Extension Documentation

A Quarto extension usually comes with a template.qmd or an example.qmd. It shows the extension at work, and for years it was the only documentation mine had. But it is one document. The usage, the options, and the examples all end up on the same long page.

So I decided to give each extension a proper documentation website. The pages were not the problem, since each extension needs its own content anyway. The styling and the chrome were. A good Quarto website needs a navbar, a footer, a theme, edit and issue links, Open Graph and Twitter card tags, search, and some accessibility fixes. That is close to a hundred lines of YAML, plus a few style sheets and HTML files, before the first page. I did not want to keep forty copies of that in step by hand.

The atelier Project Type

Most Quarto extensions contribute a filter, a shortcode, or a format. An extension can also contribute a project type¹. It inherits from one of the base types (default, website, or book), and it sets the default values for _quarto.yml.

quarto-atelier is such an extension. I made it for the documentation websites of my extensions, so the styling and the chrome live in one place instead of forty. Its project type is called atelier, and it is a website underneath. A site that uses it writes very little:

_quarto.yml

project:
  type: atelier

website:
  title: "My Extension"
  site-url: https://example.org/my-extension
  repo-url: https://github.com/example/my-extension
  navbar:
    left:
      - href: index.qmd
        text: Home

The title, the URLs, and the navbar items belong to the site. Everything else comes from the extension.

Inherited Configuration

From those few lines, the site inherits:

• _site as the output directory, and edit and issue links to the repository.
• Open Graph and Twitter card tags, with en_GB as the locale and a large image card.
• Page navigation, a back to top link, a table of contents, and copy buttons on code blocks.
• An llms.txt file, and a search overlay in the navbar.
• A footer, and a theme that reads the site’s _brand.yml for its colours in light and dark mode.
• A filter that adds the og:type and og:url tags, which Quarto leaves out.
• Six small HTML scripts, among them a skip link and a few accessibility fixes.

Here are two of those sites: the documentation of quarto-atelier itself, and the one of quarto-typst-render. They share the same layout, sidebar, table of contents, and repository links. The colours differ, because each site has its own _brand.yml.

I checked this on a test site with only the lines above. The rendered page had the og:locale, og:type, and twitter:card tags, the skip link, and the edit and issue links beside the table of contents. The _site folder had an llms.txt next to the pages.

One tag needs one more key. Quarto does not pass the website block to filters, so the filter cannot read site-url there. For og:url, the site repeats its URL under the extension name:

_quarto.yml

extensions:
  atelier:
    site-url: https://example.org/my-extension

Each site keeps its own copy of the extension under _extensions/, so the update is not instant. In each repository, a scheduled GitHub Actions workflow runs Quarto Extensions Updater once a month, the action I wrote about in an earlier post. It compares the installed extensions with the Quarto extensions registry, using the same core library as Quarto Wizard. When quarto-atelier has a new release, it opens a pull request with the release notes, so every update is a change I can review before it lands.

Overriding the Defaults

The site can still change any inherited value. Quarto merges the defaults of the project type with the site’s _quarto.yml, and the site wins.

For example, atelier puts the search in the navbar as an overlay. The documentation site of quarto-badge has no navbar, only a sidebar. So it moves the search there:

_quarto.yml

website:
  search:
    location: sidebar
    type: textbox

The merge works key by key. On my test site, I replaced only the centre of the footer. The left part of the footer, which I did not touch, stayed as atelier set it.

Limitations

There are two limits to keep in mind.

First, lists are added together, not replaced. If a site adds its own script to include-after-body, it gets that script and the five from atelier. A site cannot remove one inherited script or filter. If a site needs that, the default does not belong in the shared project type.

Then, every site moves with the extension. That is the point, but it also means a bad default reaches all of them. The monthly pull requests are the safety net, because each site takes the change through its own review.

Your Own Project Type

atelier carries my own choices, from the locale to the footer. It is built for my sites, not for yours. But if you maintain several Quarto websites, I encourage you to write a project type of your own, under your own name.

atelier can serve as a starting point. The contributes: block in its _extension.yml holds the project type and the HTML format it uses, and the rest of the folder holds the files they point to. The source is on GitHub, and the documentation site is built with the project type itself.

To try it, or to read it inside a project of your own, install it with Quarto:

quarto add mcanouil/quarto-atelier

It needs Quarto 1.9.36 or later. Or install it from your editor with Quarto Wizard:

Happy publishing!

Preview a Typst Block

Writing Typst inside a Quarto document used to mean rendering the whole document to see one small block. Quarto Wizard 3.3 compiles the block under the cursor and shows the image beside the editor. It uses the Typst binary that ships inside Quarto, so there is nothing else to install.

Put the cursor inside a Typst block, then run Quarto Wizard: Preview Typst Block, or select the code lens above the block. The cell below draws the penguins with Gribouille, and the image beside it is what the render produces.

The panel then follows the cursor, and it compiles again after each edit. Move the cursor to another block, of any of the three kinds, and the panel shows that one instead.

The panel writes a failure over the last good image of the same block. The preview therefore does not go empty while you type.

The full compiler output goes to the Quarto Wizard log.

One Schema, Two Validators

The other half of 3.3 is for people who write extensions. It is about _schema.yml, the file where an extension declares every option, shortcode argument, format key, attribute and class that it accepts. If you only use extensions, this part changes nothing for you, beyond better messages from the extensions that adopt it.

Quarto Wizard has read that file for a while, to offer completion, hover documentation and diagnostics. A value of the wrong type, or a key the extension does not declare, is reported while you write.

That covers the editor only. Someone who writes an option by hand in _quarto.yml, with no editor to help, still reaches the render with a wrong value. So 3.3 publishes the Lua validator that reads the same file during the render.

The meta-schema is the file you point $schema at.

_extensions/my-extension/_schema.yml

$schema: https://m.canouil.dev/quarto-wizard/assets/schema/v2/extension-schema.json
options:
  theme:
    type: string
    description: "Colour theme for the extension output."
    default: light
    enum: [light, dark, auto]
  count:
    type: integer
    default: 3
    minimum: 1
    maximum: 100

The module is published as schema.lua. Its version is the version of the vocabulary, so the v2 module implements the v2 meta-schema. Vendor it into your extension, because a render must not need network access.

_extensions/my-extension/my-extension.lua

1local schema = require(quarto.utils.resolve_path('_modules/schema.lua'):gsub('%.lua$', ''))

2local options = schema.validate_options(
  meta,
  'my-extension',
  quarto.utils.resolve_path('_schema.yml')
)

1

Load the vendored copy by its absolute path. Lua keys its module cache by the name you pass, so require('_modules.schema') would hand the second extension of a render the copy of the first one.

2

Read meta.extensions.my-extension, test every value against the schema, and return the options with the defaults applied.

Errors and warnings go through the Quarto logger, and a schema that cannot be read never stops the render. Narrower entry points exist for a shortcode call, for the attributes of an element, and for a format block. The Using the Lua Validator page, added to the Quarto Wizard documentation in this release, describes each one.

The v2 meta-schema also accepts uniqueItems now. The validator already enforced that keyword, so a schema that used it was rejected by the meta-schema and accepted by the module. Both agree again.

Other Fixes

3.4 follows straight after 3.3, and it is about the two features above, so the list below holds both releases.

• An extension in a repository whose default branch is master installs without writing @master. The branch is read from GitHub when the repository has no release, no tag and no registry entry.
• A Typst block written between two --- lines that open no front matter is found. The rule the preview follows is the rule Pandoc applies.
• The search for Quarto projects no longer collects search processes. It applies your files.exclude and search.exclude settings, and it stops when a newer search replaces it.
• The preview reads a document again when that document takes the name of an untitled document you closed. It used to show you the blocks of the one before.
• A fenced block that a tab indents inside a blockquote is found, and a body line keeps the indent you wrote.
• A YAML diagnostic points at the key or the value it is about, rather than at the whole line, and an option written in flow style is checked as well.
• The Lua validator corrects two checks, accepts a name written with a hyphen where the schema declares it with an underscore, and reports a spelling that two attributes both declare. That last one used to leave the choice to the validator.

The changelog holds the full list, for 3.3 and for 3.4.

Happy writing!

1 Breaking changes

Four things change, and only the first is a rename. In the other three, a plot used to draw the wrong thing and now says so.

2 A theme from your brand

brand.yml is a small standard for writing a brand’s colours, fonts, and logos in one YAML file that several tools read. Quarto reads it, Shiny reads it, and the figures were the part that did not follow. theme-brand() closes that gap.

It takes the dictionary Typst’s yaml() returns, not a path, because Typst reads a relative path from the file that calls yaml. So you read the file, and theme-set() makes the result the default for every plot below it:

#theme-set(theme-brand(yaml("_brand.yml")))

The brand’s foreground, background, and primary become the theme’s ink, paper, and accent, and the gridlines, axis lines, and strips follow from that pair as they do under theme-minimal(). The roles left over, secondary, tertiary, success, info, warning, and danger, make the palette, in that order, with any repeated colour dropped.

The figure below writes the brand as a Typst dictionary, with the keys the standard defines, so you can read it here.

#let brand = (
  color: (
1    palette: (
      slate: "#0B2545",
      mist: "#E7EEF6",
      midnight: "#0A1622",
      frost: "#DCE6F2",
    ),
2    foreground: (light: "slate", dark: "frost"),
    background: (light: "mist", dark: "midnight"),
    primary: (light: "#D1495B", dark: "#FF7A8A"),
3    secondary: "#00798C",
    tertiary: "#EDAE49",
  ),
)

#plot(
  data: penguins,
  mapping: aes(x: "flipper-len", y: "body-mass", fill: "species"),
  layers: (geom-point(size: 2pt, alpha: 0.85, stroke: none),),
  labels: labels(
    title: "Body Mass Against Flipper Length",
    x: "Flipper Length (mm)",
    y: "Body Mass (g)",
    fill: "Species",
  ),
4  theme: theme-brand(brand),
  width: 12cm,
  height: 7cm,
)

The palette theme-brand() derives is nothing special: palette is a theme key like any other, so any theme takes one.

#theme-set(theme-minimal(
  palette: (rgb("#D1495B"), rgb("#00798C"), rgb("#EDAE49")),
))

Set it once and every discrete colour and fill scale in the document draws from it, which saves repeating scale-colour-manual(values: ...) on each plot. Three rules cover the rest:

• A scale that sets its own palette: keeps it.
• The default is palette: auto, which is the Okabe-Ito palette, as before.
• Continuous scales are not affected, and stay on viridis.

Brand colours are chosen to sit well together, and data colours need the opposite, so when a brand’s roles are too close to tell apart, pass palette: none:

#theme-brand(brand, palette: none)

The plot then keeps the brand’s paper, ink, and accent, and draws the data in Okabe-Ito.

3 Arrowheads on the lines

A line often shows a direction. Until now, showing it meant drawing the head yourself, in Typst, on top of the plot. Six line geoms take an arrow instead: geom-segment, geom-curve, geom-spoke, geom-path, geom-line, and geom-step. The three text geoms take it too, in place of the plain arrow: true they had before.

arrow() describes the head. length is how long each wing is, angle how far the wings open from the line, ends which end carries the head, and type whether it is an open V or a filled triangle.

#let teal = rgb("#1F7A8C")
#let gold = rgb("#B5830A")

#plot(
  data: economics,
  mapping: aes(x: "date", y: "unemploy"),
  layers: (
    geom-line(
      linewidth: 1pt,
      colour: teal,
1      arrow: arrow(length: 8pt, angle: 20deg),
    ),
    geom-segment(
      data: ((x: "2008-01-01", y: 6900, xend: "2009-10-01", yend: 6900),),
      mapping: aes(x: "x", y: "y", xend: "xend", yend: "yend"),
      colour: gold,
      linewidth: 0.8pt,
2      arrow: arrow(length: 6pt, ends: "both", type: "closed"),
    ),
    geom-text(
      data: ((x: "2008-11-01", y: 6900, label: "21 months"),),
      mapping: aes(x: "x", y: "y", label: "label"),
      colour: gold,
      size: 9pt,
      nudge-y: 600,
    ),
  ),
  scales: scales(x: scale-date(date-format: "[year]-[month repr:numerical]")),
  labels: labels(
    title: "Unemployment Through the 2008 Recession",
    x: "Date",
    y: "Unemployed (thousands)",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 7cm,
)

The head takes the colour and the thickness of the line it sits on, so it stays in step when a mapped colour or linewidth changes it. It also stays solid under a dashed linetype, because a dashed head looks like a rendering fault, not like a style.

4 Plots that fit the size you asked for

This is the long part of the release, and the one you are most likely to notice. A Gribouille plot has always taken a width and a height, and it did not always keep to them. A long tick label, a strip band, or a legend on the side needs room outside the panel, and when one of them needed more than the plot had kept back, the plot drew it anyway and grew past the size you asked for.

Two things change. A plot now draws at any size that gives it room to draw, so a figure can be genuinely small. Only an empty canvas, or one asked for at a negative width or height, fails on size alone.

#let teal = rgb("#1F7A8C")
#let gold = rgb("#B5830A")

1#let spark(column, colour) = plot(
  data: economics,
  mapping: aes(x: "date", y: column),
  layers: (geom-line(linewidth: 0.8pt, colour: colour),),
  scales: scales(x: scale-date()),
2  theme: theme-void(),
  width: 2.2cm,
  height: 0.7cm,
)

Unemployment #box(baseline: 30%, spark("unemploy", teal)) rose for most of the
window, while the savings rate #box(baseline: 30%, spark("psavert", gold))
peaked and eased back.

#v(0.4cm)

#plot(
  data: economics,
  mapping: aes(x: "date", y: "unemploy"),
  layers: (geom-line(linewidth: 1pt, colour: teal),),
  scales: scales(x: scale-date(date-format: "[year]-[month repr:numerical]")),
  labels: labels(x: "Date", y: "Unemployed (thousands)"),
  theme: theme-minimal(),
  width: 12cm,
  height: 5cm,
)

The second change is what happens when the figure does not fit. Before it draws, the plot counts the room each part needs, from the reach of the tick labels to the width of a side legend, the shared one compose() lifts out of its panels included, and shrinks the panel to leave that room. When shrinking the panel is not enough, it fails instead of drawing past its edge:

error: panicked with: plot: the x-axis tick labels reach 3.05 cm past the panel
on the right and the plot leaves them 1.6 cm. Increase `width`, rotate the
labels with `guides(x: guide-axis(angle: 45))`, shorten the labels with a
`labels:` function on the x scale, or shrink them with
`theme(axis-text: element-text(size: ...))`.

A strip label wider than its panel, and a legend that cannot fit, fail the same way, each saying what you can change.

Failing a compile is a blunt thing to do to a document that used to build. The alternative is worse: a figure that asks for width: 12cm and quietly takes fourteen is the kind of defect you find at the very end, in the PDF, once everything else is done.

A few smaller fixes come from the same work. An axis keeps room for its longest tick mark instead of for a fixed length, and a legend measures its title and its labels instead of guessing their size from the number of characters, so both give a little width back to the panel. A scale with no levels draws no legend at all, where it used to keep a box holding a title and no keys.

5 Log axes that read like logs

An automatic log axis breaks on one, two, and five times a power and writes each break as a plain number, which is a reasonable default but not how a log axis is usually read. Three pieces let you place and label the breaks as powers instead.

breaks-log(n: 5, base: 10) puts the breaks on powers of the base, filling the gaps with steps in between when too few powers fall inside the data range, as scales::breaks_log() does. The base is separate from the scale transform, so base: 2 places powers of two on a log10 axis.

format-log(base: 10, digits: 3) writes a break as a power with a real superscript, so 1000 reads as 10^3. A break that is not an exact power keeps its leading number, as the 3 × 10^4 label does below.

guide-axis-logticks() now draws two rows of smaller ticks below the labelled decades, the tick at five times a power coming from the new axis-ticks-mid theme entry and drawn longer than its neighbours. Set axis-ticks-mid: (length: 50%) for the old look, where every small tick had the same length.

#let growth = range(0, 25).map(month => (
  month: month,
  users: calc.round(120 * calc.pow(1.32, month)),
))

#plot(
  data: growth,
  mapping: aes(x: "month", y: "users"),
  layers: (geom-line(linewidth: 1pt, colour: rgb("#1F7A8C")),),
  scales: scales(
    y: scale-continuous(
      transform: "log10",
1      breaks: breaks-log(),
2      labels: format-log(),
    ),
  ),
3  guides: guides(y: guide-axis-logticks()),
  labels: labels(
    title: "A Series That Grows by a Third Every Month",
    x: "Month",
    y: "Users",
  ),
  theme: theme-minimal(
4    axis-line: element-line(stroke: 0.6pt),
    axis-ticks: element-tick(length: 0.25cm, stroke: 0.8pt),
    panel-grid-minor: element-blank(),
  ),
  width: 12cm,
  height: 7cm,
)

A log axis also draws one minor gridline between two decades, where it used to draw a line at every step in between and left the panel banded grey. n-minor sets that count as it does on any other continuous axis, n-minor: 0 removes the lines, and the steps in between stay where they belong, on the tick marks.

6 Polar plots that fit their circle

The radial coordinate system had several defects, all of them about space.

A coord-radial() plot now draws tick marks on its angular axis, from the axis-ticks theme entry, as a flat axis does. It also keeps room for the angular tick labels angle by angle, rather than taking the same band off every side of the circle.

Both panels ask for a 7 cm by 7 cm canvas, and the dashed frame is drawn at exactly that size. The 0.6 plot comes out 22 pt wider, about 0.8 cm of chart hanging outside the box the document gave it, and the 0.7 plot measures 7 cm by 7 cm. The source of that figure is in assets/_polar/, since every cell in this post compiles against one version and this one needs two.

Every panel of a faceted radial plot keeps its own tick labels, on the angle and on the radius. A radial panel rings them inside its own circle rather than along an edge it shares with a neighbour, so a panel in the middle used to be left with no scale to read against.

A pie built with coord-radial(theta: "y") reads its tick marks and its arc from the scale that carries the sweep, which is y. That is the breaking half of the same fix, so check any pie chart you have.

7 Faster on large data

Two defects made the cost of a plot grow with the square of the number of rows, and both are gone. Here are the same two charts compiled under every release.

1#let runs = csv(
  "assets/_benchmark/results.csv",
  row-type: dictionary,
)
2#let runs = as-numeric(as-numeric(runs, "rows"), "seconds")

#let median(values) = {
  let sorted = values.sorted()
  sorted.at(int(sorted.len() / 2))
}

3#let timings = summarise(
  runs,
  seconds: group => median(group.map(row => row.seconds)),
  by: ("chart", "rows", "version"),
)

#plot(
  data: timings,
  mapping: aes(x: "rows", y: "seconds", colour: "version", fill: "version"),
  layers: (
    geom-line(linewidth: 0.9pt),
    geom-point(size: 1.6pt, stroke: none),
  ),
  facet: facet-wrap("chart", scales: "free"),
  scales: scales(
    x: scale-continuous(labels: format-comma(digits: 0)),
    y: scale-continuous(transform: "log10"),
    colour: scale-viridis-d(),
    fill: scale-viridis-d(),
  ),
  guides: guides(fill: none),
  labels: labels(
    title: "Compile Time by Version",
    subtitle: "Median of three runs, latest patch of each minor version",
    x: "Rows",
    y: "Seconds",
    colour: "Version",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 6.5cm,
)

A boxplot of sixty-four thousand rows takes about 28 seconds under every version from 0.1 to 0.6, and 2.2 seconds under 0.7. The scatter draws one mark per row, so it still grows, and what is left of that growth is the marks rather than the grouping.

Smaller wins come with them: a discrete scale with your own limits, the scale resolution of a faceted plot, and the pass that measures titles and labels are all cheaper. The benchmarks guide carries the current numbers, and what they say is to count the marks rather than the rows.

8 Documentation

The examples are now grouped by what you want to show, not by the part of the API they use. The gallery is a page of cards leading to six pages about a kind of story and six about a feature, each card says what shape of data it needs, and eighteen new plots on the bundled datasets show it in practice.

9 Wrap-up

Next on the list is more geoms and more 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.

What the Report Is

demo-quarto-clinical-report is an abbreviated clinical study report, written in the section order of ICH E3¹. It has a synopsis, ethics, design, statistical methods, study patients, demographics, endpoints, safety, conclusions, and three appendices. The PDF is 50 pages, cover included, with 30 numbered tables, listings, and figures.

Two things before anything else. Nordvale Therapeutics is a fictional sponsor, invented for the demo. The data are the public CDISC pilot study CDISCPILOT01 shipped with pharmaverseadam, and the report is not a regulatory submission.

One Source, Two Formats

The project carries one extension, _extensions/nordvale/clinical, and that extension contributes two formats.

_extensions/nordvale/clinical/_extension.yml

contributes:
  formats:
1    common:
      toc: true
      toc-depth: 3
      number-sections: true
      lang: en-GB
2      crossref:
        custom:
          - kind: float
            key: listing
            reference-prefix: Listing
            caption-location: top
3    typst:
      template-partials:
        - typst-template.typ
        - typst-show.typ
      filters:
        - path: appendices.lua
          at: post-quarto
4        - path: tlf-numbers.lua
          at: post-quarto
      papersize: a4
      section-numbering: "1.1.1"
5      font-paths:
        - _extensions/nordvale/clinical/fonts
6    html:
      theme:
        - cosmo
        - brand
        - clinical.scss
      filters:
        - inline-svglite.lua
        - path: tlf-numbers.lua
          at: post-quarto

1

What both formats agree on, merged into each one.

2

A category of its own for the subject data listings. They are tabular data, and Quarto reserves lst for code, which it left-aligns and captions above.

3

The two template partials that build the pages, and appendices.lua, which letters the appendix chapters and numbers the floats by chapter.

4

The filter that gives every output its ICH E3 number, in both formats. See Every Output Has a Number.

5

The fonts travel with the extension, so the PDF does not depend on what is installed.

6

The theme, and inline-svglite.lua, which inlines the figures the svglite device draws so the page stylesheet resolves the brand fonts for them, as described in The Brand Reaches the Figures.

A document then asks for clinical-typst or clinical-html, and gets the sponsor identity with it.

The two renderings are not a screenshot of each other. They are the same chapter, computed once, laid out twice.

The Typst Template

typst-template.typ defines one function, clinical(), with the document metadata as its arguments. typst-show.typ is the piece that maps Quarto metadata onto that function, including the brand colours and the logo Quarto resolves from _brand.yml.

The cover page is a page of its own, with the band reaching the paper edge.

_extensions/nordvale/clinical/typst-template.typ

page(
1  margin: (x: 0mm, y: 0mm),
  header: none,
  footer: none,
  numbering: none,
  background: none,
)[
2  #block(width: 100%, height: 42mm, fill: primary, inset: (x: 20mm, y: 14mm))[
    #if logo != none {
      logo
    } else {
3      text(fill: paper, size: 20pt, weight: "semibold")[#sponsor]
    }
  ]
]

1

No margin on this page, so a filled block can reach the edge of the paper.

2

The band itself, coloured with the brand primary, with its own inset for the logo.

3

A sponsor with no logo still gets a cover, with the name set in the same place.

Then comes the document control page, which is the part a regulated document needs and a blog post rarely shows. It carries the revision history and the approval block, and both are written as metadata rather than as prose.

_metadata-csr.yml

1status: draft
2approvals:
  - name: Study Statistician
    role: Biostatistics
  - name: Clinical Study Lead
    role: Clinical Development
  - name: Medical Monitor
    role: Clinical Safety and Pharmacovigilance
3revisions:
  - version: "0.1"
    date: 2026-06-15
    summary: First draft for internal review.
  - version: "1.0"
    date: 2026-07-28
    summary: Statistical results added after database lock.

1

The one key that decides whether the document is a draft.

2

One entry per approver, in the order they appear on the page.

3

The revision history, printed as a table above the signatures.

The template turns each approval into a signature block.

_extensions/nordvale/clinical/typst-template.typ

#let signature-block(name, role, rule: gray) = block(
  width: 100%,
  inset: (top: 10pt, bottom: 6pt),
)[
1  #text(size: 10pt, weight: "semibold")[#name]
  #linebreak()
  #text(size: 9pt, fill: rule)[#role]
2  #v(26pt)
  #grid(
    columns: (1fr, 1fr),
    column-gutter: 12pt,
3    [#line(length: 100%, stroke: 0.6pt + rule) #text(size: 8pt, fill: rule)[Signature]],
    [#line(length: 100%, stroke: 0.6pt + rule) #text(size: 8pt, fill: rule)[Date]],
  )
]

1

The name and the role, taken from one entry of approvals.

2

The gap a pen needs, which is the only reason this block exists.

3

Two ruled lines, one for the signature and one for the date.

Two more pieces of furniture come from the same metadata. The running footer numbers the pages as X of Y, which Typst gives you with the final value of the page counter.

[Page #counter(page).display() of #counter(page).final().first()]

The watermark is one comparison, read once at the top of the template.

let is-draft = lower(status) == "draft"

The last piece is orientation. Two listings are wider than a portrait page, so the appendix wraps those two in a ::: {.landscape} div, and only those.

The Brand Reaches the Figures

_brand.yml holds nine named colours and three font families. The fonts are declared with source: file, and point at files bundled in the extension. The PDF then looks the same on my laptop and on a runner. Typst finds them through font-paths, and the HTML theme reads them from the brand.

The page furniture is the easy half. Figures and tables are the other half, because ggplot2 and gt know nothing about a Quarto brand.

This project uses the approach I described in Branded Figures and Tables in R and Python with Quarto, with its companion repository mcanouil/demo-quarto-brand-renderings as the reference implementation. Read that post for the principle, and for the Python side. Only the names change here: get_brand_info() became brand_raw() and brand(), theme_brand() became theme_nordvale(), and gt_brand() became gt_style_nordvale(). configure_brand_fonts() kept its name.

Quarto publishes the resolved brand in an environment variable at render time, so the helpers read it from there.

R/brand.R

brand_raw <- function() {
1  execute_info <- Sys.getenv("QUARTO_EXECUTE_INFO", unset = "")
  if (nzchar(execute_info)) {
    info <- jsonlite::fromJSON(execute_info)
2    brand <- info[["format"]][["render"]][["brand"]]
    if (!is.null(brand) && length(brand) > 0L) {
3      mode <- if ("light" %in% names(brand)) "light" else names(brand)[[1L]]
      return(brand[[mode]][["data"]])
    }
  }
4  yaml::read_yaml(brand_file())
}

1

Quarto sets this variable for every chunk it executes, and it holds the render context as JSON.

2

The brand Quarto resolved, after every _brand.yml in the project has been merged.

3

The report is printed, so the light mode is the one to take.

4

Outside a render there is no variable, so the helpers read the file and still work in a plain R session and in the tests.

From there, theme_nordvale() styles the plots, treatment_colours() fixes one colour per treatment group, and gt_style_nordvale() styles the tables. That last one stays inside the subset of gt options Quarto can translate to Typst: fonts, colours, borders, and alignment.

One HTML detail is worth the filter it took. The figures are drawn with svglite, and a standalone SVG file has to carry the fonts itself to display them. inline-svglite.lua puts the SVG content into the page instead of a link to the file. The page stylesheet then resolves the brand fonts, and the graphics device does not have to embed them.

Every Output Has a Number

Quarto numbers a table by where it falls in the document, so the first table of chapter 7 would be Table 7.1. A clinical study report is read by the ICH E3 output number instead, so that table is Table 14.2.1 wherever it sits. 14.2.1 reads as section 14, the displays that follow the text, then 2 for efficacy data, then the first table of that group. Demographic displays sit under 14.1 and safety displays under 14.3, while the subject data listings sit under 16.2, where 16.2.7 is the adverse event listing. The guideline stops at the group, and the digits after it are the sponsor’s own sequence. That is why the per-protocol version of 14.2.1 is 14.2.1.1. Tables and figures run as separate series, so a Table 14.2.1 and a Figure 14.2.1 both exist.

The report prints the E3 number, in the caption and in every reference to it. A reviewer asks for 14.3.1.2 and gets the same kind of output in any study from any sponsor.

R/tlf-index.R is where every output number lives, and no other file in the project states one.

R/tlf-index.R

tlf_entry_spec(
1  key = "tte",
2  ref = "tbl-tte",
  kind = "Table",
3  number = "14.2.1",
  section = "14.2",
4  title = "Time to first dermatologic treatment-emergent adverse event",
  subtitle = "Intention-to-treat population",
5  source_note = "Medians and confidence intervals are Kaplan-Meier estimates. ..."
)

1

The name the R code calls the output by. tlf_entry() stops with an error on a key it does not know, so a typo fails the render instead of printing an empty caption.

2

The cross-reference identifier, which every reference in the report points at.

3

The ICH E3 number, which the report prints, and the E3 section it belongs to, which the index of outputs prints.

4

The title and the population, which tlf_caption() writes under the output.

5

The source note, which tlf_output() attaches to the table itself.

A section then wraps the output in a cross-reference div and asks the index for the caption.

sections/07-efficacy.qmd

::: {#tbl-tte}

```{r}
#| label: tte

tlf_output(tlf_tte_summary(adtte), "tte")
```

`{r} tlf_caption("tte")`

:::

Getting that number onto the page took more than metadata. Quarto builds a float number from the chapter and a running count, and nothing in the document can set it. A custom cross-reference type names the prefix, not the number. So the pre-render step writes the numbers to a file, and a filter applies them, differently in each format. In HTML the filter sets the number on the float, which Quarto then stringifies into the caption. In Typst it emits one show rule per label, because Typst numbers its own figures and ignores what the filter did to the float.

An HTML book needs one more step. Quarto writes its cross-reference index before any extension filter runs. A book then fills every reference from that index after Pandoc, so a filter never reaches those numbers. A post-render step renumbers them on the rendered pages instead.

The appendix then lists every output. tlf_catalogue() prints the index as a definition list, where each term is a cross-reference that resolves to the ICH E3 number, and each description carries the E3 section and the population.

Changing an output number is a one-line edit in one file, and every mention of it follows.

Book or One Long Document

A format is not tied to one kind of project, and this one shows it. The same extension renders the same sections as a Quarto book and as a single long document, and a profile picks between them. _quarto-book.yml builds the book. _quarto-doc.yml renders csr.qmd, which is nothing but includes, alongside the companion statistical analysis plan.

quarto render                 # the book, in _book/
quarto render --profile doc   # the single document, in _doc/

Both project types produce a Typst PDF and an HTML output. The PDF comes out much the same either way, 50 pages in both, so the project type hardly shows there. The HTML is where it shows, and the book is the one I recommend to use. Each chapter becomes a page of its own, with a sidebar and a search box. A reviewer can then send a link straight to the section they ask about.

The study metadata that both share sits in _metadata.yml. The per-document keys do not, and that is deliberate. A shared _metadata.yml is always merged, and merging concatenates list values instead of replacing them. Put those keys in the shared file, and the approvals of the analysis plan join the approvals of the report. They live in _metadata-csr.yml instead, which the report loads, while sap.qmd sets its own.

Checking the Numbers

A report of computed numbers needs something to check those numbers. The project has three test files, and the workflow runs them before it renders anything.

test-invariants.R checks the properties every table quietly relies on. The population flags nest as the methods chapter claims. A reason for discontinuation is present exactly for the subjects who did not complete. No subject is lost between the source data and the analysis datasets.

test-independent-test.R recomputes every headline number the prose states, from the source packages rather than from the derived datasets. If R/00-adam.R gets a filter wrong, the test disagrees instead of restating the mistake.

test-double-programming.R refits the models by a second route and compares the results with the strings the report prints. It catches a wrong estimate, a wrong reference group, or a transposed confidence interval, which no structural test can see.

The reproducibility appendix carries the rest of the traceability. It holds the analysis results datasets gtsummary keeps behind each table, a define.xml-style metadata excerpt, and the empty table shells next to the locked table. It also holds the session information, and an renv lockfile snapshotted in explicit mode from DESCRIPTION.

What I Would Watch Out For

Four things are worth knowing before you start. None of them are hard once you know where to look, and each one can cost an afternoon if you do not.

Floats numbered by chapter.

Typst numbers figures from one counter, and Quarto zeroes that counter at each chapter. Typst is never told which chapter it is in, so every chapter opened with “Table 1”. appendices.lua reads the chapter from the heading counter and prefixes the float number with it. The same filter gives the appendices their letters.

Tables that do not break.

Quarto wraps every cross-referenced float in a figure, and a figure block is not breakable. A table taller than the space left overflowed the page instead of continuing on the next one. One show rule fixes it, and Typst then repeats the header rows on each page.

show figure.where(kind: "quarto-float-tbl"): set block(breakable: true)

Plots stay unbreakable, so an image never parts from its caption.

Counting before filtering.

A few subjects in the pilot data have a last date known to be alive that precedes their first dose. The report discloses how many, and that count is taken from the unfiltered derivation on purpose. Taken after the filter, the count can report zero one day, and turn a disclosure into a false statement.

Defaults that are not neutral.

emmeans::contrast(method = "trt.vs.ctrl") applies a Dunnett-style multiplicity adjustment by default. That adjustment widens the intervals beyond what the statistical methods chapter and the analysis plan describe. The secondary endpoint is descriptive here, so the call passes adjust = "none" and says so.

Render It Yourself

You need Quarto 1.10.18 or later, for the quarto.language variables the Typst template reads, and R 4.4 or later.

Rscript -e 'renv::restore()'
quarto render

The repository is at mcanouil/demo-quarto-clinical-report, and the rendered report is published at https://m.canouil.dev/demo-quarto-clinical-report/. Here is the whole PDF, the one the workflow publishes on every push to main.

Open it full size: Typst PDF, HTML book.

Hope this shows that Quarto can be used in such context while providing profesional outputs.

Happy publishing!

1 Breaking changes

Two names change, and only one of them is likely to be in your documents.

2 Wrangling data

A Gribouille dataset is a row-store, an array of dictionaries with one dictionary per row. That is a plain Typst array, so a good part of the preparation is already a one-liner: data.filter(...) keeps rows, data.map(...) derives a column, data.sorted(key: ...) orders them. What Typst leaves open is grouped aggregation, reshaping, and joining, and that is what the new verbs do. They all take a row-store and return a row-store, so the result goes straight into #plot with nothing in between.

summarise() collapses each group to one row. The grouping is per call, through by:, so there is no grouped state to remember to undo[^If you are a dplyr user, you know what I am talking about.]. Each aggregation is a closure that receives the group’s rows and returns one cell, so anything you can compute over the rows is fair game.

#let by-class = summarise(
  mpg,
1  mean-hwy: rows => rows.map(row => row.hwy).sum() / rows.len(),
  n: rows => rows.len(),
2  by: "class",
3).sorted(key: row => row.mean-hwy)

#plot(
  data: by-class,
  mapping: aes(x: "class", y: "mean-hwy"),
  layers: (
    geom-col(fill: okabe-ito.at(4)),
4    geom-text(mapping: aes(label: "n"), anchor: "south", size: 8pt),
  ),
  scales: scales(
    x: scale-discrete(limits: by-class.map(row => row.class)),
  ),
  labels: labels(
    title: "Fuel Economy by Vehicle Class",
    x: "Vehicle Class",
    y: "Mean Highway mpg",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 7cm,
)

When the aggregation is just a tally, count() is the short form: it groups by the columns you name, adds an n column, and sort: true orders the groups from most to least frequent.

Two columns that measure the same thing are usually easier to plot once melted into one value column with a label column beside it. pivot-longer() does that, and pivot-wider() spreads them back.

#let long = pivot-longer(
  mpg,
1  ("cty", "hwy"),
2  names-to: "metric",
  values-to: "mpg",
)

#plot(
  data: long,
  mapping: aes(x: "metric", y: "mpg", fill: "metric"),
  layers: (geom-boxplot(),),
3  facet: facet-wrap("cyl"),
  scales: scales(fill: scale-okabe-ito()),
  labels: labels(
    title: "City Against Highway, by Cylinder Count",
    x: "Metric",
    y: "Miles per Gallon",
    fill: "Metric",
  ),
  guides: guides(fill: none),
  theme: theme-minimal(),
  width: 12cm,
  height: 7cm,
)

Enriching a dataset with a lookup table is a join, not a dictionary read per row. Build the lookup as its own small row-store and left-join() it on the shared key.

#let by-class = summarise(
  mpg,
  mean-hwy: rows => rows.map(row => row.hwy).sum() / rows.len(),
  by: "class",
).sorted(key: row => row.mean-hwy)

1#let kind = (
  (class: "compact", kind: "Car"),
  (class: "subcompact", kind: "Car"),
  (class: "midsize", kind: "Car"),
  (class: "2seater", kind: "Car"),
  (class: "minivan", kind: "Van"),
  (class: "suv", kind: "SUV"),
  (class: "pickup", kind: "Truck"),
)

2#let enriched = left-join(by-class, kind, by: "class")

#plot(
  data: enriched,
  mapping: aes(x: "class", y: "mean-hwy", fill: "kind"),
  layers: (geom-col(),),
  scales: scales(
    x: scale-discrete(limits: enriched.map(row => row.class)),
    fill: scale-okabe-ito(),
  ),
  labels: labels(
    title: "Economy by Class and by Kind",
    x: "Vehicle Class",
    y: "Mean Highway mpg",
    fill: "Kind",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 7cm,
)

One more thing before the plot, for real files. A CSV arrives as strings, and missing values are spelled in as many ways as there are people producing the files. as-numeric() now takes an na: list of sentinel values, blanking them before it parses, so a placeholder does not survive as a number.

#let raw = csv("vehicles.csv", row-type: dictionary)
#let clean = drop-na(as-numeric(raw, "hwy", na: ("NA", "-99")), "hwy")

The Wrangling data guide walks the whole path, from coercion to the plot, and it also says which tasks need no verb at all.

3 Breaks that land on round numbers

Until now, automatic breaks came from a fixed 1/2/5 ladder: pick the step from that list, cover the range. It is simple, and it is regularly a bit off, either too far from the data or with more ticks than anyone asked for. 0.6.0 replaces it with the extended Wilkinson search [@talbot_extension_2010]GitHub. It scores candidate tick sequences on three things at once: how simple the numbers are, how well they cover the data, and how close the count lands to the target. There is nothing to change in your code, plots come out with rounder ticks that sit closer to the data.

The same search is available as breaks-extended(n:) when you want a different tick count. It is one of four helpers that build a closure for the breaks: and minor-breaks: arguments of a continuous scale. The closure is called with the values the scale trained on, once per panel, and returns the positions, so free-scale facets each get their own.

#plot(
  data: economics,
  mapping: aes(x: "date", y: "unemploy"),
  layers: (
    geom-line(colour: okabe-ito.at(5), linewidth: 1.5pt),
    geom-point(size: 2pt, fill: okabe-ito.at(5), stroke: none),
  ),
  scales: scales(
    x: scale-date(date-format: "[year]-[month repr:numerical]"),
    y: scale-continuous(
1      breaks: breaks-quantile(),
2      minor-breaks: breaks-width(500),
3      labels: format-comma(digits: 0),
    ),
  ),
  labels: labels(
    title: "Ticks Where the Data Sits",
    x: "Date",
    y: "Unemployed (thousands)",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 7cm,
)

A closure and an explicit array of breaks are not treated the same way, and the difference matters. An explicit array widens the axis so every requested tick stays visible. Closure breaks are clipped to the trained domain instead, since the closure has seen the data and cannot ask for anything outside it.

A related fix landed with them. A scale trained on whole numbers only, such as years or counts, now keeps whole automatic breaks, so a narrow range like 2020 to 2023 no longer labels half-steps.

4 Ticks, in one element

Tick marks used to be described in two places: their colour and stroke in axis-ticks, their length in a separate tick-length with its own per-axis and per-side variants. They are one record now. element-tick(colour:, stroke:, length:) carries all three, on axis-ticks and on its per-axis, per-side, and minor variants.

#plot(
  data: penguins,
  mapping: aes(x: "flipper-len", y: "body-mass", fill: "species"),
  layers: (geom-point(size: 2pt, alpha: 0.8, stroke: none),),
  scales: scales(
1    y: scale-continuous(secondary: dup-axis()),
    fill: scale-okabe-ito(),
  ),
  labels: labels(
    title: "One Record per Tick Mark",
    x: "Flipper Length (mm)",
    y: "Body Mass (g)",
    fill: "Species",
  ),
  theme: theme-minimal(
    axis-line: element-line(stroke: 0.5pt),
2    axis-ticks: element-tick(length: 0.25cm, stroke: 0.8pt),
3    axis-ticks-y: element-tick(length: 50%),
4    axis-text-y-right: element-blank(),
  ),
  width: 12cm,
  height: 7cm,
)

Minor marks follow the same record through axis-ticks-minor. The sub-decade ticks that guide-axis-logticks() adds on a log axis used to be hardcoded at half length in the major stroke. They are themable now, and they inherit the major record, so the default look is unchanged.

5 Label Alignment Fix

The usual share of fixes rides along.

The one you are most likely to notice is vertical alignment of labels (#208GitHub). Legend entries, vertical colourbar tick labels, and y-axis tick labels now centre on the cap-height and baseline band instead of the glyph bounds. A label carrying a descender, Chinstrap next to Adelie, no longer sits a little higher than its neighbours.

6 Filling the documentation gaps

A good share of this release was writing down what was already there.

The reference pages had a real hole in them (#211GitHub). A scale-* constructor takes ..args, and the page described a few of those keys in prose, which left the rest to be found by reading the source. Every scale-* page now lists each key it accepts, with its type, its accepted values, and its default. That includes oob, the out-of-range handling, which no page documented at all.

Cross-references are links again. A reference that closed a parenthetical printed as a bare @geom-line instead of a link, and a link sometimes ran into the word or the comma before it.

Two guides changed. The Wrangling data guide is new, and it starts where the data does: coercion, then grouped aggregation, reshaping, joining, and the plot at the end. It also lists the tasks that need no verb at all, because filter, map, and sorted already do them. The theming guide gains a “Ticks and their labels” section covering element-tick, ratio lengths, minor marks, and hiding labels per side.

The site itself got a pass for legibility. The GitHub icon in the navbar is a widget now. It shows the live star and fork counts and opens a project menu: repository, issues, pull requests, releases, star, fork, Typst Universe, and sponsoring. It replaces the separate links that used to sit in the navbar, and it shares one pill button style with the version switcher, the search button, and the scheme toggle.

7 Wrap-up

Next on the list is more geoms and more 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.

1 The Problem

I write training material as one index.qmd per module. Each module produces a handout, an exercise booklet, and a slide deck, in HTML, in PDF through Typst, and in reveal.js. The prose is the same in all of them, so the source has to be the same too.

Three things get in the way.

First, heading levels do not mean the same thing in each format. A ## is a section in the handout and a slide in the deck, and Typst shifts the levels on its own when the document has no level-1 heading.

Then, some attributes only make sense in one format. A table that fits the page is too tall on a slide, so it needs a smaller font there and nowhere else.

Finally, a slide break has no meaning outside the deck. A --- splits a slide in reveal.js, but the continuation slide loses its heading, and the rule itself has nothing to do in the HTML or the PDF.

The usual answer is content-visible when-format="...", which means writing the block once per format. That is exactly the duplication I wanted to avoid.

2 Installing Them

I manage my extensions with Quarto Wizard, an extension for Visual Studio Code, Positron, and VSCodium. It browses the Quarto Extensions listing, installs an extension into your project, and tells you when one you already have has a newer release. That last part is why I recommend it over the command line: quarto add installs an extension, but nothing then keeps track of what you have and what has moved on.

The buttons below open your editor and ask Quarto Wizard to install the extension into the current project.

The same three extensions from the command line, if you prefer it:

quarto add mcanouil/quarto-offset-headings
quarto add mcanouil/quarto-prism
quarto add mcanouil/quarto-revealjs-cascade

Each section below then shows the filters: entry that turns the extension on.

3 Heading Levels

Pandoc already has shift-heading-level-by, and Quarto exposes it. But it runs as a final pass, after every Lua filter has finished. No filter can see the shifted levels, and the value applies to the whole document, so you cannot move a single heading.

offset-headings does the same job as a filter instead.

filters:
  - offset-headings

You can shift every heading at once:

extensions:
  offset-headings:
    by: 1

Or one heading, with an attribute:

## Section {offset-headings-by="-1"}

The offset flows down to the nested headings by default, so a whole branch moves together. offset-headings-depth bounds how far it flows, offset-headings-max-level caps the level it can reach, and offset-headings-recursive="false" keeps the offset on the attributed heading alone. The document offset and the per-heading offset always add up, and the result is clamped to [1, 6].

shift-heading-level-by: 0

4 Format-Specific Attributes

prism reads attributes keyed by format, and keeps the ones that match the format being rendered.

filters:
  - prism

Each key is written format:name="value". When the format matches, the attribute is re-emitted as name="value"; otherwise it is dropped. Classes and identifiers are left alone, and unprefixed attributes pass through.

::: {revealjs:style="font-size: 2em;" html:style="font-size: 1.2rem;"}
Same paragraph, two sizes.
:::

It works on divs, spans, code blocks, and headings. The format name is matched exactly against the Quarto target format, which includes custom formats. Under a custom mcanouil-typst format, only mcanouil-typst: matches, not typst:. The built-in PDF format is targeted with pdf:, since that is the format name Quarto requests, not the writer it happens to use underneath.

Two prefixes save repetition. slide: covers every HTML slide format, and default: provides a fallback used only when nothing more specific matched.

::: {default:style="color: gray;" html:style="color: crimson;"}
Crimson in HTML, gray everywhere else.
:::

The order is exact format, then group alias, then default:, then the unprefixed value.

A dropped attribute is silent by design, since a future format with that name would pick it up. That also hides a typo such as revaeljs:style, so turn the warning on while you write:

extensions:
  prism:
    warn-on-drop: true

5 Slide Breaks

cascade repeats the current heading chain whenever a --- starts a continuation slide.

filters:
  - cascade

You write the heading once and split as often as you need. The rule is removed from the non-reveal.js formats, so the same source still reads as continuous prose in the handout and the PDF. Set keep-hrule: true if you want the rule kept there.

.no-cascade on a heading keeps it off the continuation slides, depth limits how many levels of the chain are repeated, and cascade-depth overrides that depth for one chain. I covered the slide side of it in more detail in a previous post on reveal.js extensions.

6 Putting Them Together

The demo below is one demo.qmd rendered to the three formats, with nothing format-specific in the body other than attributes.

The project file declares the three filters and the three outputs.

_quarto.yml

filters:
  - prism
  - offset-headings
  - cascade

extensions:
  prism:
    warn-on-drop: true
  offset-headings:
    quarto-shift-warning: false

The order matters, and it is the order of the filters: list, since all three register at pre-ast. prism runs first, so the attributes it promotes are plain attributes by the time the others look at them. cascade runs last, so it sees the final heading levels when it builds the chain to repeat.

_quarto.yml

format:
  html:
    output-file: demo.html
    embed-resources: true
    toc: true
  typst:
    output-file: demo.pdf
    shift-heading-level-by: 0
  revealjs:
    output-file: demo-slides.html
    embed-resources: true

Both filters then meet on the same heading.

demo.qmd

## Reading a File {revealjs:offset-headings-by="-1" revealjs:offset-headings-depth="1"}

### From a CSV file

prism turns revealjs:offset-headings-by into offset-headings-by on the deck and drops it elsewhere. offset-headings then promotes the heading and its subsection by one level, so the section becomes a title slide and its subsections become slides. In the handout and the PDF, the same two headings stay at level 2 and level 3.

The code block shrinks on the deck only.

demo.qmd

```{.r revealjs:style="font-size: 0.7em;"}
penguins <- read.csv("penguins.csv")
str(penguins)
```

The --- splits the slide, and cascade puts ### From a CSV file back on top of the continuation.

demo.qmd

The `str()` call prints the structure of the object, so you can check the column types before going further.

---

Two arguments matter more than the others.

- `stringsAsFactors` controls whether character columns become factors.
- `na.strings` lists the values to read as missing.

The table gets a width in the HTML handout and a smaller font on the deck, from a single wrapper. Typst ignores max-width, so the PDF falls back to its own table sizing.

demo.qmd

::: {revealjs:style="font-size: 0.6em;" default:style="max-width: 40em;"}

| Function       | Separator | Decimal mark |
| -------------- | --------- | ------------ |
| `read.csv()`   | `,`       | `.`          |
| `read.csv2()`  | `;`       | `,`          |
| `read.delim()` | tab       | `.`          |

:::

Here are the three outputs, rendered from that one file.

The HTML handout, with the headings at their written levels and no slide break in sight.

The PDF, through Typst, with the same heading levels as the HTML.

The deck, with the promoted headings and the repeated heading on the continuation slide.

Open them full size: HTML, Typst PDF, Reveal.js.

7 Gotchas

8 Wrapping Up

Each of these filters started as an annoyance in a real document, and each one removed a block of duplicated content. Together they let one source stay one source.

Happy writing!

1 Breaking changes

Two changes need your attention before your old code compiles. Neither changes what a plot looks like, only how you spell the scales.

There is one more change, but it is internal. Every constructor dictionary now stores its concrete type under a single name: key. This only matters if you pattern-match the dictionaries a constructor returns; the way you call them in a plot is unchanged.

2 A keyed scales()

The old scale names spelled the aesthetic into the function: scale-colour-viridis-d, scale-x-log10, scale-fill-manual. That meant one constructor per aesthetic, and a long list of near-duplicates. Now there is one aesthetic-agnostic set, and the aesthetic comes from the key you bind it to inside scales(), exactly like guides().

#plot(
  data: penguins,
  mapping: aes(x: "flipper-len", y: "body-mass", fill: "species"),
  layers: (geom-point(
    size: 2pt,
    alpha: 0.8,
    stroke: 1pt,
    colour: rgb("#fafafa")
  ),),
1  scales: scales(
2    y: scale-log10(breaks: (3000, 4000, 5000, 6000)),
3    fill: scale-okabe-ito(),
  ),
  labels: labels(
    title: "One scales(), Keyed by Aesthetic",
    x: "Flipper Length (mm)",
    y: "Body Mass (g)",
    fill: "Species",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 8cm,
)

scales() is more than a tidy wrapper. You could hand plot() a plain named dictionary, (colour: scale-okabe-ito()), and it would look the same. The difference is that scales() checks every entry as it binds it, before the plot draws. A positional argument, an aesthetic key that does not exist, or a value that is not a scale spec each stops with a clear message that lists the valid names. A plain dictionary would keep a misspelled key like colur: and quietly drop the scale, so the plot would render with the wrong colours and no error to point at. An unknown argument to a scale-* constructor is caught at the same moment, reported with the keys that scale accepts for that aesthetic.

3 Native density

Density estimation is the heart of this release. geom-density() evaluates a Gaussian kernel on a grid and draws the smooth curve, all in Typst, with no external runtime. The bandwidth is chosen by Silverman’s rule and tuned with adjust; trim cuts the curve to the data range.

#plot(
  data: penguins,
  mapping: aes(x: "flipper-len", fill: "species"),
  layers: (
1    geom-density(alpha: 0.5, adjust: 1),
  ),
  scales: scales(fill: scale-okabe-ito()),
  labels: labels(
    title: "Flipper Length, One Density per Species",
    x: "Flipper Length (mm)",
    y: "Density",
    fill: "Species",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 7cm,
)

The stat exposes the usual after-stat columns, _density, _count, _scaled, and _n, so you can map y to a count instead of a density when that reads better.

4 Violins and beeswarms

A violin is the same density, mirrored and turned on its side. geom-violin() draws one silhouette per group, normalised by scale. geom-beeswarm() spreads the raw points into a deterministic, density-shaped swarm, a reproducible alternative to jitter. Layer the swarm over the violin and every penguin sits inside its own silhouette.

#plot(
  data: penguins,
  mapping: aes(x: "species", y: "body-mass", fill: "species"),
  layers: (
1    geom-violin(scale: "width", trim: false, alpha: 0.4),
2    geom-beeswarm(
      size: 2pt,
      colour: rgb("#fafafa"),
      stroke: 0.4pt,
      alpha: 0.95,
    ),
  ),
  scales: scales(fill: scale-okabe-ito()),
  labels: labels(
    title: "Every Penguin in Its Violin",
    x: "Species",
    y: "Body Mass (g)",
    fill: "Species",
  ),
  guides: guides(fill: none),
  theme: theme-minimal(),
  width: 12cm,
  height: 8cm,
)

5 Two dimensions at once

For a scatter that is too dense to read, a two-dimensional density shows where the mass sits. geom-density-2d-filled() shades filled iso-bands of the joint density; geom-density-2d() draws the iso-lines instead.

#plot(
  data: penguins,
  mapping: aes(x: "flipper-len", y: "body-mass"),
  layers: (
1    geom-density-2d-filled(),
  ),
  scales: scales(
    x: scale-continuous(expand: (0%, 0%)),
    y: scale-continuous(expand: (0%, 0%)),
    fill: scale-fermenter(palette: "YlGnBu")
  ),
  labels: labels(
    title: "Where the Penguins Cluster",
    x: "Flipper Length (mm)",
    y: "Body Mass (g)",
  ),
  guides: guides(fill: none),
  theme: theme-minimal(),
  width: 12cm,
  height: 8cm,
)

6 Ridgelines

When a plain overlap gets crowded, a ridgeline offsets each density up the panel. geom-density-ridges() draws one ridge per y level, with heights normalised across levels so they compare fairly.

#plot(
  data: penguins,
  mapping: aes(x: "body-mass", y: "species", fill: "species"),
  layers: (
1    geom-density-ridges(scale: 1.5, alpha: 0.85),
  ),
  scales: scales(
2    y: scale-discrete(expand: (auto, 55%)),
    fill: scale-okabe-ito(),
  ),
  labels: labels(
    title: "Body Mass, Ridge by Ridge",
    x: "Body Mass (g)",
    y: "Species",
    fill: "Species",
  ),
  guides: guides(fill: none),
  theme: theme-minimal(),
  width: 12cm,
  height: 8cm,
)

7 A LOESS smoother

Until now, fitted straight lines were the only smoothers geom-smooth() could draw (method: "lm"). Now geom-smooth() also takes method: "loess", a local polynomial fit with a pointwise confidence band.

#plot(
  data: penguins,
  mapping: aes(x: "flipper-len", y: "body-mass"),
  layers: (
    geom-point(size: 2pt, alpha: 0.5),
1    geom-smooth(method: "loess", span: 0.75, degree: 2),
  ),
  labels: labels(
    title: "A Local Fit, Not a Straight Line",
    x: "Flipper Length (mm)",
    y: "Body Mass (g)",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 8cm,
)

8 Difference bands

stat-difference shades the band between two series by which one is on top. Feed it ymin and ymax, map fill: after-stat("_sign"), and it splits the ribbon at every crossover, filling the gap in the colour of whichever line leads.

#let d = range(0, 25).map(i => {
  let x = i / 2
  (x: x, a: 10 + 4 * calc.sin(x * 0.7), b: 10 + 3.2 * calc.cos(x * 0.55))
})

#plot(
  data: d,
1  mapping: aes(x: "x", ymin: "a", ymax: "b", fill: after-stat("_sign")),
  layers: (
    geom-ribbon(
2      stat: stat-difference(levels: ("A leads", "B leads")),
      alpha: 0.5,
      stroke: none,
    ),
    geom-line(mapping: aes(y: "a"), linewidth: 1pt),
    geom-line(mapping: aes(y: "b"), linewidth: 1pt, linetype: "dashed"),
  ),
  scales: scales(fill: scale-manual(values: (rgb("#0072B2"), rgb("#D55E00")))),
  labels: labels(title: "Which Series Is on Top", x: "Week", y: "Value", fill: none),
  theme: theme-minimal(),
  width: 12cm,
  height: 7cm,
)

9 Pattern fills

A fill no longer has to be a flat colour. When colour/fill is not enough or is too much, a pattern can carry the information instead which helps improve accessibility and printability. Fills now accept native Typst tiling patterns, both as a fixed fill: and through scale-manual(values:), and the legend swatches draw the patterns too. This is what keeps a bar chart readable once it is printed in black and white.

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

1#let stripes = tiling(size: (6pt, 6pt))[
  #place(rect(width: 100%, height: 100%, fill: cb.at(0).lighten(60%)))
  #place(line(start: (0%, 100%), end: (100%, 0%), stroke: 1pt + cb.at(0)))
]
#let dots = tiling(size: (7pt, 7pt))[
  #place(rect(width: 100%, height: 100%, fill: cb.at(1).lighten(60%)))
  #place(dx: 2pt, dy: 2pt, circle(radius: 1.5pt, fill: cb.at(1)))
]
#let cross = tiling(size: (7pt, 7pt))[
  #place(rect(width: 100%, height: 100%, fill: cb.at(2).lighten(60%)))
  #place(line(start: (0%, 100%), end: (100%, 0%), stroke: 0.8pt + cb.at(2)))
  #place(line(start: (0%, 0%), end: (100%, 100%), stroke: 0.8pt + cb.at(2)))
]

#plot(
  data: penguins,
  mapping: aes(x: "species", fill: "species"),
  layers: (geom-bar(),),
2  scales: scales(fill: scale-manual(values: (stripes, dots, cross))),
  labels: labels(
    title: "Bars You Can Read in Greyscale",
    x: "Species",
    y: "Count",
    fill: "Species",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 7cm,
)

10 New chart types

A few new stats and positions turn familiar geoms into charts they could not draw before.

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

1#let pat(i, body) = tiling(size: (7pt, 7pt))[
  #place(rect(width: 100%, height: 100%, fill: cb.at(i).lighten(55%)))
  #body
]
#let stripes = pat(0)[#place(line(start: (0%, 100%), end: (100%, 0%), stroke: 1pt + cb.at(0)))]
#let dots = pat(1)[#place(dx: 2pt, dy: 2pt, circle(radius: 1.4pt, fill: cb.at(1)))]
#let cross = pat(2)[
  #place(line(start: (0%, 100%), end: (100%, 0%), stroke: 0.8pt + cb.at(2)))
  #place(line(start: (0%, 0%), end: (100%, 100%), stroke: 0.8pt + cb.at(2)))
]
#let hlines = pat(3)[#place(line(start: (0%, 50%), end: (100%, 50%), stroke: 1pt + cb.at(3)))]

#let series = ()
#for g in ("A", "B", "C", "D") {
  let peak = (A: 8, B: 20, C: 12, D: 4).at(g)
  for x in range(0, 21) {
    series.push((
      x: x,
      y: 2 + 4 * calc.exp(-0.02 * calc.pow(x - peak, 2)),
      grp: g,
    ))
  }
}

#plot(
  data: series,
  mapping: aes(x: "x", y: "y", fill: "grp"),
  layers: (
2    geom-area(position: position-stack(offset: "silhouette"), stroke: 0.5pt),
  ),
  scales: scales(fill: scale-manual(values: (stripes, dots, cross, hlines))),
  labels: labels(title: "A Streamgraph", x: "Time", y: none, fill: "Series"),
  guides: guides(y: none),
  theme: theme-minimal(),
  width: 12cm,
  height: 7cm,
)

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

#let standings = (
  (t: 1, rank: 1, team: "A"), (t: 2, rank: 3, team: "A"),
  (t: 3, rank: 2, team: "A"), (t: 4, rank: 1, team: "A"),
  (t: 1, rank: 2, team: "B"), (t: 2, rank: 1, team: "B"),
  (t: 3, rank: 1, team: "B"), (t: 4, rank: 2, team: "B"),
  (t: 1, rank: 3, team: "C"), (t: 2, rank: 2, team: "C"),
  (t: 3, rank: 4, team: "C"), (t: 4, rank: 3, team: "C"),
  (t: 1, rank: 4, team: "D"), (t: 2, rank: 4, team: "D"),
  (t: 3, rank: 3, team: "D"), (t: 4, rank: 4, team: "D"),
)

#plot(
  data: standings,
  mapping: aes(x: "t", y: "rank", colour: "team", fill: "team"),
  layers: (
1    geom-line(stat: stat-connect(connection: "sigmoid"), linewidth: 1.5pt),
2    geom-point(size: 5pt, stroke: none),
  ),
  scales: scales(
    x: scale-continuous(breaks: (1, 2, 3, 4)),
3    y: scale-reverse(breaks: (1, 2, 3, 4)),
    colour: scale-manual(values: cb),
    fill: scale-manual(values: cb),
  ),
  labels: labels(title: "A Bump Chart", x: "Round", y: "Rank", colour: "Team", fill: "Team"),
  guides: guides(fill: none),
  theme: theme-minimal(),
  width: 12cm,
  height: 7cm,
)

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

#plot(
  data: penguins,
  mapping: aes(fill: "species"),
  layers: (
1    geom-tile(
      stat: stat-waffle(rows: 12),
      width: 0.85,
      height: 0.85,
      stroke: 1pt + rgb("#fafafa"),
    ),
  ),
  scales: scales(
    fill: scale-manual(values: cb)
  ),
  labels: labels(title: "Penguins as a Waffle", x: none, y: none, fill: "Species"),
  guides: guides(x: none, y: none),
  theme: theme-void(),
  width: 12cm,
  height: 7cm,
)

11 Agents and plugins

Gribouille ships an installable agent skill that teaches a coding assistant to write correct plots, checking every argument against the documentation. It installs with:

npx skills add mcanouil/gribouille

The repository doubles as a Claude Code plugin marketplace, so you can wire the same skill into Claude Code:

/plugin marketplace add mcanouil/gribouille
/plugin install gribouille@gribouille

12 Stricter Errors and Rendering Fixes

As always, a good share of the release is fixes rather than features.

The biggest is stricter validation. An unknown aes() aesthetic, such as the US spelling color, now fails with the list of valid aesthetics instead of drawing an empty plot. theme() rejects a misspelled element key, an unknown stat or scale transform fails with a clear message rather than rendering as identity, and mapping an aesthetic to a missing column names the column and lists the ones that exist.

Two rendering fixes are worth calling out. Abutting opaque fills, such as tiles, hexes, and stacked bars, are now stroked with their own fill colour, which removes the hairline seams that antialiasing used to bleed through between them. And stat-quantile drops its cubic pair enumeration for an exact O(n^2 log n) search, so geom-quantile scales to thousands of rows.

Facets and compositions also gain spacing control. facet-wrap and facet-grid take a gutter argument, and a new theme(panel-spacing:) default sets the gap for both axes at once (a length, or a (x:, y:) dictionary); compose’s gutter now accepts the same dictionary form.

13 Wrap-up

Next on the list is more geoms and more 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.

1 The documentation: great-docs

great-docs is Posit’s API documentation tool for Python packages. You point it at a module, give it a small YAML config, and it generates a Quarto-based site from your docstrings. The result is close to what pkgdown gives you for R: a landing page, an API reference, and whatever extra pages you add.

The config for this project is short, see the full great-docs.yml in the repository.

great-docs.yml

1parser: numpy

authors:
  - name: Mickaël Canouil
2    role: Author

reference:
  - title: Functions
    desc: Utility functions
3    contents:
      - body_mass_distribution
      - load_penguins
      - mass_flipper_corr
      - mass_vs_flipper
      - species_counts
      - summarise_by_species

1

Docstring format — numpy means NumPy-style sections (Parameters, Returns, Examples). Other options are google and sphinx.

2

Author metadata appears in the generated site sidebar under Developers.

3

Controls which names appear on the Reference page and in what order. The names not listed here are hidden from the public API.

Building the site copies the output into a docs/ folder the app will serve.

scripts/build-docs.sh

1uv run great-docs build
2rm -rf docs
3cp -R great-docs/_site docs

1

Runs great-docs build inside the project’s uv virtual environment.

2

Removes any stale output before copying fresh files.

3

great-docs writes to great-docs/_site by default; this renames it to docs.

2 The app: Shiny for Python

The penguin_analysis module loads the dataset with polars, computes summaries, and draws plotnine plots. The Shiny app wraps those functions in an interactive UI.

app.py

app_ui = ui.page_navbar(
    ui.nav_panel(
        "Explore",
        ui.layout_sidebar(
            ui.sidebar(
                ui.input_selectize("species", "Species",
                                   choices=_SPECIES,
                                   selected=_SPECIES,
1                                   multiple=True),
            ),
            ui.output_text("correlation"),
            ui.output_data_frame("table"),
        ),
    ),
    ui.nav_panel("Plots",
        ui.output_plot("scatter"),
        ui.output_plot("distribution"),
    ),
    ui.nav_panel("Summary", ui.output_data_frame("summary")),
2    ui.nav_spacer(),
3    ui.nav_control(ui.a("Documentation", href="/docs/", target="_blank")),
    title="Palmer Penguins",
)

1

multiple=True lets the user select several species at once; all three are pre-selected so the app is useful immediately on load.

2

Pushes items that follow it to the right end of the navbar.

3

Injects a plain HTML link into the navbar. Here, href="/docs/" works because both routes share the same origin, so no absolute URL is needed.

The navbar links to /docs/ so the user can jump from the app to the reference without leaving the same origin.

3 Serving both from one process

Shiny for Python serves static files through its own handler, which matches file paths literally. That means a URL like /docs/reference/ returns a 404 because there is no file called reference at that path. What great-docs emits are clean directory links, and those 404 under Shiny’s handler.

The fix is to wrap the Shiny app in a Starlette application and mount the docs/ folder with StaticFiles(html=True).

app.py

from starlette.applications import Starlette
from starlette.routing import Mount
from starlette.staticfiles import StaticFiles

1_DOCS_DIR = Path(__file__).parent / "docs"

app = Starlette(
    routes=[
2        Mount("/docs", app=StaticFiles(directory=_DOCS_DIR, html=True), name="docs"),
3        Mount("/", app=shiny_app, name="shiny"),
    ]
)

1

Resolves the docs/ path relative to app.py, not the working directory, so the app starts correctly regardless of where shiny run is called from.

2

html=True resolves /docs/reference/ to docs/reference/index.html instead of returning a 404.

3

The Shiny app is mounted last. Starlette tries routes in order, so the more-specific /docs prefix always wins before the catch-all /.

Because Starlette and Shiny both speak ASGI, shiny run app.py still works after wrapping.

4 Quick start

uv sync --extra app --extra dev
bash scripts/build-docs.sh
uv run shiny run app.py --port 8000

Then http://localhost:8000 is the app and http://localhost:8000/docs/ is the documentation.

Happy coding!

1 When does this pattern fit?

The pattern earns its complexity when several things are true at once. You have a domain object that several verbs operate on, such as load, summarise, and export. You want the same logic available interactively, in a batch pipeline, and in a report. You need branded, consistent output across formats: HTML, PDF, slides.

If you only need a handful of functions, this is too much structure. The cost is worth paying once the object model and the reporting start to repeat.

2 The four pillars

The package rests on four parts that compose cleanly.

Each pillar is a distinct tool with a different job. S7 defines the typed data structures the rest of the package operates on. targets is a build system: it caches intermediate results and only re-runs steps whose inputs have changed. Shiny turns R functions into an interactive web app, with no JavaScript needed. Quarto renders documents from a single source file: HTML pages, PDFs, slide decks, all from the same prose and code.

The S7 objects are the currency that flows between the four parts. The pipeline, the report, and the Shiny app all pass them around and call the same generics.

3 An S7 object model

R is a functional language, but it lets you define your own types. A class is a named structure with rules: it says what fields a value must have, what types those fields must be, and what makes a value valid. Once you have a class, you can write functions whose behaviour changes depending on what type of object you pass them. That is the whole idea.

S7 is the R Consortium’s current answer to “how should R do this”. It replaces the older S3 and S4 systems with a cleaner API: you declare properties (the fields), a validator (the rules), and a constructor (how to build one). You call @ to read a field, just like $ for a list.

The package has three classes. Dataset wraps a data.frame and records when it was created. AnalysisResult holds the summary table and method name produced by one analysis run. Project owns a dataset and an ordered list of results.

R/aab-classes.R

Dataset <- S7::new_class(
  name = "Dataset",
1  properties = list(
2    data = S7::class_any,
3    name = S7::new_property(class = S7::class_character, default = ""),
    created = S7::new_property(class = S7::class_any, default = NULL)
  ),
4  validator = function(self) {
    if (!is.null(self@data) && !is.data.frame(self@data)) {
      return("@data must be a data.frame or NULL")
    }
    if (length(self@name) != 1L) {
      return("@name must be a single string")
    }
    NULL
  },
5  constructor = function(data = NULL, name = "") {
    S7::new_object(
      S7::S7_object(),
      data = data,
      name = name,
      created = Sys.time()
    )
  }
)

1

Properties are typed slots; every instance must carry a value for each.

2

class_any accepts any R object with no type check.

3

new_property() adds a class constraint and a default value; omitting name gives "".

4

All invariants go in validator; returning a string fails construction with that message.

5

The constructor stamps created automatically; callers only supply data and name.

Verbs are S7 generics. A generic is a function that looks at the type of its first argument and calls the right implementation. You define the generic once, then attach a separate implementation for each class. Generics go in aaa-generics.R, before the class files, so the implementations can attach to them when R loads the package.

R/aaa-generics.R

analyse <- S7::new_generic(
  "analyse",
1  "object",
  function(object, method = "describe", ...) {
2    S7::S7_dispatch()
  }
)

1

The dispatch argument: S7 picks the method based on the class of object.

2

Must call S7_dispatch() in the body; this triggers method lookup and execution.

The Project method delegates to the Dataset method, stores the result, and updates the timestamp.

R/analyse.R

1S7::method(analyse, Project) <- function(object, method = "describe", ...) {
2  result <- analyse(object@data, method = method, ...)
  object@results <- c(object@results, list(result))
3  object@modified <- Sys.time()
  object
}

1

Attaches a method to the analyse generic specifically for Project objects.

2

Delegates to the Dataset method by passing object@data; no logic is duplicated.

3

S7 slot assignment uses @<-, the same accessor as reading (@).

One more thing worth keeping: the filter() generic uses a search-path fallback so the package’s own filter() method works on Dataset objects while dplyr’s filter() still works on data frames. The default method walks the search path and delegates to the next plain function of the same name.

4 A config-driven pipeline

Most people who run an analysis are not R developers. They know what data they have and what question they want to answer, but they should not need to open a .R file to say so.

A YAML config makes this possible. It reads like plain English: here is the data file, here are the analyses to run, here is what the report should be called. No R syntax, no package knowledge, no risk of accidentally breaking the pipeline logic. The package owns the code; the config owns the decisions.

R developers who want more control are not forced through the config. They can call Dataset(), analyse(), and the rest of the verbs directly, compose them however they like, and build their own pipeline. The config-driven workflow is a convenience layer on top, not a gate.

generate_pipeline() validates the config, fills a whisker/Mustache template, and writes a _targets.R file. run_pipeline() calls targets’ tar_make() to execute it. report_pipeline() renders the Quarto report from the store.

pipeline-config.yml

data:
  file: demo.csv
  name: demo
analyses:
  summary:
    method: describe
  pairs:
    method: correlate
report:
  title: "Acme Analysis Report"
  formats:
    - acme-html

The template is the interesting part. Each analysis in the config becomes one targets target. The whisker {#analyses} ... {{/analyses}} section expands once per entry.

inst/templates/_targets.R

list(
  tar_target(input_file, "{{{data_file}}}", format = "file"),
  tar_target(
    dataset,
    acme.toolkit::Dataset(data = utils::read.csv(input_file), name = "{{{data_name}}}")
  ){{#analyses}},
  tar_target(
    {{name}},
    acme.toolkit::analyse(dataset, method = "{{method}}")
  ){{/analyses}}
)

The leading comma belongs at the start of each repeated block, after the always-present dataset target. This avoids a trailing comma in the generated list, which would be a parse error.

5 A bundled Quarto extension

Branding lives in exactly one place: a Quarto extension under inst/_extensions/acme/. One _extension.yml defines three formats.

inst/_extensions/acme/_extension.yml

title: Acme
version: 0.1.0
quarto-required: ">=1.5.0"
contributes:
  metadata:
    project:
      brand: _brand.yml
  formats:
    common:
      filters:
        - filters/prose-divs.lua
        - filters/copyright-year.lua
      toc: true
      number-sections: true
    html:
      theme: [cosmo, brand, acme.scss]
      embed-resources: true
      title-block-banner: true
    typst:
      papersize: a4
      margin: {top: 2.5cm, bottom: 2.5cm, left: 2cm, right: 2cm}
    revealjs:
      theme: [default, brand, revealjs/theme.scss]
      embed-resources: true

A document opts in with one line.

format: acme-html

Colours, fonts, and logos live in _brand.yml. Quarto’s native brand support feeds them into every format, so the SCSS files only add layout rules.

The extension ships inside the package at inst/_extensions/acme/. When the pipeline is generated, .install_acme_extension() copies it into the project directory. Quarto resolves _extensions/ from the document’s directory, so the copy must be local. Re-skinning the whole system means editing three files: _brand.yml, acme.scss, and revealjs/theme.scss.

6 A modular Shiny app

The Shiny app reuses the package’s analysis code. It does not re-implement it. The modules call analyse(), the same generic the batch pipeline calls.

Shiny modules exist to solve a scoping problem. In a plain Shiny app, every input and output shares a single namespace, so names clash as the app grows. A module wraps a piece of UI and its server logic into an isolated unit with its own namespace. You can drop it into any app by calling two functions: one for the UI, one for the server.

That last point matters here. The three modules are not just internal implementation details of this package’s bundled app. They are the public interface for other Shiny apps. If you already have a Shiny app and you want to add an acme.toolkit analysis panel to it, you call mod_analysis_ui() and mod_analysis_server() and you are done. No copy-pasting, no re-implementing the analysis logic.

mod_input loads a CSV and writes a Dataset into shared state. mod_analysis reads the dataset, runs analyse(), and writes the result. mod_report reads the result and offers a Quarto report as a download.

The top-level server owns the shared state and passes it into each module.

R/app_server.R

app_server <- function(input, output, session) {
1  dataset <- shiny::reactiveVal(NULL)
  result <- shiny::reactiveVal(NULL)

  mod_input_server("input", dataset = dataset)
  mod_analysis_server("analysis", dataset = dataset, result = result)
  mod_report_server("report", result = result)

  invisible(NULL)
}

1

Shared state lives here. Modules never reach into each other.

The data flows in a straight line.

Inside mod_analysis, the call is:

R/mod_analysis.R

shiny::observeEvent(input[["run"]], {
  ds <- dataset()
  if (is.null(ds)) {
    shiny::showNotification("Load a dataset first.", type = "warning")
    return()
  }
1  result(analyse(ds, method = input[["method"]]))
})