1 Guide controls

The biggest visible change is a new layer of control over what guides draw.

Before 0.3.0, hiding an axis’s tick marks and labels meant reaching into theme() for the right element surface. Now, guides(x: none) does it directly. The axis line, the vertical grid lines, and the axis title all stay. To drop the title too, add labs(x: none) alongside it.

#plot(
  data: penguins,
  mapping: aes(x: "flipper-len", y: "body-mass", colour: "species"),
  layers: (geom-point(size: 2pt, alpha: 0.7),),
1  guides: guides(x: none),
  labs: labs(
    title: "Ticks Off, Grid Stays",
    x: "Flipper Length (mm)",
    y: "Body Mass (g)",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 8cm,
)

The same syntax now controls legends too. guides(none) hides a legend; guides(auto) restores the default. Both replace the removed guide-none().

When you want all legends gone at once, guides(default: none) sets the fallback for every aesthetic without its own override.

#plot(
  data: penguins,
  mapping: aes(x: "flipper-len", y: "body-mass", colour: "species"),
  layers: (geom-point(size: 2pt, alpha: 0.7),),
1  guides: guides(default: none),
  labs: labs(
    title: "No Legends",
    x: "Flipper Length (mm)",
    y: "Body Mass (g)",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 8cm,
)

2 Radial guide controls

The same guide syntax extends to coord-radial. guides(theta: none) hides the full angular axis, the arc, minor ticks, and tick labels together. guides(r: none) hides only the radial tick labels, leaving the spokes and circles in place.

#plot(
  data: penguins,
  mapping: aes(x: "species", fill: "species"),
  layers: (geom-bar(),),
  coord: coord-radial(),
1  guides: guides(theta: none, default: none),
  labs: labs(
    title: "Angular Axis Hidden",
    x: none,
    y: "Count",
  ),
  theme: theme-minimal(),
  width: 10cm,
  height: 10cm,
)

3 Compose gets a theme

Two changes landed in compose() together.

The first is a theme: parameter. Pass a theme and it styles the composition chrome: the shared title, the hoisted legend, and the panel tags. It also propagates into any panel that has no theme of its own, so you can set one theme once and let it cascade instead of repeating it across every panel.

The second is the defer() helper.

1#let panel(y, title) = defer(plot,
  data: penguins,
  mapping: aes(x: "flipper-len", y: y, colour: "species"),
  layers: (geom-point(size: 2pt, alpha: 0.85),),
  labs: labs(title: title, x: none, y: none),
)

#compose(
  panel("body-mass", "Body Mass"),
  panel("bill-len", "Bill Length"),
  columns: 2,
  tag-levels: "1",
  tag-prefix: "(",
  tag-suffix: ")",
  guides: guides(default: guide-legend(position: "bottom")),
  labs: labs(title: "One Theme, Two Panels"),
2  theme: theme-minimal(),
  width: 18cm,
  height: 8cm,
)

4 Area stacks by default

geom-area() now defaults to stat: "align" and position: "stack".

Before 0.3.0, stacking a multi-group area chart needed both arguments spelled out. Now they are the defaults. stat: "align" also handles groups that have different x values: it resamples each group onto a shared grid before stacking, so the x values do not need to match.

#let series = (
  (x: 0, y: 5, g: "A"), (x: 1, y: 8, g: "A"), (x: 3, y: 6, g: "A"), (x: 4, y: 9, g: "A"),
  (x: 0, y: 3, g: "B"), (x: 2, y: 5, g: "B"), (x: 3, y: 4, g: "B"), (x: 4, y: 6, g: "B"),
  (x: 0, y: 2, g: "C"), (x: 1, y: 3, g: "C"), (x: 2, y: 2, g: "C"), (x: 4, y: 4, g: "C"),
)

#plot(
  data: series,
  mapping: aes(x: "x", y: "y", fill: "g"),
1  layers: (geom-area(),),
  labs: labs(
    title: "Stacked by Default",
    x: "x",
    y: "y",
    fill: "Group",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 8cm,
)

5 Annotations can overflow

annotate() gains a clip argument. The default is true, which preserves the existing behaviour: marks outside the panel are clipped. Set clip: false and the mark is drawn even if it sits past the axis limits.

This is useful for corner insets, labels anchored outside the data range, or decorations that belong in the margin. A paired fix ensures that an annotate(clip: false) placed outside the scale limits actually draws. Before 0.3.0, the out-of-range pre-pass silently dropped it.

#plot(
  data: penguins,
  mapping: aes(x: "flipper-len", y: "body-mass"),
  layers: (
    geom-point(size: 2pt, alpha: 0.6),
    annotate(
      geom-text(label: "← past the edge"),
      x: 235,
      y: 5000,
1      clip: false,
    ),
  ),
  labs: labs(
    title: "Annotation Outside the Panel",
    x: "Flipper Length (mm)",
    y: "Body Mass (g)",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 8cm,
)

1

clip: false keeps the mark visible even though x = 235 sits past the panel boundary.

6 Under the hood

As with 0.2, a large share of the release is fixes rather than features. Legend layout was the main focus.

• Horizontal legends with centred or right align now centre or right-justify the key graphic under the title, instead of leaving it pinned to the left while the title moved.
• guide-legend(nrow:) and guide-legend(ncolumn:) now work for continuous size legends, laying keys out in a grid as they do for discrete swatch legends.
• guide-legend(align:) now aligns the legend title as well as the entry labels. Passing a plain string such as "left" also reports a clear error instead of being silently ignored.
• legend-background now inherits the base rect element, so theme(rect: ...) cascades to it as it does for every other *-background surface.
• A hoisted compose() legend that leaves no room for the panels, or a left/right legend that would overrun the caption, now reports a clear layout error instead of silently overprinting.

A second group cleans up statistics and scale behaviour.

• stat-bin-2d and stat-bin-hex _density is now the cell’s fraction of the total count, matching ggplot2, instead of an undocumented count-per-cell-area value.
• sqrt and log10 transforms validate their domain and report clear errors for out-of-range data. The sqrt inverse also clamps padded view bounds at zero so the axis stays monotone and shows the 0 break.
• The out-of-range filter now respects scale expand, so points and annotations inside the expansion headroom are kept. Reversed limits (a flipped axis) no longer drop every row.
• geom-linerange() honours its alpha parameter, which was always documented but never applied.

7 Editor support: Tinymist docstrings

The published package now ships Tinymist-friendly docstrings. Hovering over a gribouille function in a compatible editor shows formatted parameters, return values, and examples, instead of the raw @-tag comments. Variadic sinks such as guides() and theme() list their accepted keys explicitly, so you can see which aesthetics or element surfaces each function takes without opening the reference.

8 Wrap-up

Next on the list is more geoms and worked examples. If you run into something unexpected, the issue tracker is the right place for it.

• Gribouille
  • Repository: https://github.com/mcanouil/gribouille.
  • Documentation: https://m.canouil.dev/gribouille.
  • Typst Universe: https://typst.app/universe/package/gribouille.
• Typst Render
  • Repository: https://github.com/mcanouil/quarto-typst-render.
  • Documentation: https://m.canouil.dev/quarto-typst-render.

It Started by Helping Out

My time with Quarto began before v1: back-and-forth between the issue/discussion tracker and real document use in my research on the genetics of type 2 diabetes and obesity, when the CLI was still finding its shape. I still spend time in the quarto-dev/quarto-cli repository, answering questions, helping people troubleshoot, surfacing gaps in the documentation, and guiding the same R Markdown and bookdown migration I once made myself.

The figure below (Figure 1) traces that involvement month by month, split across discussions, issues, and pull requests, and it is itself drawn with Gribouille through the quarto-typst-render extension.¹

The totals still catch me off guard. Close to 14,000 contributions in all: comments, replies, pull requests, issues, and discussions across four years.

Working through those threads deepened my understanding of what Quarto does well and where it falls short, which shaped how I use it for my own work today.

From R Markdown to One CLI

The first thing that won me over was the scope of a single tool. With R Markdown I kept a small mental map of which package produced which output. With Quarto I write quarto render, and the same project gives me an HTML report, a PDF through Typst, a Reveal.js deck, a website, or a book. The fragmented toolchain became one CLI, and that alone changed how I work.

The defaults are also less surprising. Format options live under a single format: key, so an HTML and a PDF variant of the same document sit side by side instead of fighting each other. Even the format names are more intuitive: html, pdf, revealjs, website, and book are easier to remember than the R Markdown equivalents (also way less typing), and they are consistent across formats, so I do not have to remember that html_document is for HTML but pdf_document is for PDF. A project/directory-level _metadata.yml sets shared options once, and conditional content with {.content-visible when-format="html"} reads far more clearly than the output checks I used to scatter through R Markdown code cells. None of this is magic, it is just less surprising, and after years of small surprises that matters.

Multi-language support is also native in Quarto. I move between R and Python in the same workflow, even if not yet in the same document (I have strong hopes for Quarto 2 ongoing developments).

The look and feel out of the box is, in my opinion, simply better, especially for HTML. And because R is no longer mandatory, writing notes or plain prose is a first-class use case, not an afterthought. That is also what makes Quarto easy to recommend: I have helped colleagues and clients move from R and bookdown, without asking them to change how they think.

Building My Own

If one feature made Quarto really stick, it is the extension system. An extension adds shortcodes, filters, formats, or whole project types without forking or hacking the core. That single idea turned Quarto from a better R Markdown² into a platform I build on.

I know this because I keep building on it with tools that began as solutions to my own needs but that I share in the spirit of open source.

1. 2022 Q3Storybook, Coeos, Iconify, Letter, Animate, and Elevator, my first handful while learning the format.
2. 2022 Q4Masonry.
3. 2023 Q1Lua Env and Spotlight.
4. Preview Colour shows an inline swatch next to a hex, RGB, or HSL code. Also Version Badge.
   2023 Q2
5. Invoice is a Typst template I actually send to clients.
   2023 Q4
6. Highlight Text highlights text across HTML, Typst, Reveal.js, and Docx.
   2024 Q2
7. 2024 Q3GitHub, later replaced by Git Link.
8. Quarto Wizard manages extensions from VS Code and Positron.
   2024 Q4
9. 2025 Q1Div Reuse and Language Cell Decorator.
10. quarto-mcanouil brings brand.yml theming to HTML, Typst, and Reveal.js, and Git Link turns issue, pull request, and commit references into links. Also External, Modal, and TOC Depth.
    2025 Q3
11. Extensions Updater updates a project's extensions automatically, like Dependabot. Also Collapse Output, Remember, Tabset, and Offcanvas.
    2025 Q4
12. Code Window dresses code blocks as macOS or Windows windows, and Typst Render compiles Typst blocks to images for any format. Also A11y.
    2026 Q1
13. Prism attaches format-specific values to a single Div, Span, or CodeBlock. Also Fragmention, Cascade, and Code Annotation Fragments.
    2026 Q2

The same mechanism scales up. Embedding a Quarto format extension inside an R package gives a large organisation branded, client-ready HTML, PDF, and Reveal.js with its corporate identity baked in. My needs as a biostatistician and consultant drove most of this, and some of it the community adopted. Quarto Wizard manages extensions from VS Code and Positron, and the Quarto Extensions directory lists more than 300 of them through the GitHub API. I also maintain that directory as a community resource that stands apart from the core team, so anyone can find an extension without knowing it exists first. I have written before about the Wizard (1.0.0 and 2.0.0), about keeping extensions updated, and about the Lua behind Quarto extensions.

Then Came Typst

Building all of this kept pulling me toward one format in particular, and that format is Typst. It has become my most recent rabbit hole, both standalone with typst compile and through Quarto’s native typst output. For PDF it is a genuine step up from LaTeX: compilation is fast, the programming model is readable, and layout control is far more direct. I no longer dread a page that needs precise placement.

Out of that work came Gribouille, a grammar of graphics written in pure Typst, so I can draw a plot where the document is compiled rather than importing a rendered image. The chart above (Figure 1), the one tracing my time on quarto-cli, is one of its outputs. The non-obvious lesson, for me, was how little I missed LaTeX once the small frictions were gone. The other was that Typst’s documentation is remarkably easy to search: the model is consistent enough that the right page turns up before I have finished typing the query. My tutorials on building Typst templates for Quarto (Part 1 and Part 2) document those experiments, from document dispatching to the Gribouille releases, and most recently building LinkedIn carousels with Typst, which showed that the same source-to-output loop works for social content as well as technical documents.

Four Years On

Quarto stuck for a plain reason: it stopped getting in my way. What began as answering other people’s questions turned into building my own tools, and then into a new way to make PDFs altogether. Four years on, that is still why I open it every day.

There is also something coming I’m excited about, namely Quarto 2, a ground-up rewrite in Rust: faster compilation, a tree-sitter parser with real error messages, and a collaborative editor built on Automerge. I cannot wait, even though backwards compatibility is one of the main goals, some breaking changes are likely to occur in favour of a better experience, and I am sure it will be worth it.

Happy publishing!

1 Introduction

Gribouille shipped its first version a fortnight ago. This is the first feature update: 0.2.0 landed first, and 0.2.1 followed shortly after with align-panels and two more fixes, so this post covers the 0.2 update as a whole. It has two faces. On the surface, compose() learned to number, nest, title, share a legend across panels, and line those panels up across the grid, facet-grid() got free scales, and labels and guides became easier to control. Underneath, most of the time went into the internals, turning a long list of panics into clear errors and correct output.

Every figure in this post is a real, freshly compiled plot.

Every {typst} block below pulls the library in through a one-line preamble, #import "@preview/gribouille:0.2.1": *, exactly as the launch post explained.

2 Compose grew up

The launch already had compose(): pass a few deferred plots, get them laid out on a grid with their shared legend hoisted to the edge. This release turns it into a small layout language of its own, close in spirit to patchwork.

Panels can be numbered with tag-levels, the composition can carry its own title through labs, and the shared legend’s side is set once with a default guide.

#let panel(y, title) = plot(
  data: penguins,
  mapping: aes(x: "flipper-len", y: y, colour: "species"),
  layers: (geom-point(size: 2pt, alpha: 0.85),),
1  labs: labs(title: title, x: none, y: none),
  theme: theme-minimal(),
2  defer: true,
)

#compose(
  panel("body-mass", "Body Mass"),
  panel("bill-len", "Bill Length"),
  columns: 2,
3  tag-levels: "1",
  tag-prefix: "(",
  tag-suffix: ")",
  tag-corner: "top-right",
4  guides: guides(default: guide-legend(position: "bottom")),
5  labs: labs(title: "Two Views, One Shared Legend"),
  width: 18cm,
  height: 8cm,
)

Three things here are new. tag-levels, with tag-prefix, tag-suffix, and tag-corner, labels each panel and styles the tag through a new plot-tag theme element. A composition now accepts its own labs (title, subtitle, caption) and alt text, so the figure reads as one unit. The shared legend is steered through guides instead of the old guides-placement argument, which is removed.

The 0.2.1 release adds one more control and tidies the tags. By default each panel keeps its own margins, so when one panel carries wide axis labels and another narrow ones, their plot areas start at different offsets and never quite line up. align-panels: true shares the margins grid-wise, left and right per column, top and bottom per row, so the data areas align across the grid the way patchwork and cowplot do. The panel tags also reserve their own band now, sitting above each panel instead of overlapping the data.

#let panel(y, title) = plot(
  data: penguins,
  mapping: aes(x: "flipper-len", y: y, colour: "species"),
  layers: (geom-point(size: 2pt, alpha: 0.85),),
  labs: labs(title: title, x: none),
  theme: theme-minimal(),
  defer: true,
)

#compose(
  panel("body-mass", "Body Mass (g)"),
  panel("bill-len", "Bill Length (mm)"),
  columns: 1,
1  align-panels: true,
2  tag-levels: "a",
  guides: guides(default: guide-legend(position: "bottom")),
  width: 12cm,
  height: 14cm,
)

3 Free the facet scales

facet-grid() used to share one pair of axes across every panel. It now takes a scales argument, matching ggplot2: "free_x" frees the x-axis per column, "free_y" frees the y-axis per row, and "free" frees both. Non-positional scales such as colour stay shared, and the panels keep an equal size.

#plot(
  data: penguins,
  mapping: aes(x: "flipper-len", y: "body-mass", colour: "species"),
  layers: (geom-point(size: 2pt, alpha: 0.7),),
  facet: facet-grid(rows: "species", scales: "free_y"),
  theme: theme-minimal(),
  width: 12cm,
  height: 14cm,
)

Each row now picks its own y-range, so a group sitting in a narrow band no longer wastes most of its panel on empty space.

4 Highlight a subset without a second dataset

A layer’s data now takes a function as well as a frame. The function receives the plot data and returns the rows that layer should draw. So one dataset can feed a faint base layer and a sharp highlight on top, with no second table to keep in step.

#plot(
  data: penguins,
  mapping: aes(x: "flipper-len", y: "body-mass"),
  layers: (
    geom-point(size: 2pt, alpha: 0.35),
    geom-point(
1      data: rows => rows.filter(r => {
        let mass = r.at("body-mass", default: none)
        mass != none and mass >= 5500
      }),
      size: 3pt,
      colour: rgb("#D55E00"),
    ),
  ),
  labs: labs(
    title: "One Dataset, One Layer Highlighted",
    x: "Flipper Length (mm)",
    y: "Body Mass (g)",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 8cm,
)

The same trick covers per-layer transforms, not just filtering. Return a reshaped frame and that layer draws it, while the rest of the plot keeps the original data.

5 Tidier labels and guides

Two smaller changes remove a recurring annoyance.

First, every labs() field defaults to auto. Passing none now drops an axis or legend title and reclaims the margin it reserved, instead of leaving an empty gap. element-blank() on a text surface does the same from the theme side.

#plot(
  data: penguins,
  mapping: aes(x: "flipper-len", y: "body-mass"),
  layers: (geom-point(size: 2pt, alpha: 0.7),),
  labs: labs(
    title: "Axis Titles Off, Space Reclaimed",
    x: none,
    y: none,
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 8cm,
)

Second, guides() takes a default entry. It holds the fallback guide options, the legend side most often, and any aesthetic without its own guide inherits from it. You saw it above feeding the shared legend in compose(); it works the same on a single plot(). Legend labels also honour the legend-text alignment now, and element-text()/element-typst() gained an align argument and a working angle, so tick labels and titles rotate as asked.

6 The heavy lifting was underneath

The list above is the visible part. The larger share of this release is a pass over the internals, and it is the kind of work that does not show up in a screenshot.

A whole class of inputs that used to crash the compile now behaves. A geom-col() on a continuous axis with a single distinct value, an empty values array in a scale-*-manual(), a non-positive bins, a sparse contour grid, or width: auto on an unbounded page: each of these used to panic, and each now either draws or reports a clear, actionable error.

A second group is about getting the right answer rather than not crashing.

• after-scale and stage channels now train on the marker’s source column, so grouped geoms such as geom-smooth(), and geom-errorbar() or geom-rug(), resolve a mapped colour instead of panicking.
• coord-cartesian(xlim:, ylim:) zooms the axes instead of being ignored, and coord-flip(reverse: true) keeps a log10 or sqrt transform.
• A column mapped to both a positional and a grouping aesthetic, for example aes(x: "species", fill: "species"), now resolves the grouping across aggregating stats instead of drawing every mark in the ink colour with an empty guide.
• Number formatters round correctly, so 0.9999995 no longer renders as 0.1, and continuous scales honour an explicit breaks.
• geom-segment(), geom-curve(), geom-ribbon(), and geom-area() draw on a discrete scale instead of silently rendering nothing (0.2.1).

A third group, and a big one, is about layout space: what a plot reserves, and what it reclaims when it is not needed. The labs(none) and element-blank() controls shown above are the visible handles, but most of the work was below them, deciding how much room each part of a figure should take.

• A standalone plot no longer keeps a fixed empty margin on its top and right edges; the panel grows into that space.
• A missing axis title reclaims the band it would have reserved, on the x-axis side as well as the y-axis side.
• width and height now bound the whole image, title, subtitle, caption, and background padding included, so the data panel shrinks to fit and long titles wrap instead of overflowing.
• Legends reserve the room a label actually needs, measuring multi-line and wider-than-usual labels across swatches, size ladders, and colourbars, so nothing clips or overlaps.

None of this changes the API. Documents that compiled before still compile, and the plots that were already correct look the same. What changed is the long tail of inputs that did not.

7 Typst Render moved too

The figures here are compiled by the quarto-typst-render extension, which had its own run of releases since the launch post. Three are worth knowing about for a documentation-heavy project.

• code-fold and code-summary collapse the echoed Typst source into a <details> block, so a long example does not push the figure off the screen.
• Quarto code annotations now work on echoed Typst source: the // <1> markers and the numbered list under the compose() block above are exactly that feature.
• output-source writes the compiled Typst source, preamble and colour bindings included, next to each saved image, which is handy when you want to reproduce a figure outside Quarto.

8 Wrap-up

Next on the list is more geoms, a wider set of worked examples, and feedback from the people writing Typst documents day to day.

• Gribouille
  • Repository: https://github.com/mcanouil/gribouille.
  • Documentation: https://m.canouil.dev/gribouille.
  • Typst Universe: https://typst.app/universe/package/gribouille.
• Typst Render
  • Repository: https://github.com/mcanouil/quarto-typst-render.
  • Documentation: https://m.canouil.dev/quarto-typst-render.

Introduction

Since January 2026 I have made the carousels for my LinkedIn posts with Typst. It has worked well, so here is how I do it.

A LinkedIn carousel is not a special thing. It is a multi-page document that the feed turns into swipeable cards, and you upload it as a single PDF. So if you can make a multi-page PDF, you can make a carousel.

Typst is a fine tool for exactly that. You describe each page in plain text, compile to PDF in a fraction of a second, and keep the source under version control like any other code. No design tool, no manual export, no moving boxes around by hand.

This post shows the one helper I use to make this easy: a small slide helper that gives every page a full-bleed background with consistent padding. Every slide shown below is a real Typst compilation, rendered to SVG by the Typst Render Quarto extension, so you see the code and its result side by side.

Setting up the page

Start by setting the page geometry once, at the top of the file.

#set document(title: "My Carousel", author: "Your Name")
#set text(lang: "en")
#set page(width: 21cm, height: 21cm, margin: 0cm)

The 21cm by 21cm size is a square 1:1. The LinkedIn image size guide recommends carousels as a square 1080 by 1080, or a 4:5 portrait. The exact dimensions do not matter, only the ratio does, so any square pair works.

The important line is margin: 0cm.

Carousel slides want colour and imagery that reach every edge, and a page margin would fence the content into a smaller box with white gutters. Removing the margin gives you the full page, and you add the padding back yourself. That is what the slide helper does.

The slide layout

A slide helper can do more than add padding. It can also draw the parts that repeat on every card. The layout below draws a full-height accent rail down the left edge, adds a page number in the top-right corner, then lays out your content in the space that is left. Here it is, defined and then called with an empty body so you can see the rail and the padded area where body goes.

1#let slide(index: none, fill: paper, body) = page(fill: fill, {
2  place(left + top, rect(width: 0.55cm, height: 100%, fill: accent))
3  if index != none {
    place(
      top + right, dx: -1.4cm, dy: 1.4cm,
      text(font: mono, size: 14pt, fill: ink-soft, index)
    )
  }
4  block(
    width: 100%, height: 100%, inset: (left: 2.6cm, right: 1.7cm, y: 1.7cm),
    body
  )
5})

#slide({
  block(
    width: 100%, height: 100%,
    stroke: (paint: ink-soft, thickness: 1pt, dash: "dashed"),
    radius: 8pt,
    align(center + horizon, text(font: mono, fill: ink-soft, "body goes here")),
  )
})

The helper is optional: a bare #page(...) would work too. Defining slide once is what keeps the rail, the page number, and the padding identical on every card, and every call site short.

The page geometry, a small palette, the fonts, this slide layout, and a ruled kicker label are the file’s setup. In this post they live in a shared preamble, so each live example below shows only the card it draws.

Slides, live

The cover card passes an index, adds a kicker at the top, and centres the headline. The rail and the page number come from the layout.

#slide(index: "1 / 3", {
  kicker("Typst · Carousel")
  v(1fr)
  block(width: 16cm, {
    text(font: display, size: 54pt, weight: "bold", fill: ink, "Build decks")
    linebreak()
    text(font: display, size: 54pt, weight: "bold", fill: accent, "from text")
    v(0.4cm)
    text(size: 20pt, fill: ink-soft, "One layout, used on every card.")
  })
  v(1fr)
})

A content card stacks a few numbered rows with a grid to keep the numbers and text aligned.

#slide(index: "2 / 3", {
  kicker("Why Typst")
  v(0.5cm)
  block(
    width: 16cm,
    text(
      font: display, size: 32pt, weight: "bold", fill: ink,
      "Three reasons it fits carousels."
    )
  )
  v(0.7cm)

  let row(n, t) = grid(
    columns: (1.3cm, 1fr),
    align: (left + horizon, left + horizon),
    text(font: mono, size: 22pt, weight: "bold", fill: accent, str(n)),
    block(width: 15cm, text(size: 18pt, fill: ink, t)),
  )

  stack(
    dir: ttb,
    spacing: 0.7cm,
    row(1, "Plain text in, PDF out. Diff it, version it, regenerate it."),
    row(2, "One layout sets the look of every page at once."),
    row(3, "No design tool, no manual export, no pixel pushing."),
  )
})

The closing card changes the background with the fill parameter. The rail and the page number stay the same.

#slide(index: "3 / 3", fill: ink, {
  v(1fr)
  kicker("Ship it")
  v(0.5cm)
  text(
    font: display, size: 46pt, weight: "bold", fill: paper,
    "Compile and post."
  )
  v(0.6cm)
  text(
    font: mono, size: 17pt, fill: rgb("#8fa49d"),
    "typst compile carousel.typ carousel.pdf"
  )
  v(1fr)
})

Each card renders as a true square, so what you see is what the feed will show.

Compile the whole deck

Stack your slides in one carousel.typ file, then compile it. Each #slide(...) becomes one page, and the PDF is the carousel.

# Each #slide is one page; the PDF is the carousel
typst compile carousel.typ carousel.pdf

# Typst can also export one PNG per page, no extra tool needed
typst compile carousel.typ "carousel-{p}.png" --ppi 144

Upload carousel.pdf to LinkedIn as a document post, and keep the PNG frames for a preview.

Want a GIF for another platform?

LinkedIn takes the PDF, but some places want a GIF. Build one from the PNG frames with ImageMagick.

# Assemble the exported PNG frames into a looping GIF
magick -delay 250 -loop 0 carousel-*.png carousel.gif

-delay 250 holds each frame for 2.5 seconds, and -loop 0 loops forever.

Here is this post’s deck as a looping GIF.

Bonus: an LLM prompt

If you would rather start from a draft, paste the prompt below into your assistant of choice. It encodes the geometry, the slide helper, and the design constraints, so the output compiles with the typst CLI.

You are designing a LinkedIn carousel as a Typst document.
Produce a single self-contained carousel.typ that compiles with `typst compile`.

Hard requirements:

- Page geometry: #set page(width: 21cm, height: 21cm, margin: 0cm).
  This is a square 1:1 (LinkedIn shows carousels at 1080 by 1080); keep the ratio.
- Define one `slide` layout and use it for every card.
  Build it from a full-page block with zero page margin and an inset, so the background reaches every edge and the content keeps consistent padding:
    #let slide(fill: <default-bg>, body) = page(fill: fill, {
      block(width: 100%, height: 100%, inset: 1.7cm, body)
    })
  Add any repeated parts you want on top of that (a header, a page number, ...).
- Invent a small palette (background, ink, soft ink, one accent) and a font trio (display, body, mono).
  Prefer legible fonts.
- Five to seven cards following the arc: cover, then content, then a closing call to action.
  Use one card with `fill: <accent-or-dark>` to invert the look.
- Body text at least 14pt; headlines 30 to 56pt, so everything reads at thumbnail size.
  Use place, grid, stack, and v()/h() for layout.

Then tell me the two `typst compile` commands to export it to PDF and to one PNG per page.

The topic of the carousel is: <describe your announcement here>.
Layout and style (optional): <describe any layout or look you want, for example a side rail, page numbers, a colour band, a serif or a sans display; leave blank to let you pick a clean design>.

Now build a deck for your next post. If you make one, tag me on LinkedIn so I can see it.

1 Introduction

Typst has grown from a curious newcomer to a credible alternative for scientific writing, reports, and slide decks. What it still lacked, until today, was a real grammar of graphics: a way to declare a figure with the same vocabulary you would reach for in ggplot2, then have it draw, lay out, and align with the rest of the document.

Gribouille (French for scribble) is the first cut of that library. Version 0.1.0 lands on Typst Universe with this announcement, modelled closely on ggplot2, drawing on top of cetz, and shipped with a documentation site that is itself a Quarto project rendered by the quarto-typst-render extension. Every figure in this post is a real, freshly compiled plot.

2 Why a grammar of graphics for Typst

Until now, producing a figure inside a Typst document meant taking a detour through another language. You would leave Typst to call out to ggplot2, matplotlib, or plotnine, save a PNG or SVG, and import it back. That works, but it splits the toolchain in two: one font system on the page, another inside the figure; one colour palette in the report, another in the chart; one render pass that knows about the layout, another that does not.

cetz already gives Typst a robust low-level drawing API, but the declarative layer that turns a dataset, a mapping, and a few layers into a publication-quality figure was missing. That is exactly the gap Gribouille fills.

The pay-off is a single toolchain. Give a plot an alt: description and Gribouille wraps the result in a Typst figure element with kind: "gribouille-plot", so you can attach show rules, captions, or cross-references in one place; with or without it, every plot shares the document’s fonts, palette, and geometry. The YAML front-matter of this very post wires its background: and foreground: to the site’s light and dark colours, and every figure below reacts automatically when you toggle the theme. Compilation is deterministic, offline-friendly, and produces a PDF straight out of Typst with no Python or R runtime required.

3 A respectful nod to ggplot2

A short personal aside. I have been using ggplot2 since almost its first release, and a large part of how I think about data visualisation comes from that work. This release would not exist without Hadley Wickham’s original vision, nor without the people carrying it forward today, in particular Thomas Lin Pedersen and Teun van den Brand, and the wider community of contributors who keep shaping the package through to the recent v4 release.

Gribouille is, in many ways, a port of ggplot2’s vocabulary into Typst. The names line up: plot() instead of ggplot(), geom-point() for geom_point(), facet-wrap(), scale-colour-*(), theme-minimal(), and so on. Where the two part ways, it is because Typst is a different language, with no lazy evaluation, no plot object you can mutate after the fact, and no ggsave() output pipeline. Column names are plain strings. Per-aesthetic type coercion is done inline with as-factor() and as-numeric(). These are opinionated departures, but the mental model is the same one you already have.

4 Build a penguins plot, one layer at a time

The library ships the Palmer Penguins dataset under the penguins symbol. The walk-through below builds a single figure end to end, one grammar concept at a time, with brief notes on alternatives at each step. It is a tighter version of the Get Started page on the documentation site.

Every plot you build composes the same pieces. plot() wraps a stack of layers, each sheet sitting on the one below, from data and mapping at the foundation up through theme and labels.

The post’s YAML points the typst-render extension at a one-line preamble file so every {typst} block has the library in scope:

extensions:
  typst-render:
    preamble: _preamble.typ

And _preamble.typ contains:

#import "@preview/gribouille:0.1.0": *

You would write the same #import once at the top of your own Typst document.

#plot(
  data: penguins,
  mapping: aes(x: "flipper-len", y: "body-mass"),
  layers: (geom-point(size: 2pt),),
  width: 12cm,
  height: 9cm,
)

#plot(
  data: penguins,
  mapping: aes(
    x: "flipper-len",
    y: "body-mass",
    colour: "species",
  ),
  layers: (geom-point(size: 2pt, alpha: 0.85),),
  width: 12cm,
  height: 9cm,
)

#plot(
  data: penguins,
  mapping: aes(
    x: "flipper-len",
    y: "body-mass",
    shape: "species",
  ),
  layers: (geom-point(size: 2pt, alpha: 0.85),),
  width: 12cm,
  height: 9cm,
)

#plot(
  data: penguins,
  mapping: aes(
    x: "flipper-len",
    y: "body-mass",
    colour: "species",
    fill: "species",
  ),
  layers: (
    geom-point(size: 2pt, alpha: 0.6),
    geom-smooth(method: "lm", alpha: 0.2),
  ),
  width: 12cm,
  height: 9cm,
)

#let cb = (
  rgb("#0072B2"),
  rgb("#D55E00"),
  rgb("#009E73"),
)

#plot(
  data: penguins,
  mapping: aes(
    x: "flipper-len",
    y: "body-mass",
    colour: "species",
    fill: "species",
  ),
  layers: (
    geom-point(size: 2pt, alpha: 0.6),
    geom-smooth(method: "lm", alpha: 0.2),
  ),
  scales: (
    scale-colour-discrete(palette: cb),
    scale-fill-discrete(palette: cb),
  ),
  width: 12cm,
  height: 9cm,
)

#let cb = (
  rgb("#0072B2"),
  rgb("#D55E00"),
  rgb("#009E73"),
)

#plot(
  data: penguins,
  mapping: aes(
    x: "flipper-len",
    y: "body-mass",
    colour: "species",
    fill: "species",
  ),
  layers: (
    geom-point(size: 2pt, alpha: 0.6),
    geom-smooth(method: "lm", alpha: 0.2),
  ),
  scales: (
    scale-colour-discrete(palette: cb),
    scale-fill-discrete(palette: cb),
  ),
  facet: facet-wrap("island"),
  width: 12cm,
  height: 9cm,
)

#let species-colours = (
  Adelie:    rgb("#0072B2"),
  Chinstrap: rgb("#D55E00"),
  Gentoo:    rgb("#009E73"),
)

#plot(
  data: penguins,
  mapping: aes(
    x: "flipper-len",
    y: "body-mass",
    colour: "species",
    fill: "species",
    shape: "species",
  ),
  layers: (
    geom-point(size: 2pt, alpha: 0.6),
    geom-smooth(method: "lm", alpha: 0.2),
  ),
  scales: (
    scale-colour-discrete(
      limits: species-colours.keys(),
      palette: species-colours.values(),
    ),
    scale-fill-discrete(
      limits: species-colours.keys(),
      palette: species-colours.values(),
    ),
    scale-y-continuous(labels: format-comma()),
  ),
  facet: facet-wrap("island"),
  guides: guides(
    colour: guide-legend(position: bottom + right),
    fill: guide-legend(position: bottom + right),
    shape: guide-legend(position: bottom + right),
  ),
  labs: labs(
    title: "Penguin Body Mass Scales with Flipper Length",
    subtitle: {
      [Linear fit $hat(y) = beta_0 + beta_1 dot.c x$ on every island for three species: ]
      species-colours.pairs()
        .map(p => text(fill: p.at(1), weight: "bold", p.at(0)))
        .join(", ")
    },
    x: "Flipper Length (mm)",
    y: "Body Mass (g)",
    colour: "Species",
    fill: "Species",
    shape: "Species",
  ),
  theme: theme-minimal(
    plot-title: element-text(size: 12pt, weight: "bold"),
    plot-subtitle: element-typst(size: 9pt),
  ),
  width: 12cm,
  height: 9cm,
)

5 Compose multiple plots

Sometimes a story needs more than one panel. compose() takes several deferred plots, lays them out on a grid or stack, and hoists their shared legend into a single guide block at the edge of the figure. The deferred plots are produced by passing defer: true to plot(), which returns a spec dictionary instead of rendering immediately.

#let panel(mapping) = plot(
  data: penguins,
  mapping: mapping,
  layers: (geom-point(size: 2pt, alpha: 0.85),),
  width: 6cm,
  height: 4.5cm,
  defer: true,
)

#compose(
  panel(aes(x: "flipper-len", y: "body-mass", colour: "species")),
  panel(aes(x: "bill-len", y: "body-mass", colour: "species")),
  layout: "grid",
  columns: 1,
)

6 Drive Gribouille from any computation

Typst Render 0.13.1 adds a small but powerful helper called typst_define(), available from both R and Python. It lets a code cell hand any value to every {typst} block in the document under a single Typst dictionary named typst_define. A scalar, a list, a dictionary, a NumPy array, a Polars DataFrame, anything JSON-serialisable, lands in Typst as the corresponding native value.

The mechanism is deliberately plain. The helper serialises the values you give it to JSON, hex-encodes them, and emits a tiny Pandoc metadata block of the form ---\ntypst-define: <hex>\n---\n. The extension’s Lua filter, which runs at the pre-quarto stage, decodes that block and injects a #let typst_define = (...) preamble in front of every Typst compilation. You compute on one side, read typst_define.something on the other, and the two stay in step regardless of which language did the work.

That bridge is what makes the rest of this section possible. The example below uses Python with polars, but the same approach works with R (typst_define() ships in both languages), with plain Python collections, with database queries, with REST calls, or with anything else that can produce a value. Python and Polars are one concrete illustration, not a requirement.

#| include: false
import os, sys
sys.path.insert(0, os.path.join(
  os.environ.get("QUARTO_PROJECT_DIR", "."),
  "_extensions", "mcanouil", "typst-render", "_resources",
))
from typst_define import typst_define

import os
import sys

import polars as pl

project_dir = os.environ.get("QUARTO_PROJECT_DIR", "../..")
sys.pycache_prefix = os.path.join(project_dir, ".cache", "pycache")
extension_resources = os.path.join(
  project_dir,
  "_extensions",
  "mcanouil",
  "typst-render",
  "_resources",
)
sys.path.insert(0, extension_resources)
from typst_define import typst_define

# Network read at render time; swap for a local CSV or the `palmerpenguins`
# Python package when working offline.
penguins = pl.read_csv(
  "https://raw.githubusercontent.com/allisonhorst/palmerpenguins/main/inst/extdata/penguins.csv",
  null_values="NA",
).with_columns(
  pl.col("flipper_length_mm").cast(pl.Float64),
  pl.col("body_mass_g").cast(pl.Float64),
)

summary = (
  penguins
  .drop_nulls(["flipper_length_mm", "body_mass_g"])
  .group_by("species")
  .agg(
    pl.col("flipper_length_mm").mean().round(1).alias("flipper_mean"),
    pl.col("body_mass_g").mean().round(0).cast(pl.Int64).alias("body_mass_mean"),
    pl.len().alias("n"),
  )
  .sort("species")
)

typst_define(summary=summary)
summary

#let cb = (
  rgb("#0072B2"),
  rgb("#D55E00"),
  rgb("#009E73"),
)

#plot(
  data: typst_define.summary,
  mapping: aes(
    x: "species",
    y: "body_mass_mean",
    fill: "species",
  ),
  layers: (geom-col(width: 0.6),),
  scales: (scale-fill-discrete(palette: cb),),
  labs: labs(
    title: "Mean Body Mass per Species",
    subtitle: "Computed in Polars, drawn in Gribouille",
    x: "Species",
    y: "Body Mass (g)",
    fill: "Species",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 7cm,
)

7 Current limitations

This first release is deliberately focused. Some ggplot2/plotnine features are out of scope by design; others are pending while the project matures.

• No geom-violin(), geom-density(), or geom-density-2d(). Kernel density estimation needs numerical machinery that pure Typst cannot run efficiently, and the realistic escape hatch is a WebAssembly helper. That route is on hold for now because I do not yet have enough hands-on WASM experience to build and ship one with confidence, and the help I have had from LLMs has not closed that gap to a level I am comfortable releasing.
• geom-smooth() and stat-smooth() support method: "lm" only. LOESS is deferred for the same reason.
• geom-dotplot() uses histogram-style binning only; data-driven dot-density binning is deferred.
• Maps and spatial geometries (ggplot2’s sf integration) are currently out of scope.

8 Wrap-up

Next on the list is filling in more geoms, more themes, and more worked examples, and chasing feedback from the people writing Typst documents day to day.

• Gribouille
  • Repository: https://github.com/mcanouil/gribouille.
  • Documentation: https://m.canouil.dev/gribouille.
  • Typst Universe: https://typst.app/universe/package/gribouille.
• Typst Render
  • Repository: <https:// github.com/mcanouil/quarto-typst-render>.
  • Documentation: https://m.canouil.dev/quarto-typst-render.

1 Introduction

Reveal.js is a flexible slide engine, but a few rough edges show up again and again when writing slides in Quarto. List fragments need a marker on every item, code annotations stay static, long talks repeat the same heading on continuation slides, and tabsets need a mouse click to advance. Each of the four small extensions below closes one of those gaps, and they compose cleanly on a single slidedeck.

Every section installs one extension, shows the minimal front-matter and body needed to activate it, and embeds a focused slidedeck you can step through with the arrow keys.

2 Fragmention

quarto-revealjs-fragmention lets you animate a whole list item as a single fragment. You place an empty span with the .fragment class (and optional fragment-index) at the start of the item, and the filter hoists those attributes onto the parent <li>, so there is no stray marker left in the rendered slide.

quarto add mcanouil/quarto-revealjs-fragmention

filters:
  - fragmention

## A staged list

- []{.fragment fragment-index="1"} Load the data from disk.
- []{.fragment fragment-index="2"} Clean and validate the inputs.
- []{.fragment fragment-index="3"} Fit the model.
- []{.fragment fragment-index="4"} Report the results.

## Mixed fragments

- []{.fragment .fade-in-then-semi-out fragment-index="1"} Step one fades in, then dims.
- []{.fragment .highlight-red fragment-index="2"} Step two highlights in red.
- A static bullet always visible.
- []{.fragment .grow fragment-index="3"} Step three grows for emphasis.

3 Codefrag

quarto-revealjs-codefrag pairs naturally with Quarto’s code-annotations: select mode. Each # <n> marker becomes a Reveal.js fragment, so the matching annotation appears step by step as you press the arrow keys, and the tooltip stays in sync with the current annotation.

quarto add mcanouil/quarto-revealjs-codefrag

revealjs-plugins:
  - codefrag

## Step through an R pipeline

```{.r code-line-numbers="|1|2-3|4-5|6"}
library(dplyr)                          # <1>
mtcars |>
  filter(cyl == 6) |>                   # <2>
  group_by(gear) |>
  summarise(mean_mpg = mean(mpg)) |>    # <3>
  arrange(desc(mean_mpg))               # <4>
```

1. Load the `dplyr` package.
2. Keep only six-cylinder cars.
3. Compute the mean mileage per gear.
4. Sort the resulting table.

4 Cascade

quarto-revealjs-cascade repeats the current heading chain whenever a --- slide break creates a continuation slide. You keep one section heading (and optional subsection) at the top of a topic, then use --- to start fresh slides without retyping the title.

quarto add mcanouil/quarto-revealjs-cascade

filters:
  - cascade

# Cascade demo

## Results

### Experiment A

- Baseline accuracy: 0.82.
- Calibration error: 0.04.

---

- Recall improves with larger batches.
- Precision plateaus after 10 epochs.

---

### Experiment B

- Baseline accuracy: 0.87.
- Calibration error: 0.03.

---

- Results replicate across three seeds.
- No regression on the held-out split.

5 Tabset

quarto-revealjs-tabset turns a .panel-tabset block into a keyboard-driven tabset. Each tab becomes a Reveal.js fragment, so the arrow keys cycle through them, and PDF export lays every tab out on its own page instead of collapsing them to the active one.

quarto add mcanouil/quarto-revealjs-tabset

revealjs-plugins:
  - tabset

## Dataset overview {.smaller}

::: {.panel-tabset}

### Description

- 1,000 records collected in 2025.
- Three outcome labels, balanced across classes.

### Summary

| Feature | Min | Median | Max |
|---------|----:|-------:|----:|
| Age     |  18 |     42 |  91 |
| Score   |   0 |     57 | 100 |

### Notes

- Missing values imputed with the column median.
- Duplicates removed before splitting.

:::

6 All four together

The four extensions compose without fuss on a single slidedeck. You declare the two filters, the two plugins, and code-annotations: select, then use each feature where it fits the story.

filters:
  - fragmention
  - cascade
revealjs-plugins:
  - codefrag
  - tabset

7 Wrap-up

Each extension is small, focused, and targets a friction point rather than a whole workflow. Install the ones you need, keep the rest out of your front-matter, and your next slidedeck can lean a little more on the keyboard and a little less on the mouse.

Repositories for the curious:

• quarto-revealjs-fragmention.
• quarto-revealjs-codefrag.
• quarto-revealjs-cascade.
• quarto-revealjs-tabset.

1 The Problem

The goal is to make every visual output match the document’s brand without hardcoding hex values or font names. Here is what branded outputs look like across six different brand configurations, each with light and dark variants:

2 The QUARTO_EXECUTE_INFO Approach

When Quarto renders a document, it sets the QUARTO_EXECUTE_INFO environment variable for every code cell. This variable points to a JSON file containing document metadata, format settings, and, crucially, the resolved brand configuration.

The brand data lives at format.render.brand in the JSON, with separate entries for each colour mode (light, dark). Reading it requires only a JSON parser.

get_brand_info <- function() {
2  jsonlite::fromJSON(
1    Sys.getenv("QUARTO_EXECUTE_INFO", unset = "")
  )
}

import json
import os
import pathlib

def get_brand_info() -> dict:
1    raw = os.environ.get("QUARTO_EXECUTE_INFO", "")
    if not raw:
        return {}
    path = pathlib.Path(raw)
2    if path.is_file():
        return json.loads(path.read_text())
    return json.loads(raw)

info <- get_brand_info()
cat(jsonlite::toJSON(info[["format"]][["render"]][["brand"]], pretty = TRUE))

info = get_brand_info()
print(json.dumps(info["format"]["render"]["brand"], indent=2))

3 Brand Data Structure

The brand object under format.render.brand contains one entry per colour mode. Each mode holds a data object with colour and typography definitions.

{
  "light": {
    "data": {
      "color": {
        "palette": {
          "anchor-blue": "#2f5d8a",
          "harbour-teal": "#2d8c8f",
          "strait-violet": "#5f6fb3"
        },
        "foreground": "#4f789e",
        "background": "#f8fafc"
      },
      "typography": {
        "base": "Chakra Petch",
        "headings": "Great Vibes",
        "monospace": "JetBrains Mono",
        "fonts": [
          { "family": "Chakra Petch", "source": "bunny" }
        ]
      }
    }
  },
  "dark": {
    "data": { "..." }
  }
}

The key fields are:

• color.palette: named colour values used for data series and accents.
• color.foreground / color.background: ink and paper colours for the given mode.
• typography.base / typography.headings: font family names.
• typography.fonts: font specifications including source (bunny, google, file, or system).

The diagrams below summarise how each helper function fits into the rendering pipeline.

4 Dependencies

This approach relies on a handful of packages for each language.

5 Font Registration

Web fonts defined in a brand configuration are not available to R or Python graphics devices by default. Before creating any plots or tables, a configure_brand_fonts() function registers each font so that graphics devices can find them. Call it once in a setup chunk at the top of your document.

configure_brand_fonts <- function(brand_mode = "light") {
  info <- get_brand_info()
  brand <- info[["format"]][["render"]][["brand"]]
1  doc_dir <- dirname(info[["document-path"]])

  for (mode in intersect(c("light", "dark"), names(brand))) {
    fonts <- brand[[mode]][["data"]][["typography"]][["fonts"]]
    for (ifont in seq_len(nrow(fonts))) {
      family <- fonts[["family"]][[ifont]]
      source <- fonts[["source"]][[ifont]]

      if (identical(source, "file")) {
        files <- fonts[["files"]][[ifont]]
        for (fp in as.character(files[["path"]])) {
2          resolved <- file.path(doc_dir, fp)
3          systemfonts::register_font(family, plain = resolved)
        }
      } else {
4        systemfonts::require_font(family, repositories = "Bunny Fonts")
      }
    }
  }
5  systemfonts::reset_font_cache()
}

import matplotlib.font_manager as fm
import pyfonts

def configure_brand_fonts() -> None:
    info = get_brand_info()
    brand = info["format"]["render"]["brand"]
1    doc_dir = pathlib.Path(info["document-path"]).parent

    for mode in ["light", "dark"]:
        if mode not in brand:
            continue
        fonts = brand[mode]["data"]["typography"]["fonts"]
        for font_spec in fonts:
            family = font_spec["family"]
            source = font_spec["source"]

            if source == "file":
                for f in font_spec.get("files", []):
2                    resolved = doc_dir / f["path"]
3                    fm.fontManager.addfont(str(resolved))
            elif source in ("bunny", "google"):
                if source == "bunny":
                    props = pyfonts.load_bunny_font(family)
                else:
                    props = pyfonts.load_google_font(family)
4                fm.fontManager.addfont(props.get_file())

6 Branded Figures

The theme_brand() function extracts colours and fonts from the brand data and builds a complete ggplot2 or plotnine theme. The idea is straightforward: pull out the ink (foreground), paper (background), and palette colours, then pass them to the theme constructor. In R, the latest ggplot2 supports ink, paper, and accent parameters directly in theme_minimal(); in Python, each theme element is styled individually.

theme_brand <- function(base_size = 11, brand_mode = "light") {
  info <- get_brand_info()
  brand <- info[["format"]][["render"]][["brand"]]
  brand_data <- brand[[brand_mode]][["data"]]
  colors <- brand_data[["color"]]
  typography <- brand_data[["typography"]]
1  palette_values <- unname(unlist(colors[["palette"]]))

2  ink <- colors[["foreground"]]
  paper <- colors[["background"]]
3  accent <- scales::col_mix(ink, paper, amount = 0.25)

  ggplot2::theme_minimal(
    base_size = base_size,
4    base_family = typography[["base"]],
    header_family = typography[["headings"]],
5    ink = ink,
    paper = paper,
    accent = accent
  ) +
    ggplot2::theme(
      plot.title = ggplot2::element_text(
        colour = accent,
        size = ggplot2::rel(2)
      ),
6      palette.colour.discrete = palette_values,
      palette.fill.discrete = palette_values
    )
}

def _col_mix(a: str, b: str, amount: float = 0.25) -> str:
    ra, ga, ba = int(a[1:3], 16), int(a[3:5], 16), int(a[5:7], 16)
    rb, gb, bb = int(b[1:3], 16), int(b[3:5], 16), int(b[5:7], 16)
    r = int(ra + (rb - ra) * amount)
    g = int(ga + (gb - ga) * amount)
    b_val = int(ba + (bb - ba) * amount)
    return f"#{r:02x}{g:02x}{b_val:02x}"

def get_brand_palette(brand_mode: str = "light") -> list[str]:
    info = get_brand_info()
    brand = info["format"]["render"]["brand"]
    palette = brand[brand_mode]["data"]["color"]["palette"]
    return list(palette.values())

from plotnine import (
    element_line, element_rect, element_text, theme, theme_minimal
)

def theme_brand(base_size: int = 11, brand_mode: str = "light") -> theme:
    info = get_brand_info()
    brand = info["format"]["render"]["brand"]
    brand_data = brand[brand_mode]["data"]
    colors = brand_data["color"]
    typography = brand_data["typography"]

1    ink = colors["foreground"]
    paper = colors["background"]
2    accent = _col_mix(ink, paper, 0.25)
    base_family = typography["base"]
    heading_family = typography["headings"]

    base_line_size = base_size / 22
    grid_major_colour = _col_mix(ink, paper, 0.8)
    grid_minor_colour = _col_mix(ink, paper, 0.9)

    return theme_minimal(
        base_size=base_size,
3        base_family=base_family
    ) + theme(
        plot_background=element_rect(fill=paper, colour="none"),
        panel_background=element_rect(fill=paper, colour="none"),
        panel_grid_major=element_line(colour=grid_major_colour, size=base_line_size),
        panel_grid_minor=element_line(colour=grid_minor_colour, size=base_line_size * 0.5),
        text=element_text(colour=ink),
        axis_title=element_text(family=heading_family),
        axis_line_x=element_line(colour=accent),
        axis_line_y=element_line(colour=accent),
        plot_title=element_text(
            family=heading_family,
            colour=accent,
            size=base_size * 2,
        ),
        plot_subtitle=element_text(colour=ink),
        legend_title=element_text(family=heading_family, colour=accent),
        legend_background=element_rect(fill=paper, colour="none"),
    )

library(ggplot2)
penguins <- read.csv("penguins.csv")

ggplot(penguins) +
  aes(x = bill_length_mm, y = bill_depth_mm, colour = species) +
  geom_point(na.rm = TRUE) +
  theme_brand(brand_mode = "light") +
  labs(title = "Light Mode", subtitle = "Using brand colours and fonts")

import polars as pl
from plotnine import aes, geom_point, ggplot, labs, scale_color_manual

penguins = pl.read_csv("penguins.csv", null_values="NA").drop_nulls(
    ["bill_length_mm", "bill_depth_mm"]
)

palette = get_brand_palette("light")

(
    ggplot(penguins.to_pandas())
    + aes(x="bill_length_mm", y="bill_depth_mm", color="species")
    + geom_point()
    + theme_brand(brand_mode="light")
    + scale_color_manual(values=palette)
    + labs(title="Light Mode", subtitle="Using brand colours and fonts")
)

7 Branded Tables

The gt_brand() function follows the same pattern: extract brand colours and fonts, then apply them to the table. Column headers get the first palette colour as a background, body borders use an accent derived from blending ink and paper, and the base and heading fonts are applied throughout.

gt_brand <- function(data, brand_mode = "light") {
  info <- get_brand_info()
  brand <- info[["format"]][["render"]][["brand"]]
  brand_data <- brand[[brand_mode]][["data"]]
  colors <- brand_data[["color"]]
  typography <- brand_data[["typography"]]
  palette <- unname(unlist(colors[["palette"]]))

  ink <- colors[["foreground"]]
  paper <- colors[["background"]]
  accent <- scales::col_mix(ink, paper, amount = 0.25)

  gt::gt(data) |>
1    gt::opt_table_font(font = typography[["base"]]) |>
    gt::tab_options(
2      table.background.color = paper,
      table.font.color = ink,
3      column_labels.background.color = palette[[1L]],
      column_labels.font.weight = "bold",
4      table_body.border.top.color = accent,
      table_body.border.bottom.color = accent
    ) |>
    gt::tab_style(
5      style = gt::cell_text(font = typography[["headings"]], color = paper),
      locations = gt::cells_column_labels()
    )
}

from great_tables import GT, loc, style

def gt_brand(data, brand_mode: str = "light") -> GT:
    info = get_brand_info()
    brand = info["format"]["render"]["brand"]
    brand_data = brand[brand_mode]["data"]
    colors = brand_data["color"]
    typography = brand_data["typography"]
    palette = list(colors["palette"].values())

    ink = colors["foreground"]
    paper = colors["background"]
    accent = _col_mix(ink, paper, 0.25)

    return (
        GT(data)
        .tab_options(
1            table_font_names=typography["base"],
2            table_font_color=ink,
            table_background_color=paper,
3            column_labels_background_color=palette[0] if palette else accent,
            column_labels_font_weight="bold",
4            table_body_border_top_color=accent,
            table_body_border_bottom_color=accent,
        )
        .tab_style(
            style=style.text(
                font=typography["headings"],
                color=paper,
5                weight="bold",
            ),
            locations=loc.column_labels(),
        )
    )

8 Light and Dark Mode

Quarto supports light and dark colour modes, and the brand data includes separate colour definitions for each. The helper functions accept a brand_mode parameter to select which variant to use.

For figures, Quarto’s renderings cell option generates both variants from a single code cell.

#| renderings: [light, dark]

The code loops over both modes and prints each plot. Quarto then displays the correct one based on the reader’s selected theme.

For tables, use Quarto’s .light-content and .dark-content CSS classes to conditionally display the appropriate version.

::: {.light-content}
Table rendered with `brand_mode = "light"`.
:::

::: {.dark-content}
Table rendered with `brand_mode = "dark"`.
:::

9 Putting It All Together

The full workflow boils down to four steps:

1. Call configure_brand_fonts() once in a hidden setup chunk (#| include: false) to register brand fonts before any plotting.
2. Apply theme_brand(brand_mode = ...) to every ggplot2 or plotnine figure.
3. Pass your data through gt_brand(data, brand_mode = ...) for every gt or great_tables table.
4. Use renderings: [light, dark] on figure cells and .light-content/.dark-content divs on tables so the reader’s theme preference is respected automatically.

That is the entire pattern. Every helper reads from the same QUARTO_EXECUTE_INFO source, so switching to a different brand configuration is just a matter of changing your _brand.yml file; no code changes are needed.

10 Conclusion

The QUARTO_EXECUTE_INFO environment variable provides language-agnostic access to Quarto’s resolved brand configuration at render time. With a small set of helper functions, you can apply consistent brand colours, fonts, and palettes to every figure and table your code produces.

This is one approach among several (see the note on brand.yml packages above), but it has the advantage of working identically in R and Python, supporting full font registration, and requiring no dependencies beyond a JSON parser and the plotting libraries you are already using. Browse the companion repository for six complete brand configurations with production-ready implementations, and feel free to adapt the helpers to your own projects.

11 Further Resources

• Multiformat Branding with _brand.yml: the official Quarto documentation on the brand feature.
• Execution Context Information: how QUARTO_EXECUTE_INFO works and what data it exposes.
• Execution Options: code cell options including renderings for light/dark mode.
• HTML Theming: customising HTML themes, Sass variables, and dark mode support.
• brand.yml Specification: the full specification and documentation for _brand.yml files.

1 Continuing from Part 1

Part 1 introduced the dual-layer architecture for building Quarto Typst templates. Here is a brief recap of the building blocks this tutorial relies on:

• Lua filters intercept Pandoc AST elements (spans, divs) and generate raw Typst code via pandoc.RawBlock and pandoc.RawInline.
• Typst rendering functions receive that generated code and produce styled output with access to document context.
• Wrapper functions in typst-show.typ bridge parse-time (Lua) and render-time (Typst), injecting runtime context such as colour schemes.
• build_wrapped_content handles the common pattern of wrapping div content with opening and closing Typst function calls, optionally extracting a title from the first heading.

This tutorial builds on those foundations with advanced patterns for production-quality extensions.

To keep the article and downloadable zip perfectly aligned, source-backed code blocks below show the full file content from the assets bundle. Each section highlights the exact functions to focus on, so you can scan purposefully instead of reading every line top-to-bottom.

2 Handler Factories: Reducing Repetition

As you add components, the same handler structure keeps appearing. Part 1’s panel handler called build_wrapped_content directly. With one or two components that is fine, but each new handler duplicates the same boilerplate:

(conceptual) without factories

local DIV_HANDLERS = {
  ['panel'] = function(div, config)
1    return build_wrapped_content(div, config, true)
  end,
  ['highlight'] = function(div, config)
2    return build_wrapped_content(div, config, false)
  end,
}

1

Extract title from first heading.

2

No title extraction; every new wrapped component repeats this same structure.

The only thing that varies is the extract_title flag. A factory function captures that variation in a closure, eliminating the repetition entirely. A closure is a function that remembers variables from the scope where it was created. When create_wrapped_handler(true) returns a new function, that function carries should_extract_title = true inside it, so every call to the returned handler automatically uses the correct flag without it needing to be passed again. This is necessary because the filter loop (shown below in “Using Factories”) calls each handler as DIV_FACTORY_HANDLERS[class](div, class_config), passing only the div element and the class config; the flag is never passed. By baking the flag into the closure at declaration time, each entry in DIV_FACTORY_HANDLERS becomes a self-contained handler with no extra parameters to manage.

_extensions/my-extension/_modules/wrapper.lua

local typst_utils = require(quarto.utils.resolve_path("_modules/typst-utils.lua"):gsub('%.lua$', ''))

local M = {
  attributes_to_table = typst_utils.attributes_to_table,
}

--- Extract first heading as title attribute
function M.extract_first_heading_as_title(el, attrs)
  if not attrs['title'] and #el.content > 0 then
    local first_elem = el.content[1]
    if first_elem.t == 'Header' then
      attrs['title'] = pandoc.utils.stringify(first_elem.content)
      local new_content = {}
      for i = 2, #el.content do
        table.insert(new_content, el.content[i])
      end
      el.content = new_content
    end
  end
end

--- Build Typst block wrappers with optional attributes
function M.build_typst_block_wrappers(config, attrs)
  local has_attributes = next(attrs) ~= nil

  if has_attributes or config.arguments then
    local attr_string = typst_utils.build_attribute_string(attrs)
    return string.format('#%s(%s)[', config.wrapper, attr_string), ']'
  else
    return string.format('#%s[', config.wrapper), ']'
  end
end

--- Build wrapped content for a div
function M.build_wrapped_content(div, config, should_extract_title)
  local attrs = typst_utils.attributes_to_table(div)
  if should_extract_title then
    M.extract_first_heading_as_title(div, attrs)
  end

  local opening, closing = M.build_typst_block_wrappers(config, attrs)
  local result = { pandoc.RawBlock('typst', opening) }
  for _, item in ipairs(div.content) do
    table.insert(result, item)
  end
  table.insert(result, pandoc.RawBlock('typst', closing))
  return result
end

--- Factory: create handler for wrapped content components
1function M.create_wrapped_handler(should_extract_title)
2  return function(div, config)
    return M.build_wrapped_content(div, config, should_extract_title)
  end
end

return M

_extensions/my-extension/typst-markdown.lua (handler tables excerpt)

local DIV_HANDLERS = {
1  ['quote-card'] = quote_card.process_div,
}

local DIV_FACTORY_HANDLERS = {
2  ['panel'] = wrapper.create_wrapped_handler(true),
3  ['highlight'] = wrapper.create_wrapped_handler(false),
}

_extensions/my-extension/typst-markdown.lua (Div filter excerpt)

for _, class in ipairs(div.classes) do
  local class_config = merged_div_config[class]
  if class_config then
1    if DIV_HANDLERS[class] then
      return DIV_HANDLERS[class](div, class_config)
    end

2    if DIV_FACTORY_HANDLERS[class] then
      return DIV_FACTORY_HANDLERS[class](div, class_config)
    end

3    return wrapper.build_wrapped_content(div, class_config, false)
  end
end

_extensions/my-extension/typst-markdown.lua (Span filter excerpt)

1for _, class in ipairs(span.classes) do
  local class_config = merged_span_config[class]
  if class_config then
2    local content = pandoc.utils.stringify(span.content)
    local attrs = typst_utils.attributes_to_table(span)
3    local attr_string = typst_utils.build_attribute_string(attrs)

    local typst_code
    if attr_string ~= '' then
4      typst_code = string.format('#%s(%s)[%s]', class_config.wrapper, attr_string, content)
    else
      typst_code = string.format('#%s[%s]', class_config.wrapper, content)
    end

5    return pandoc.RawInline('typst', typst_code)
  end
end

3 The Configuration System

A key design goal for reusable extensions is extensibility. Users should be able to add their own components or override built-in ones without modifying the extension’s source code. The configuration system enables this through metadata-driven element mappings.

_extensions/my-extension/_modules/config.lua (built-in mappings excerpt)

--- Return default div/span mappings for all components
function M.get_builtin_mappings()
  return {
    div = {
1      ['highlight'] = { wrapper = 'my-highlight', arguments = false },
2      ['panel'] = { wrapper = 'my-panel', arguments = true },
      ['quote-card'] = { wrapper = 'quote-card', arguments = true },
    },
    span = {
      ['badge'] = { wrapper = 'my-badge', arguments = true },
    },
  }
end

(conceptual) document.qmd

---
title: "My Document"
extensions:
1  typst-markdown:
    divs:
2      my-callout: my-custom-callout
3      my-box:
        function: my-custom-box
        arguments: true
    spans:
      my-highlight: my-text-highlight
---

(conceptual) document.qmd front matter

include-in-header:
  - text: |
      #let my-custom-box(content) = {
        block(fill: luma(240), radius: 4pt, inset: 1em, content)
      }

_extensions/my-extension/_modules/config.lua (user config excerpt)

local function meta_get(meta_map, wanted_key)
  if type(meta_map) ~= 'table' then return nil end
  if meta_map[wanted_key] ~= nil then return meta_map[wanted_key] end
  -- Pandoc meta maps may use non-string key objects; normalise via stringify.
  for key, value in pairs(meta_map) do
    if pandoc.utils.stringify(key) == wanted_key then return value end
  end
  return nil
end

--- Parse simple or detailed config format
local function parse_mapping(config)
1  if type(config) == 'string' then
    return { wrapper = config, arguments = false }
  end

2  local fn_name = meta_get(config, 'function') or meta_get(config, 'wrapper')
  if fn_name then
    local arg_value = meta_get(config, 'arguments')
    return {
      wrapper = pandoc.utils.stringify(fn_name),
      arguments = arg_value and pandoc.utils.stringify(arg_value) == 'true' or false,
    }
  end

  -- Simple form: `custom-highlight: my-custom-highlight`.
3  local simple_fn = pandoc.utils.stringify(config)
  if simple_fn ~= '' then
    return { wrapper = simple_fn, arguments = false }
  end

  return nil
end

_extensions/my-extension/_modules/config.lua (merge excerpt)

--- Merge configurations: user overrides built-in
function M.merge_configurations(builtin, user)
  local merged = {}
1  for class, cfg in pairs(builtin) do
    merged[class] = cfg
  end
2  for class, cfg in pairs(user) do
    merged[class] = cfg
  end
  return merged
end

4 Value Conversion and Type Safety

When passing values from Lua to Typst, type conversion matters. Strings need quoting. Numbers should not. Booleans map to Typst’s true/false. Getting this wrong produces syntax errors or unexpected behaviour.

_extensions/my-extension/_modules/typst-utils.lua

local M = {}

--- Convert a Lua value to Typst syntax
1function M.typst_value(value)
  if value == nil then
    return 'none'
  elseif type(value) == 'boolean' then
2    return value and 'true' or 'false'
  elseif type(value) == 'number' then
    return tostring(value)
  elseif type(value) == 'string' then
3    if value == 'none' or value == 'auto' or value == 'true' or value == 'false' then
      return value
    end
4    if value:match('^%-?%d+%.?%d*[a-z%%]+$') then
      return value
    end
5    return '"' .. value:gsub('"', '\\"') .. '"'
  else
    return '"' .. tostring(value):gsub('"', '\\"') .. '"'
  end
end

--- Convert element attributes to a plain Lua table
function M.attributes_to_table(element)
  local attrs = {}
  for key, value in pairs(element.attributes) do
    attrs[key] = value
  end
  return attrs
end

--- Build attribute string for Typst function calls
function M.build_attribute_string(attrs)
  local parts = {}
  for key, value in pairs(attrs) do
    local typst_key = key
    local typst_val = M.typst_value(value)
    table.insert(parts, string.format('%s: %s', typst_key, typst_val))
  end
  return table.concat(parts, ', ')
end

return M

1typst_value(nil)
2typst_value(true)
3typst_value(42)
4typst_value("hello")
5typst_value("1em")
6typst_value('none')
7typst_value('Say "hi"')