Apex now has a --mode quarto option aimed at Pandoc/Quarto-style markdown for HTML output. This is not a Quarto replacement — you are not getting cell execution, project rendering, or PDF output from Apex alone. What you do get is a sensible HTML path for .qmd-style documents without running the full Quarto toolchain.

Getting started

From the command line:

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

Or set it in YAML front matter:

title: My Doc
mode: quarto

Quarto mode inherits unified-family defaults, turns on Quarto-specific preprocessors, and keeps unsafe HTML enabled (needed for raw blocks and diagram fences).

What syntax is covered

Here is the Pandoc/Quarto surface area Apex handles today.

Callouts and divs

::: {.callout-note}
Quarto callout note body.
:::

::: {.border}
Bordered div content.
:::

::: {.hidden}
This content is hidden in standalone HTML output.
:::

Bracketed spans and figures

[smallcaps text]{.smallcaps}
[underlined text]{.underline}
[highlighted text]{.mark}

![Caption](elephant.png){fig-alt="Alt text"}

The fig-alt attribute maps to the image alt while the markdown alt text becomes the caption.

Raw content

Block and inline Pandoc raw syntax:

```{=html}
<strong>raw html</strong>
```

Text `<span class="x">inline</span>`{=html} after.

Non-HTML formats like {=latex} are preserved in HTML comments rather than rendered.

Lists

Example lists with (@) markers, roman lists with i) / ii), and line blocks:

(@)  My first example will be numbered (1).
(@)  My second example will be numbered (2).

i) Alpha
ii) Beta

| Line one
|   preserved spaces
| Line three

Empty fenced divs reset list numbering between blocks:

1. First

::: {}

1. Second

Code fences with attributes

```{.python filename="run.py" linenos=true}
print("hello")
```

Attributes land on the rendered <pre> as data-* keys. Per-block linenos=true can turn on line numbers even when global highlighting line numbers are off.

Diagram fences

```{mermaid}
flowchart LR
  A --> B
```

```{dot}
digraph { A -> B; }
```

These become <pre class="mermaid"> or <pre class="graphviz"> blocks. Standalone output auto-injects mermaid.js when mermaid diagrams are present and you have not already added a mermaid script.

Shortcodes (core shim)

A thin preprocessor handles a small set of Quarto shortcodes before parsing:

{{< pagebreak >}}

Press {{< kbd $@3 >}} to save.

{{< include chapter.md >}}
  • pagebreak becomes page-break HTML
  • kbd becomes <span class="keycombo separated" title="..."><kbd class="key symbol">...</kbd></span> for the kbd plugin
  • include becomes Apex include syntax (<<[chapter.md])

Unknown shortcodes pass through unchanged. Set APEX_VERBOSE=1 to log warnings about unrecognized names.

Cross-references and citations

Cross-ref tokens are wrapped for styling, not resolved:

See @fig-elephant and @sec-intro for details.

That becomes <span class="quarto-xref">…</span> in the output. You do not get “Figure 1” links or automatic numbering from Apex.

Citations use Apex’s existing Pandoc citation support, which is the same syntax Quarto uses:

bibliography: references.bib


See [@doe99] for background.

When quarto-xrefs is on (the default in quarto mode), bare @fig-… / @sec-… tokens are not mistaken for author-in-text citations. Bracketed [@key] citations still work normally.

Metadata toggles

Individual preprocessors can be turned off in YAML for debugging or partial compatibility:

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-xrefs: true
quarto-strict-lists: false

Test fixtures

Examples live in the Apex repo under tests/fixtures/quarto/ — start with smoke.md and the topic-specific files (callouts.md, lists.md, diagrams.md, and so on).

What is not covered (yet)

Apex is an HTML-oriented renderer, not Quarto. These are intentionally out of scope or only partially supported:

  • Executable cells — no {python} chunk execution
  • Cross-ref resolution — @fig-id is marked up, not linked or numbered
  • Quarto project/site rendering — no _quarto.yml pipeline
  • Multi-format output — no native PDF, Typst, or Word from Apex alone (use Pandoc integration for that)
  • Conditional content and computed shortcodes — not implemented in core
  • Most shortcodes — only pagebreak, kbd, and include in core; things like {{< video >}} need plugins
  • Full Quarto CSL/bibliography parity — Apex has its own citation/bibliography path; it works with Quarto citation syntax, not Quarto’s entire reference engine
  • Typst/raw {=typst} compilation — preserved, not compiled

If you hit syntax that works in Quarto but not in Apex, that is useful feedback — especially edge cases around lists, divs, tables, and shortcodes.

Testers welcome

Quarto mode landed across several development phases and has a solid test suite, but real .qmd documents are the best stress test. If you try --mode quarto on your own files, please report anything that looks wrong.

Open issues with bug reports/feature requests.

Include a minimal markdown sample, the command you ran, and what you expected versus what you got. The more reproducible the report, the faster I can fix it.

Wiki docs for quarto mode live in the Apex wiki as Quarto Mode if you want the reference-style version of this post. If you’re new to Apex and want to try it out and help test this new mode, see the installation instructions.