markdoc-pdf 0.11.1

Render Markdoc documents to PDF, as a CLI or a library
Documentation
# Getting started — markdoc-pdf for tech writers

A 5-minute tour. By the end of it you'll have a working `.mdoc`
source, a chosen style, and a generated PDF.

If you don't yet have the `markdoc-pdf` binary installed, see
[INSTALL.md](INSTALL.md) first.

## 1. Make a project folder

A markdoc-pdf project is just a folder with the source `.mdoc`
alongside any media it references:

```
my-doc/
├── intro.mdoc
└── images/
    ├── logo.svg
    └── diagram.png
```

That layout — source at the top, media in a sibling folder — is the
default markdoc-pdf assumes. The `--assets-root` flag overrides it
when you need something else.

## 2. Write your first `.mdoc`

Create `my-doc/intro.mdoc`:

```markdown
---
title: Coffee Brewing Guide
description: Pour-over basics for the home barista
authors:
  - Aki Tanaka
  - Maria Linde
language: en-us
releaseDate: "2026-05-03"
---

# Pour-over essentials

Pour-over coffee is **deceptively simple**: hot water, ground beans,
a filter, and a few minutes of attention.

## What you need

- A *gooseneck* kettle for controlled pouring
- Medium-coarse grind, around 20 g for a single cup
- 92–96 °C water (just off the boil)

## The basic recipe

1. Bloom: add 40 g of water, wait 30 s.
2. First pour: spiral out to 150 g over 30 s.
3. Second pour: bring it to 320 g over another 60 s.
4. Drawdown finishes around 3:00 to 3:30 total.

![A clean v60 setup](images/diagram.png)

> Tip: if it tastes sour, grind finer; if it tastes bitter, grind
> coarser. Adjust one variable at a time.
```

Things to notice:

- **Frontmatter** (the YAML between `---` lines) drives the PDF
  metadata and template variables like `{title}` and `{date}`. None
  of the fields is required, but `title` matters for ToC pages and
  the cover page.
- **Markdown** works as you'd expect — `**bold**`, `*italic*`,
  `[link text](url)`, lists, blockquotes, fenced code blocks (with
  optional language for syntax highlighting), tables.
- **Markdoc tags** look like `{% tag %}…{% /tag %}`. The most useful
  for writers right now: `{% callout %}`, `{% caption %}`, `{% media src="…" /%}`,
  `{% footnote %}`, and the layout / form tags `{% columns %}`,
  `{% float %}` and `{% input %}`. See *Markdoc tags* below.

## 3. Pick a style

Styles live in `markdoc-pdf/examples/themes/`. Pick one that matches
the document type:

| You're writing… | Try… |
|-----------------|------|
| Product manual | `technical-manual.style.toml` |
| Academic paper | `academic-paper.style.toml` |
| Internal review draft | `draft-report.style.toml` |
| Letter / memo | `letter.style.toml` |
| Book | `book.style.toml` |
| Changelog | `release-notes.style.toml` |
| Sales whitepaper | `whitepaper.style.toml` |
| One-page reference card | `cheatsheet.style.toml` |

You can also omit `--style` entirely — the built-in default (A4,
Noto Sans, no decoration) is a fine starting point.

## 4. Render

From inside `my-doc/`:

```sh
markdoc-pdf \
    --input intro.mdoc \
    --output intro.pdf \
    --style /path/to/themes/technical-manual.style.toml
```

That writes `intro.pdf` and prints `wrote intro.pdf (… bytes) from intro.mdoc`.

If something is wrong with your input, you'll get a single-line
`error: …` plus a `hint: …` follow-up. Common ones:

- `error: input file not found: …` — typo in the path.
- `error: couldn't load style …: missing field …` — the style file
  is missing a field; copy a working theme as a starting point.
- `warning: media unavailable: …` — an `<img>` or `{% media %}`
  references a file the resolver couldn't find. The PDF still
  renders, with a placeholder where the image should be.

## 5. Iterate

The CLI is one-shot, so a typical loop is:

```sh
markdoc-pdf -i intro.mdoc -o intro.pdf -s themes/technical-manual.style.toml \
  && xdg-open intro.pdf      # or: open intro.pdf  on macOS
```

Wire it to your editor's "save and run" hook for a tight feedback
loop.

## Markdoc tags worth knowing

Tags extend Markdown with semantic markers that the renderer
interprets. The ones writers will use most:

### `{% callout %}` — note / warning / info boxes

```markdown
{% callout type="warning" %}
Don't pour boiling water — let it sit 30 s after the kettle whistles.
{% /callout %}
```

`type` accepts `note`, `info`, `warning`, `caution`, `danger`,
`success`, `notice`. Each renders as a coloured panel.

### `{% caption %}` — captions for figures and tables

Place immediately before an image or table:

```markdown
{% caption %}V60 brewing geometry — top view{% /caption %}
![…](images/diagram.png)
```

The caption gets a `Figure N:` (or `Table N:`) prefix and feeds the
List of Figures / List of Tables sections when the style enables them.

### `{% media src="…" /%}` — images with explicit alt text

Equivalent to `![alt](src)` but lets you separate `alt` and `src`
attributes — useful when alt text gets long:

```markdown
{% media src="images/diagram.png" alt="Side view of the V60 dripper sitting on a glass server, with a paper filter and ground coffee inside." /%}
```

### `{% media id="…" /%}` — references by asset id (local workflow)

Documents can reference media by an asset **id** rather than a
path:

```markdown
{% media id="0a02bb82-1a68-4c5c-883f-406361e1235e" /%}
{% img   id="0a02bb82-1a68-4c5c-883f-406361e1235e" /%}
```

In a production pipeline, the calling service may fetch the asset and rewrite
the reference to a concrete `src` (e.g. `src="file:///…/0a02bb82….webp"`)
before rendering. Otherwise markdoc-pdf resolves the id **locally**: put the
file, named `<id>.<ext>`, anywhere under your `--assets-root` — at the top
or in a sub-folder — and the renderer finds it. It first checks the root
for `<id>` with each known extension (`.webp` / `.png` / `.jpg` / `.jpeg` /
`.gif` / `.svg`, then the bare id); failing that, it searches sub-folders
by file stem. The actual format is detected from the file contents, so a
wrong extension still works. A missing id degrades to the usual placeholder
plus a `warning: media unavailable: …` line — so a writer can drop the
downloaded assets into a folder (nested however they arrive) and preview a
real document without changing its `id=` references. `{% img %}` is
an alias of `{% media %}`, so both spellings resolve identically.

### `{% footnote %}` — inline footnotes

```markdown
The Treaty of Westphalia{% footnote %}Signed in 1648, ending the Thirty Years' War.{% /footnote %} is widely cited.
```

Numbers are auto-assigned. Bodies appear in the per-page footnote
pool at the bottom of the page. Configure separator/font/spacing in
the style's `[footnote]` section.

### `{% tag id="name" %}` and `{% tagref id="name" %}` — cross-references

```markdown
## Configuration {% tag id="config" %}

…

For details see the {% tagref id="config" %} chapter.
```

`{% tagref %}` becomes a clickable link in the PDF. Every heading
also gets an auto-assigned anchor (`__heading_<n>`) so the ToC and
List of Figures entries are linkable.

### `{% columns %}` and `{% float %}` — side-by-side and wrapped layout

`{% columns %}` places its children in side-by-side columns (equal, or
uneven via `widths="2 1"`), optionally centred (`align="center"`) on a
`background` panel; `{% grid %}` reflows the same cells into as many equal
columns as fit, wrapping into rows; `{% float %}` floats an image to one
side with the following content wrapping around it — and with inline
`{% media side="…" /%}` markers becomes a magazine-style wrap around several
images. Worked examples:
[`examples/columns-and-grid.mdoc`](examples/columns-and-grid.mdoc) and
[`examples/float.mdoc`](examples/float.mdoc).

### `{% input %}` — print form fields

A labelled, ruled form field for printable forms — `type` (`text`,
`number`, `email`, `date`, `checkbox`, …), `required`, `min`/`max`,
`minlength`/`maxlength`. It renders as pure graphics (label + box sized by
`maxlength`), so it stays PDF/A-safe; the constraints are printed as a hint
for whoever fills it in by hand. See
[`examples/form.mdoc`](examples/form.mdoc).

## Composing a book from `sections`

A large manual doesn't have to live in one file. Give the root document a
`sections` manifest in its frontmatter — an ordered tree of
`[section, [subsection, …]]` file paths — and each file is stitched into one
book, in order, when you render the root:

```yaml
---
title: Acme Robot
documentNumber: 4100237
sections:
- - "intro"           # → intro.mdoc
  - []
- - "safety/overview" # → safety/overview.mdoc
  - - "safety/messages"
    - "safety/precautions"
- - "operation"
---

# Copyright {% tag numbered="false" /%}
{% toc /%}
```

Paths resolve against the root file's directory (a leading `/` is treated as
root-relative, not absolute; extensionless paths get `.mdoc`/`.md`). Each
section file's own frontmatter is dropped, so the root's title / version /
document number govern the whole book — and heading numbering, the ToC, the
running header, the footer, and the last-page QR all span the composed
whole. It's built on the same inclusion machinery as `{% partial %}`
(recursive, cycle-detected).

## Where to next

- The full set of style knobs (margins, fonts, colours, headers,
  footers, watermarks, coverpage, hyphenation, custom font loading)
  lives in [`examples/themes/README.md`]examples/themes/README.md.
- For the full Markdoc tag/schema reference, see the parent
  `markdoc/` crate's documentation.
- The frontmatter fields the renderer reads are `title`, `description`,
  `authors`, `creator`, `language`, `releaseDate`, `updateDate` and
  `sections` (`src/frontmatter.rs`), and any list of maps the style turns
  into a table (`[frontmatter_tables]`). Every other field is still
  available to templates as `{name}`.