Reference

Every option the typst-render extension accepts.

The complete typst-render configuration: the global options, the per-block options, output control, and the interactions to know about.

Enabling the filter

filters:
  - typst-render
Important

Reference it by name, with no at: stage. It registers itself at the several stages it needs, and pinning it to one breaks cross-referencing and the math: typst takeover.

Caution

A ```{typst} block looks like an executable cell to Quarto’s engine detection, which then selects Jupyter and fails for want of a kernel. Set engine: markdown on any document that uses one; the repository’s own example.qmd does.

Global options

Set under extensions.typst-render.

Options under extensions.typst-render.
Option Default Description
format auto png, svg, pdf, or html. html gives semantic markup with MathML maths, needs Typst 0.15, and falls back to SVG.
math Set to typst to render every equation in the document as Typst maths rather than LaTeX. Quarto numbering and cross-references keep working.
dpi 144 Pixels per inch, for PNG.
width, height auto Page size for compilation. Ignored with output: asis.
margin 0.5em Page margin, or block inset with output: asis.
background none Page fill, or the block fill with output: asis. A Typst colour, auto to read _brand.yml, or a map with light and dark keys.
foreground Text fill for the compiled image, taking the same three shapes.
preamble Typst code, or paths to .typ files, prepended to every block.
root Root directory for compilation. Global only.
font-path, package-path Extra fonts, and a package directory for offline builds. Global only.
input Key-value pairs passed as --input, readable through sys.inputs.
cache true Cache compiled images between renders.
cache-refresh false Remove stale cache files after each render.
output-directory ./assets/typst-render Where saved images are written, relative to the document, under a subdirectory named after it. An empty string writes none, leaving them in the render cache where a deployed site cannot reach them.
output-source false Also write the compiled Typst source beside each image.

Per-block options

Written as //| key: value at the top of a block.

Options accepted on a block.
Option Default Description
format The output format for this block alone: png, svg, pdf, or html.
echo false Show the source alongside the output. fenced includes the block markers.
code-fold false Collapse the echoed source into a <details>. show renders it open. HTML only.
code-summary Code The summary text for that <details>.
code-line-numbers false Highlight lines of the echoed source. A string such as 1|3-4 steps through them in RevealJS.
eval true Whether to compile at all.
include true Whether to embed the result. false still compiles and writes files.
output true Whether to show the result. asis passes the code through natively in Typst output.
output-location RevealJS placement: fragment, slide, column, column-fragment.
classes CSS classes for the image element, such as r-stretch.
pages all Which pages of a multi-page result to include: 1, 1-3, 2,5, 3-.
layout-ncol Arrange multi-page output in this many columns.
align left, center, right, or default.
label, cap, alt Cross-reference label, caption, and alternative text.
file, output-filename Compile an external .typ file, and name the written image.

The two tables are one set of options read at two levels. Everything in the first can be set on a block, apart from math, root, font-path, and package-path, which are global only. Everything in the second can be set globally as a default for every block, apart from file, output-filename, label, cap, and alt, which belong to a block alone.

Inline expressions

A red word `{typst} #text(red)[hello]` in a sentence.

An inline expression takes the global options that shape the compilation, format, dpi, background, foreground, preamble, input, cache, output, eval, include, classes, output-directory, and output-source among them. Its image is written as typst-inline-<N>.<ext>, numbered in document order, beside the block images in <output-directory>/<document>/. The options that describe a block are ignored: echo and its companions, label, cap, file, output-filename, pages, layout-ncol, align, and output-location.

eval: false leaves the expression as inline code, since there is no source listing to fall back on. include: false compiles and writes the image, then leaves the expression out of the sentence.

The compilation options can also be set on one expression, as attributes:

A big red `{typst} $pi r^2$`{format="png" dpi="300" foreground="#ff0000"} in a sentence.

format, dpi, background, foreground, cache, classes, preamble, and input are accepted there, along with alt. Anything else is ignored; where images are written stays a global decision.

Alt text is given the same way:

The area is `{typst} $pi r^2$`{alt="pi r squared"}.

Without it, the Typst source is used as the alt text.

An inline expression sets its own width, height, and margin so the result sits on the text baseline, and ignores the values configured for blocks. With output: asis in Typst output it is passed through instead, scoped in #[ ... ] with the preamble and colour bindings ahead of it, so a #let or #set inside stays local to the expression. Every other writer compiles an image, as it does for a block.

When background or foreground carries both a light and a dark value, an expression in HTML output is compiled twice and both images are emitted, marked with Quarto’s light-content and dark-content so the page shows the one matching its mode.

Interactions

Caution

code-window claims ```{typst} blocks at pre-quarto and rewrites them into decorated code blocks, so this filter never sees them and no figure is produced. Do not run both on the same document.

Limitations

  • Inline Typst is not available in PowerPoint: Pandoc cannot put an image inside a run of text there. Blocks work normally.
  • engine: markdown is required on documents containing {typst} blocks.
  • format: html needs Typst 0.15 or later, and falls back to SVG below that.
Back to top