Quarto Mode

Quarto Mode

Command: apex --mode quarto document.qmd

Quarto mode targets Pandoc/Quarto markdown for HTML output. It is a unified-family mode with Quarto-specific preprocessors enabled by default.

Quick start

apex document.qmd --mode quarto --standalone
apex document.qmd --mode quarto --standalone --script mermaid

Metadata:

---
title: My Doc
mode: quarto
---

Enabled by default

Compared to unified mode, Quarto mode:

• Enables Quarto callouts, fenced divs, and bracketed spans
• Enables Pandoc/Quarto preprocessors (raw content, lists, code fence attrs, diagrams, shortcodes)
• Disables Marked-specific extensions, wiki links, and index syntax
• Keeps unsafe HTML enabled (required for raw content and diagram blocks)

Feature overview

Feature	Syntax	Notes
Callouts	::: {.callout-note}	See Callouts
Bracketed spans	[text]{.smallcaps}	Semantic CSS in standalone output
fig-alt	{fig-alt="Alt"}	Maps alt text to <img alt>
Raw content	```{=html} / `{=html}`	Requires unsafe
Example lists	(@) Item	Pandoc example list markers
Roman lists	i) Item	lower-roman styling
Line blocks	| Line	Preserves spacing
Code fence attrs	```{.python filename="x.py"}	data-* on <pre>
Diagrams	```{mermaid} / {dot}	<pre class="mermaid">; auto mermaid.js in standalone
Shortcodes	{{< pagebreak >}}, {{< kbd >}}, {{< include >}}	Thin core shim; kbd uses Plugins
Cross-refs	@fig-id, @sec-id	Wrapped in <span class="quarto-xref"> (display only; no resolution)
Hidden divs	::: {.hidden}	Hidden via standalone CSS

Out of scope

Apex does not implement Quarto's full engine. These remain out of scope:

• Cell execution, project/site rendering, conditional content
• Cross-ref resolution (@fig-… is marked up, not linked)
• CSL/bibliography pipeline (use Apex citations separately if needed)
• PDF/Typst/Word multi-format output (use Pandoc Integration)

Per-feature metadata toggles

Individual preprocessors can be toggled in YAML:

quarto-extensions: true
quarto-raw: true
quarto-list-continuation: true
quarto-line-blocks: true
quarto-roman-lists: true
quarto-code-attrs: true
quarto-diagrams: true
quarto-shortcodes: true
quarto-callouts: true
quarto-xrefs: true
quarto-strict-lists: false

Set a key to false to disable that preprocessor while keeping --mode quarto.

Shortcodes and plugins

Core converts a small set of Quarto shortcodes before parsing:

• {{< pagebreak >}} → page break HTML
• {{< kbd ... >}} → {% kbd ... %} (render with the kbd plugin)
• {{< include file.md >}} → <<[file.md]> include syntax

Other shortcodes (e.g. {{< video >}}) should be handled by plugins. Unknown shortcodes pass through unchanged; set APEX_VERBOSE=1 for warnings.

Test fixtures

Examples live under tests/fixtures/quarto/ in the Apex repository:

• smoke.md — integration smoke test
• callouts.md, spans.md, raw-content.md, lists.md, code-attrs.md, diagrams.md, shortcodes.md

Related

• Modes — all processor modes
• Command Line Options — --mode quarto
• Callouts — Quarto callout syntax
• Plugins — extending shortcodes and syntax