markdoc-pdf 0.11.1

Render Markdoc documents to PDF, as a CLI or a library
Documentation
# Examples

Two kinds of things live here:

- **Single-feature style demos** — tiny `.style.toml` files that
  illustrate one knob at a time (`small`, `pdfa`, `toc`, …). Useful
  as copy-paste starting points when authoring a real theme.
- **Source fixtures** — `rich.mdoc` and the assets it references.
  Used by the CI smoke-test and by everything below as the input
  document.

Ready-to-deploy themes (manuals, papers, posters, …) live one
directory deeper in [`themes/`](themes/README.md) — start there if
you want a finished look rather than a feature reference.

## Quick render

From the `markdoc-pdf/` directory after building the binary
(`cargo build --release`):

```sh
./target/release/markdoc-pdf \
    --input  examples/rich.mdoc \
    --output rich.pdf \
    --style  examples/themes/technical-manual.style.toml \
    --assets-root examples
```

Swap `--style` for any of the files below to see a single feature in
isolation.

## Style demos

Every file in `examples/*.style.toml` is a *partial* style — it only
sets the fields it cares about; everything else inherits from the
built-in default (A4, Noto Sans, no decoration). That makes them
small and readable.

| File | Demonstrates |
|------|--------------|
| `small.style.toml` | Tiny page height (300 pt). Forces pagination on `rich.mdoc`. |
| `letter.style.toml` | US Letter geometry, header / footer with template variables, custom callout colours. The most complete "real-world" example. |
| `toc.style.toml` | Just a table of contents at the start. |
| `full-toc.style.toml` | ToC + List of Figures + List of Tables — three front-matter sections. |
| `abbrev.style.toml` | Abbreviated caption prefixes (`Fig.` / `Tab.`) plus LoF and LoT. |
| `below.style.toml` | Caption positioned **below** the figure / table instead of above. |
| `copyright-footer.style.toml` | Three-slot footer (copyright left, confidentiality + title centre, page-of-total right). Reference for footer authoring. |
| `link-style.style.toml` | `[link]` block exercising all four knobs (`color`, `italic`, `bold`, `underline`). Renders links in bold italic purple with an underline. |
| `decorations.style.toml` (+ `decorations.mdoc`) | Every inline text **decoration** in one document: bold, italic, strikethrough, `inline code` (monospace), links (coloured + underlined via `[link]`), and `{% color %}` spans — shown alone, mid-paragraph, and combined. The style only enables link underlining so all decorations are visible together. |
| `callout-styles.style.toml` | Every callout-related knob spelled out: `callout_padding`, `callout_accent_width`, `callout_space_after`, plus per-severity `[callout_styles.<kind>]` blocks for all seven kinds. Values match the built-in defaults — copy and edit. |
| `coverpage.style.toml` (+ `coverpage.mdoc`) | Synthesised cover page: large title at the top, hero image below (`logo_position = "below_title"`), then subtitle / authors / publication date. Renders against `coverpage.mdoc`, which carries the rich frontmatter the cover page needs. |
| `badges.style.toml` (+ `badges.mdoc`) | Ordered-list circle badges via `[list_marker]`: numbers in filled circles, with `ordered_sequences` cycling `decimal` → `lower-alpha` as the list nests (1 → a). |
| `table-borders-{grid,horizontal,none}.style.toml` (+ `table-borders.mdoc`) | The three `table_borders` modes — a full grid, horizontal row rules only, or none. Render `table-borders.mdoc` with each to compare. |
| `table-styling.style.toml` (+ `table-styling.mdoc`) | Styling tables *differently within one document*: a document-wide table style (incl. zebra striping via `table_stripe_color`) plus per-table overrides on the list-syntax `{% table %}` (a pipe table wrapped in the tag does not take its attributes: Markdoc leaves such a table as it is) with `borders`, `border_color`, `edge_color`, `header_background`, `stripe` (colour or `none`), `column_weights`, `cell_padding`, and `header_column` (make column 0 row headers) attributes. |
| `table-forms.style.toml` (+ `table-forms.mdoc`) | The table *forms* this renderer supports: a plain pipe table, a header-less table (blank header row dropped), a header column (a list-syntax `{% table header_column=true %}`), and per-column text alignment via CommonMark `:---` / `:-:` / `---:` delimiter markers. |
| `table-list-syntax.mdoc` (+ `table-forms.style.toml`) | The Markdoc **list-syntax** `{% table %}` (cells as `*` items, rows separated by `---`): basic, header-less (leading `---`), rich content (code, lists, and `{% list type="checkmark" %}` in cells), column / per-cell alignment via `{% align %}`, and `{% colspan=N %}` / `{% rowspan=N %}` (merged columns and rows). Builds the same table structure as a pipe table. |
| `columns-and-grid.mdoc` | The two multi-column layout primitives. `{% columns %}` — a fixed row of equal or uneven (`widths="2 1"` / `widths=[2, 1]`) columns of images (or any blocks); each column is a list item (`*`) or a blank-line-separated block, `gap` sets the spacing, `align="center"` centres each cell's content, `background="#…"` paints a panel behind the row, and a per-column `{% caption %}` (loose-list form) can sit above or below (`position="below"`) and be tinted with `color="#…"` (or the document-wide `caption_color` style field). A `widths="2 1 2"` row of text / image / text (+ `figure.svg`) centres a figure with independent commentary flanking it on both sides. `{% grid %}` — the same cells *reflow* into as many equal columns as fit at `min` points wide (default 120), wrapping into rows (the print analogue of CSS `repeat(auto-fill, minmax(min, 1fr))`); each row is atomic, so a figure never splits from its caption across a page. Images also render inside ordinary table cells. Render with `--assets-root examples`. |
| `swatch.mdoc` | Block colour bars via `{% swatch %}` — solid (`color="#…"`) or a linear `gradient="[Ndeg,] stop, stop, …"` (evenly spaced stops unless one carries an `NN%` position; `transparent` allowed), sized by `height` / `radius`. The block sibling of the inline `{% color %}`, rendered as a synthesised SVG so gradients need no assets. Shown standalone and as an indicator key — a `{% swatch %}` bar over a bold title and a grey description in each `{% grid %}` cell. Also `{% chip %}`, the inline sibling: a small colour dot (or `shape="square"`) that flows in running text, handy as a compact legend. |
| `qr.mdoc` | QR codes via `{% qr %}` — encodes `value`, which can be a URL, arbitrary text, or a frontmatter field read as `$markdoc.frontmatter.documentNumber`. `size` (points), `ecl` (error correction: `low` / `medium` / `quartile` / `high`), `color` / `background`, `quiet_zone` (modules), and `align`. Drawn as crisp vector (a synthesised SVG). Covers the document-number-on-the-last-page pattern for production scanning. |
| `document-history.mdoc` (+ `document-history.style.toml`) | A `{% document-history /%}` tag — a revision table drawn from the `documentHistory` frontmatter (`{version, date, description}` entries), so the change log is authored once in metadata and rendered consistently. The tag is the style's, not the renderer's: `document-history.style.toml` names it, the list, the *Document history* heading and the columns under `[frontmatter_tables]`, and without that style the tag renders nothing. Shows the heading, a `title=` override, and (in the prose) `title=""` for the table alone. Render with `--style examples/document-history.style.toml`. |
| `status-lights.mdoc` | A worked status-light legend built from the primitives — a `{% grid %}` of `{% swatch %}` bars (solid colours plus pulsing / blinking / fading gradients) over bold labels and grey `{% color %}` descriptions. Shows how `{% grid %}` and `{% swatch %}` compose into a real, reflowing status-indicator key. |
| `book/` (directory) | A composed multi-file manual. The root `book/book.mdoc` carries a `sections` manifest in its frontmatter, which stitches the chapter files (`intro`, `safety/*`, `specifications`, `operation`, `reference`) into one PDF, sharing the root's title / version / document number. Doubles as a full content showcase: cover, ToC, auto-numbered headings, callouts, blockquotes, every list kind, striped and list-syntax tables, captioned figures, image thumbnails, a figure grid, swatches / chips, columns, a highlighted code block, a footnote, a `{% float %}`, and QR codes — including the last-page document-number stamp. Render with `--input examples/book/book.mdoc --style examples/book/book.style.toml --assets-root examples`. |
| `float.mdoc` (+ `figure.svg`) | Content wrapping around an image with `{% float %}` — a `side="left"` (default) or `side="right"` image that the following content wraps beside, then flows full-width below once it clears the image. `width` sizes the image (a fraction ≤ 1 of the column, an explicit point value, or a `"NN%"` string; default 40 %) and `gap` sets the space to the content. The wrap keeps its real structure: a paragraph reflows around the image, while lists, `inline code`, code blocks and callouts render as themselves, and footnotes / anchors inside the wrap are preserved. Give each `{% media %}` an explicit `side` and drop it inline, and the region switches to the **magazine** mode: several images floated to either side, anchored where they appear, with one continuous prose stream wrapping around all of them (narrowing left, right, or into the channel between overlapping floats). The whole float is one indivisible unit — it never straddles a page break (moves to the next page if it won't fit). Use `{% columns %}` instead when you want fully independent side-by-side lanes. Render with `--assets-root examples`. |
| `form.mdoc` | Print form fields via `{% input %}` — a label above a ruled box (sized by `maxlength`; a small square for `type="checkbox"`), a red required marker, and a grey hint spelling out the type / length / value constraints (`text`, `number`, `email`, `date`, `min`/`max`, `minlength`/`maxlength`). Pure graphics, so PDF/A-safe — no interactive widget, which PDF/A forbids. The same tag is a native validated `<input>` on the web. |
| `image-formats.mdoc` (+ `sample.jpg` / `sample.gif` / `sample.webp`) | The supported raster image formats, one labelled tile each: JPEG, GIF (static — an animated GIF renders its first frame), and WebP. The format is detected from the file's bytes, not its extension. PNG and SVG render identically and appear in the other examples. Render with `--assets-root examples`. |
| `fonts.mdoc` (+ `fonts.style.toml`) | **A different typeface for each part of one document.** Serif body, sans h1–h3, monospace code, plus independently-set ToC, running header and footer, and a per-kind callout font. `h4`–`h6` and the `warning` callout deliberately set nothing so the page shows inheritance and override side by side: an element's own `font_families` wins, otherwise `body_font_families`, otherwise the bundled Noto set. Every list is a fallback chain (Liberation → DejaVu → Noto), and families that aren't installed are skipped silently, so the contrast survives on a machine missing the first choice. Render with `--style examples/fonts.style.toml`. |
| `scripts.mdoc` | Non-Latin and **bidirectional** text. Fonts are chosen per character from a fallback list, so one document mixes writing systems freely: a greetings table plus paragraphs in Chinese / Japanese / Korean (CJK), Arabic and Hebrew (right-to-left — shaped into joined forms and reordered, including an RTL phrase inside an LTR sentence), Devanagari (Hindi), Thai, Greek and Cyrillic. Needs the matching Noto fonts installed (`Noto Sans CJK`, `Noto Sans Arabic`, `Noto Sans Hebrew`, `Noto Sans Devanagari`, `Noto Sans Thai`); any that are missing fall through to the next family. Renders with the default style. |
| `a5-pamphlet.style.toml` (+ `a5-pamphlet.mdoc`) | A5 portrait pages (148 × 210 mm) sized to be imposed two-up onto an A4 sheet and folded into a saddle-stitch pamphlet: tighter margins, smaller body font, and a centred page-number footer (bare front cover via `skip_first_page`). The renderer makes the A5 *pages* only — `impose.sh` (below) wraps render → `pdfbook2` into fold-ready A4 sheets, since imposition is not a renderer feature. |
| `pdfa.style.toml` | One-liner: `pdf_export = "a2_b"`. Switches to PDF/A-2B output. |
| `ua1.style.toml` | One-liner: `pdf_export = "u_a1"`. Switches to PDF/UA-1 (accessibility) output. |

## Pamphlet imposition

`impose.sh` turns the A5 pamphlet — or any A5 `.mdoc` — into a
fold-ready A4 booklet. It renders the A5 pages, then runs `pdfbook2`
to reorder them and place two per sheet (padding to a multiple of four
with blanks). The renderer never imposes; that is entirely this
script's `pdfbook2` step.

```sh
examples/impose.sh                              # bundled example → a5-pamphlet-booklet.pdf
examples/impose.sh in.mdoc style.toml out.pdf   # any A5 document
```

`pdfbook2` ships with TeX Live (`texlive-pdfbook2` on Fedora,
`texlive-extra-utils` on Debian). Without it the A5 pages are still
written, and you can impose from your print dialog instead (Booklet
layout, A4 paper, duplex flipped on the **short** edge). Print
double-sided, fold, staple the spine.

## Source fixture

`rich.mdoc` exercises most rendering paths in a single document:
headings, lists (ordered and unordered), block quotes, code with
syntax highlighting, callouts (info / warning / danger), inline and
block media (PNG + SVG + a deliberately-missing reference to test the
placeholder), a wide table, cross-references with `{% tagref %}`, and
a long-paragraph tail that forces pagination.

Its frontmatter is intentionally minimal (just `title:`) so style
demos drive the visual output rather than metadata.

The referenced assets:

| File | Used for |
|------|----------|
| `swatch.png` | Raster image referenced via `![…](swatch.png)`. |
| `swatch.svg` | SVG referenced via `{% media src="swatch.svg" /%}`. |

Pass `--assets-root examples` so the renderer resolves these relative
to this directory.