PDF export

Sigla exports any Markdown document as a presentable, WYSIWYG PDF — same renderer, same fonts, same diagrams, same code highlighting as the screen view. There are two surfaces: the GUI preview window and the mdv export command-line subcommand.

Two surfaces

GUI — Export as PDF…

⌘⇧P (File → Export as PDF…) opens a live preview window. ⌘P (File → Print…) opens the same preview primed for print.

The preview window lets you:

• Pick a document theme (GitHub, Technical Paper, Apple Documentation)
• Pick paper size (Letter or A4) and orientation (Portrait or Landscape)
• Toggle running header and footer
• Set a custom header text (footer renders page numbers)
• Toggle “Start every H1 on a new page”

The preview updates in real time as you edit the source markdown.

CLI — mdv export

PDF is the default output format — no --to flag required:

mdv export input.md                                        # → input.pdf in cwd
mdv export input.md --theme gitHub --paper letter --no-footer
mdv export input.md --emit-diagrams ./assets/              # PDF + sidecar PNGs

Produces a PDF byte-for-byte equivalent to what the GUI’s preview would generate for the same input + same options. Drivable from make, CI, and headless Claude Code subagent use.

The --emit-diagrams <dir> flag writes each rendered diagram (Mermaid, Vega-Lite, PlantUML, Graphviz, etc.) as a standalone image alongside the PDF. Useful for embedding diagrams in other tools without re-rendering:

# Export PDF and write each diagram as a PNG sidecar in ./assets/
mdv export design.md --emit-diagrams ./assets/
# → design.pdf
# → ./assets/design-diagram-1-mermaid.png
# → ./assets/design-diagram-2-plantuml.png

Full flag reference: see CLI reference.

Themes

The PDF inherits whichever theme you pick:

Defaults are theme conventions; you can override per export.

Paper sizes

Landscape swaps width and height.

Headers and footers

• Header: free-text running header. Repeats at the top of every page. The same text is used for every page; there’s no per-section header.
• Footer: page number (“Page N of M”). The presence is controlled by the toggle; the format is fixed.

If you turn both off, the page renders edge-to-edge with no chrome.

Pagination contract

[!NOTE] Sigla intentionally never splits these elements across pages:

• Images
• Diagrams (Mermaid, Vega-Lite, PlantUML, Graphviz)
• Tables
• Short code blocks (fenced blocks that fit on a single page)

Each element gets padded forward to the next page if it would otherwise straddle a page break. The data-attribute marker data-sigla-block on rendered output is what the PDF exporter uses to identify “never split this.”

The one exception is a code block larger than a single page — that splits at line boundaries, because no amount of padding helps.

This contract is the same in both the GUI preview and the CLI export.

Image scaling

Images larger than the page content area are scaled down proportionally to fit. Images smaller than the content area render at their natural size.

[!WARNING] Very large images can cause Sigla to scale entire pages down to fit (so the page-relative position of the image is preserved). When this happens, the export prints a warning to stderr listing which page indexes were scaled. In the CLI:

warning: page 3 scaled to 0.72× to fit oversized image

If you want exact 1× rendering, downscale the source image before export.

Math, code highlighting, and diagrams

All bundled renderers carry through to PDF:

• KaTeX math — $x^2$, $$\sum x_i$$, ```math fences render to typeset math in the PDF.
• Code highlighting — fenced code blocks render with syntax highlighting matching the document theme. The dark variant activates automatically based on the export theme’s dark stylesheet pairing.
• Mermaid, Vega-Lite — built-ins; render headlessly inside the PDF generator’s offscreen WebView.
• PlantUML, Graphviz — bundled extensions; same as the GUI, including the missing-binary placeholder if plantuml or dot isn’t installed.
• Gherkin — bundled template extension; render as a styled syntax-highlighted block.
• Custom user extensions — render in PDF too, subject to the same --no-extensions and --extension allowlist flags on the CLI.

Disabling extensions for a PDF export

From the CLI:

# Hard-off: every extension fences fall back to <pre><code>
mdv export doc.md --no-extensions

# Whitelist: only plantuml runs; everything else is stripped
mdv export doc.md --extension plantuml

Useful for:

• Reproducible CI exports where you want a known-minimum surface.
• Producing a “source-only” PDF for review where diagrams are noise.
• Diagnosing whether an extension is the source of a layout bug.

[!NOTE] CI use is not formally licensed yet. Sigla’s published license is “Multi-Mac per user” (see the pricing FAQ) — there’s no separate CI-runner tier today. If you’re running mdv md-to-pdf on ephemeral CI infrastructure as part of your job, treat it as one of your Macs for now and email press@sigla.so if your use case needs a firmer answer.

The GUI export inherits the active Settings → Renderers configuration — to disable an extension for one export, toggle it off in Settings, export, then toggle back.

Where the exported PDF lives

• GUI: the export sheet asks you to pick a destination via the standard save panel.
• CLI: defaults to <input-basename>.pdf in the current working directory; override with --output <path>.

The CLI refuses to write inside the Sigla.app bundle — any other path is allowed.

Cross-references

• CLI reference — all mdv export flags, including --emit-diagrams, --json, and --to html
• Themes — built-in theme specs
• Keyboard shortcuts — ⌘P vs ⌘⇧P