litedown: Lightweight R Markdown Implementation

Litedown uses a vendored version of cmark-gfm (GitHub's CommonMark implementation) located in src/cmark/ and src/extensions/. Instead of relying on external R packages, litedown calls this C library directly to allow for custom features and bug fixes at the C level.

Key custom extensions and bindings provided by litedown include:

• Math: LaTeX math support ($...$, $$...$$, and \begin{...}\end{...} environments).
• Subscript/Superscript/Strikethrough: Supports ^x^ (superscript), ~x~ (subscript), and ~~x~~ (strikethrough). Note that the subscript extension owns the ~ delimiter.
• Pandoc-style Attributes: Supports code block attributes like ```{.class #id key="val"}. In HTML, this renders as <pre><code class="class" id="id" key="val">.
• Raw Content Blocks: Supports ```{=html}, ```{=latex}, and ```{=tex} to emit raw content into specific output formats.
• LaTeX Footnotes: A postprocess pass that moves footnote definitions inline for LaTeX output, rendering them as \footnote{body} or \footnotemark[N] for repeats.
• R Bindings:
  • R_render_markdown(): Renders markdown to a string.
  • R_parse_markdown(): Returns a parse tree as a nested list.
  • R_code_tokens(): Returns a flat table of code blocks and inline code.
  • R_prose_lines(): Returns indices of lines not inside a code block.

To update the vendored cmark-gfm source code with a newer version from upstream, run the sync.sh script from the package root. You can sync to the latest release tag or a specific reference (tag, branch, or commit).

Steps to sync:

1. Run the sync script:

   src/patches/sync.sh          # Syncs to the latest release tag
   src/patches/sync.sh REF      # Syncs to a specific tag, branch, or commit

2. Verify the build: After syncing, the script clones upstream, copies sources, regenerates headers, and re-applies local patches. You must then build the package and run tests to ensure compatibility:

   R CMD INSTALL .
   Rscript -e 'testit::test_pkg("litedown","test-cran")'

3. Check examples: Re-render the examples to ensure the new upstream version hasn't changed the output unexpectedly:

   cd examples && CI=true Rscript _run.R

4. Resolve patch conflicts: If any local patches fail to apply, you must manually fix them or drop them if they have been merged into the upstream version.

src/patches/sync.sh          # latest release tag
src/patches/sync.sh REF      # a specific tag/branch/commit

In Litedown, you control the position of captions (for figures and tables) by the order in which you place the {.caption} div relative to the content within a container div (like {.figure} or {.table}).

• Bottom Caption (Default for Figures): Place the {.caption} div after the image/content inside the container.
• Top Caption (Default for Tables): Place the {.caption} div before the table content inside the container.
• Custom Positioning: To override defaults, simply move the {.caption} block. For example, to put a figure caption at the top, place the {.caption} div before the image within the {.figure} container.

## Default Figure (Bottom Caption)
:::: {.figure #fig:id}
![Alt text](image.png)

::: {.caption}
[](#@fig:id)
Caption text.
:::
::::

## Custom Figure (Top Caption)
:::: {.figure #fig:id}
::: {.caption}
[](#@fig:id)
Caption text.
:::

![Alt text](image.png)
::::

## Default Table (Top Caption)
:::: {.table #tab:id}
::: {.caption}
[](#@tab:id)
Caption text.
:::

| col1 | col2 |
|--:|--:|
| val1 | val2 |
::::

## Custom Table (Bottom Caption)
:::: {.table #tab:id}
| col1 | col2 |
|--:|--:|
| val1 | val2 |

::: {.caption}
[](#@tab:id)
Caption text.
:::
::::