Why Typst matters

Practical Quarto: Patterns, templates, and tooling @ posit::conf(2026)

Charlotte Wickham

&  

Mine Çetinkaya-Rundel

pos.it/practical-quarto-conf26

Case study

The Bureau of Regional Statistics publishes a quarterly release.

Same release, new requirement

The Bureau of Regional Statistics quarterly release. Every one must carry:

• the agency mark
• the reference period and the region
• the release status — Provisional, Revised, or Final

Last module we built all three into an HTML title block. Now it has to be a PDF.

Do not sell Typst yet. Get them to render one first.

The starter is the document without the title block work — a clean sheet, not their module 03 folder.

Your turn 1: render it as a PDF

1. Add typst as a second format in report.qmd. Keep html:

   report.qmd

   format:
     html: default
     typst: default

2. Render with Quarto: Preview Format… command and pick Typst.

3. Render the HTML too. Compare the two formats.

Exercise: 04-typst/01-first-pdf

No TeX install.

Quarto: Preview Format… — the command from this morning.

Add, don’t replace. They end holding both outputs, which is what makes step 3 possible.

Steer the comparison to the logo, and to the status with nothing marking it.

Same brand in both: Atkinson Hyperlegible, brand ink for the text, forest links.

The logo only shows up in the PDF. Brand cannot place it in a standalone HTML document — module 03 built a partial for exactly that. Here it arrives with no configuration.

The date is 2026-09-14 here and September 14, 2026 in the HTML.

{{< meta brs-release.status >}} in the Summary works in both.

Why Typst?

• Already installed. format: pdf needs a LaTeX distribution. Typst ships inside Quarto.

• Faster. Render, look, change, look again.

• Uses your brand. Colors, fonts, and the logo, from the same _brand.yml.

Typst is a binary dependency, in the same quarto check list as Pandoc.

Brand reaches none of this in LaTeX. The .tex has no trace of it.

Headings are brand ink here, not primary. Turn 3 changes that.

Two ways to reach metadata

	Last module	This module
Where you write it	title-block.html, a partial	report.qmd, the body
What you write	$brs-release.status$	{{< meta brs-release.status >}}
What it is	Pandoc template syntax	a Quarto shortcode

Pandoc’s template syntax only runs when Pandoc is filling a template.

Pandoc’s template syntax →

Quarto’s meta shortcode →

$brs-release.status$ typed in the body is just text.

Both reach a nested key with a dot.

The shortcode also works inside a raw Typst block too.

Quarto writes the Typst

.qmd → .typ → .pdf

Keep the intermediate .typ:

report.qmd

format:
  typst:
    keep-typ: true

Two renders, not one. Pandoc gets you to Typst; Typst gets you to PDF.

The middle file is normally deleted. Keep it and you can read it, and errors point into it.

Your content translated to Typst

report.typ

= Summary
<summary>
This is a Provisional release covering Oregon for the reference period Q3 2026.

Total employment in the region rose by 4,300 jobs over the quarter, an increase of 0.4%. Sector detail is in #ref(<tbl-sectors>, supplement: [Table]), and the full method is in the #link("https://example.gov/brs/methods")[methodology notes].

#strong[All figures in this release are #emph[provisional].]

#quote(block: true)[
Benchmarking aligns the survey estimates with the annual census of employment.
]

Template contributes 431 lines above it…

Every line above 432 came from the template and its partials, or from the brand.

475 lines in total for a two-page release.

Scroll up through it live. Do not read it out — just show the scale, then land on #show: doc => article( and brand-color.

Template: format: typst

The boilerplate, in order. Their content is the box in the middle.

Typst syntax

Text is content

badge.typ

Provisional

A .typ starts in markup mode. Text is text.

= is a heading, - a list item. Typst has *bold* and _italic_ too — Pandoc just does not use them.

# switches into code

badge.typ

rect()

badge.typ

#rect()

Empty parentheses: a call with no arguments.

Typst: rect →

One character is the whole difference. Without the # you get the characters rect() back as text.

The docs page for rect is the next two slides, ahead of time.

Arguments go in the parentheses

badge.typ

#rect(fill: green)

Named arguments. A function’s reference page is a list of these.

green is built in.

Use [] to pass content arguments

badge.typ

#rect(fill: green)[Provisional]

This is the same call:

#rect(fill: green, [Provisional])

Typst: trailing content blocks →

[...] is a content block. The box now has something in it.

Typst calls the [...] after the parentheses a trailing content block, and you will see both spellings in the docs.

With nothing else in the parentheses they can go too: #rect[Provisional]. A function can even take several trailing blocks — #enum(start: 2)[A][B].

Your turn 2: read the Typst

1. Render, then open report.typ. Scroll down to = Summary — everything below it is your content.

2. Find a call — it starts with #.

3. Search for the function in the Typst reference. Say in plain words what it does, and whether any arguments are being passed to it.

4. Again, with another one.

Exercise: 04-typst/02-read-the-typ

All four are in the first section: #ref, #link, #quote, and a #strong with an #emph nested inside it.

Arguments vary on purpose — #strong takes none, #quote(block: true) takes a named one, #link and #ref take one unnamed and then content.

Collect two or three out loud. The reference being readable is the point, not finishing.

You can nest content and calls

badge.typ

#rect(fill: green)[
  #text(fill: white)[Provisional]
]

They just met this in their own file — #strong[... #emph[provisional] ...].

Inside [...] you are back in content mode, so the second # does the same job as the first.

This is the shape the status badge needs.

Writing Typst in a .qmd

A raw block passes straight through:

report.qmd

```{=typst}
#rect(fill: green)[Provisional]
```

Lands in report.typ untouched. Every other format ignores it.

Same mechanism as {=html}. The = means “this is already in the target language, do not translate it”.

Render this document to HTML and the block is dropped, silently.

This is how the status badge gets into the document.

The release status badge

report.qmd

```{=typst}
#rect(fill: brand-color.primary, radius: 3pt)[
  #text(fill: white)[
    {{< meta brs-release.status >}}
  ]
]
```

Read it inside out: take the status, make it white text, put it inside a primary-coloured rectangle.

Everything from the last section, one step each: a call, an argument, a content block, and a call inside it.

brand-color.primary instead of a hex code, and {{< meta >}} instead of $status$.

This block is in the next exercise folder already.

Set and show rules

Every element has a function

Even if not explicitly called, all layout and styling happens with functions:

Element	Its function
Text	text()
Heading	heading()
Paragraphs	par()
Page	page()

Nothing is exempt. Provisional on its own is a text element — we just never named the function.

Typst’s own word for these is element function, and its docs say every one of them can be customised with set and show rules. That is the next two slides.

Their .typ already has set par, set text, set heading and set page, all written by Quarto from the YAML and the brand.

A set rule changes the default

styles.typ

Provisional

#set text(fill: brand-color.primary)

Provisional

From here on, not everywhere. The first one was already rendered.

#set f(arg: value) — the arguments are the function’s own.

Adding show scopes it to an element

styles.typ

#show heading: set text(fill: brand-color.primary)

= Summary

Ordinary text here

== Manufacturing

A show-set rule: the show keyword, a selector, a colon, then a set rule.

Typst: styling →

Read it as: wherever a heading appears, apply this.

Nothing had to be marked up — show finds the elements itself.

.where() narrows the selector

styles.typ

#show heading.where(level: 1): set text(fill: brand-color.primary)

= Summary
== Manufacturing

Same rule, narrower selector. heading.where(level: 1) is still the heading function, with a filter on it.

Careful: Quarto shifts levels down by one, so a markdown ## is Typst level 1.

Your .typ is already full of these

report.typ

#set page(
  paper: "us-letter",
  margin: (x: 1.25in, y: 1.25in),
  numbering: "1",
  columns: 1,
)

#set text(fill: brand-color.foreground)
#show heading: set text(font: ("Atkinson Hyperlegible",), weight: 600, )
#show link: set text(fill: rgb("#1b5e4f"), )

The page block is page.typ, filled from defaults you never set.

The brand lines are the module 03 callback — brand was unreachable from an HTML partial, and here it is, in scope, in the body. Yours can say brand-color.primary instead of a hex code.

Your turn 3: set and show rules

In report.qmd, add a new raw block above the badge, so the rules apply to everything below.

1. Write a set rule to loosen the paragraphs — par has a leading argument. par →

2. Write a show-set rule to centre the section headings. align →

3. Challenge: step 2 caught ### Manufacturing too. Narrow the selector to the top-level sections only.

Exercise: 04-typst/03-set-and-show

report.qmd, not report.typ — the .typ is generated, and anything typed there is gone on the next render.

Both rules have a model in that generated file, though.

Step 1 is #set, step 2 is #show. Say that if nobody moves.

The bonus needs the heading shift — ## is level 1. Staged in the README.

Fast finishers: the menu of free wins.

One answer

• Result
• The block

report.qmd

```{=typst}
#set par(leading: 1em)
#show heading.where(level: 1): set align(center)
```

Two lines. One changes a default everywhere, one changes it inside headings only.

The ### Manufacturing subsection staying left is the selector doing its job.

Further customization

When a raw block is not enough

You want	Reach for
rules used across documents	include-before: styles.typ
a header or footer on every page	override page.typ
a different title block	override typst-show.typ, typst-template.typ

A raw block styles what is already there. It cannot touch the title block — that is built before your content arrives.

#set page() in the body starts a new page too, so a body raw block cannot even reach page one.

Seed with the defaults, hand to an agent

I've added page.typ, typst-show.typ and typst-template.typ, 
unedited copies of Quarto's Typst partials, already registered in report.qmd. 
Edit the partials to rebuild the title block: 
title and subtitle alongside a right aligned the brand logo, 
the reference period and region, 
then the release status as a badge. 

Do not ask for partials from scratch — it will drop the machinery behind cross-references, footnotes and the bibliography.

page.typ is the interesting change: a deletion. Editing a partial is as often about removing default behaviour as adding to it.

The logo comes from _brand.yml, not a document key. $logo$ on its own renders the string true; you want $logo.path$.

Brand colours are not template variables — only brand.typography.* is. brand-color is a Typst variable, so pass it from typst-show.typ.

With a little iteration…

Example: 04-typst/05-title-block

The same layout as the HTML title block from module 03, in the format that could not have it.

Read the folder, don’t work through it. The README lists what the first pass got wrong and what is still not right.

Wrapping up

When LaTeX is still right

• an existing journal template — different language, no path across
• an established math workflow built on LaTeX packages
• HTML, when screen-reader users are a primary audience

Say this plainly. Typst is not a replacement for all of it.

Free with Typst

• gt tables. Structure and CSS styling both translate. Stay in R.
• pdf-standard: ua-1. One line, and a tagged PDF.
• Page layout. papersize, margin, page-numbering, columns.

ua-1 needs quarto install verapdf to be validated. Without it the render still succeeds and the check is skipped.

Passing validation is not the same as meeting the standard.

Questions?

Resources

Reading .typ in your editor

Tinymist Typst — syntax highlighting and completion for .typ files.

myriad-dreamin.tinymist

Open VSX · VS Code Marketplace · Docs

Positron installs extensions from Open VSX, and this one is there.

It covers .typ files. A {=typst} raw block inside a .qmd is not highlighted — the grammar only injects into fences labelled typ or typst.

nvarner.typst-lsp is the predecessor and contributes no grammar. Uninstall it if you have both.

Where the Typst partials live

numbering.typ
definitions.typ
typst-template.typ
page.typ
typst-show.typ
notes.typ
biblio.typ

Source for a version: quarto-cli/src/resources/formats/typst/pandoc/quarto