Document setup

str | dictionary
Slide aspect ratio.

• "16-9": widescreen, the default.
• "4-3": traditional projector.
• a (width:, height:) dictionary of lengths, for a custom size Typst’s named papers do not cover.

content | str | array
Canonical deck authorship. Title layouts inherit it when their own authors is auto. A name on its own is enough, so this reads like title and subtitle in the common case:

authors: [Ada Lovelace]
authors: ([Ada Lovelace], [Charles Babbage])

Wrap a name in layouts.author when it carries affiliations, an ORCID iD, or a contact address. Names and records mix in one array:

authors: (
  mosaic.layouts.author(
    [Ada Lovelace],
    affiliations: ([Analytical Society],),
    email: "ada@example.org",
    corresponding: true,
  ),
  [Charles Babbage],
)

dictionary
Partial semantic color overrides layered over the active theme. Omitted roles keep the theme’s value.

• canvas: the slide page behind everything else.
• surface: raised panels, such as component frames and callouts.
• text: ordinary body text.
• muted: subtitles, captions, and other fine print.
• line: rules, borders, and other drawn separators.
• accent: the deck’s one emphatic color.
• warning: the status color a component’s role: "warning" paints with.
• error: the status color a component’s role: "error" paints with.

colors: (accent: rgb("#0072B2"))

dictionary
Partial fallback content keyed by cell ID, used whenever a slide leaves that cell empty. Every key names a grid cell, for example footer or body; the full-slide planes have their own options below.

A slide’s explicit content overrides these values, and none on the slide suppresses a configured default. Defaults targeting cells absent from a resolved grid are ignored, so one footer default is safe across layouts that have no footer.

cells: (footer: align(right, mosaic.components.progress()))

content | str | none
The deck’s background plane, drawn behind the grid on every slide. A slide inherits it unless it passes its own background:, or none to suppress it. The plane takes no space away from the grid.

background: mosaic.components.image(path("paper.webp"))

content | str | none
The deck’s foreground plane, drawn over the grid on every slide. Ordinary home for a logo, a slide number, or a progress indicator.

foreground: place(bottom + right, mosaic.components.progress())

dictionary
Partial overrides for the grid geometry the layouts measure with. Omitted keys keep the theme’s value.

• inset: padding inside a cell, default 1.25em.
• gap: space between grid regions, default 0.7em.
• compact-gap: the tighter space inside stacked metadata, default 0.35em.

Typographic rhythm is not here. Heading spacing and list spacing are ordinary show and set rules owned by the theme, so change them with native rules after setup or in your own theme’s apply.

dictionary
Partial geometry overrides for the printed speaker, notes, and split outputs. Omitted keys keep the theme’s value. These pages are paper, not slide canvas, so this is layout geometry only; their heading and note typography are ordinary show rules, changeable after setup.

• margin: the A4 page margin, default 15mm.
• split-inset: the same inset for the split output’s notes half, whose page carries no margin of its own so the two halves meet exactly at the midpoint, default 12mm.
• thumbnail-stroke: the border drawn around the slide thumbnail, default 0.6pt in the theme’s line color.
• note-gap: space between successive notes, default 3mm.
• thumbnail-gap: space below the slide thumbnail, default 7mm.
• heading-gap: space below the notes heading, default 4mm.
• bottom-gap: slack held back below the notes block so a full page does not butt against the bottom margin, default 2mm.

notes: (margin: 20mm)

str
What to do when a cell’s content is taller than the cell.

Observation measures every cell on every frame, which roughly doubles the layout work a deck does, so it is off by default and switched on for a deliberate checking pass rather than left on while you write.

• "off": observe nothing. The default.
• "record": emit queryable <mosaic-overflow-warning> metadata and keep compiling. Typst gives a package no warning channel, so nothing is printed; this mode is for tooling that reads the records itself.
• "error": emit the same metadata and fail the compile, naming every offending cell. Run this before presenting, so a build stops rather than shipping a clipped slide.

dictionary
Partial named-layout overrides. Omitted names keep the active theme’s layout.

• content: the ordinary slide layout, also used by automatic level-two-heading slides.
• title: used by slide(layout: "title").
• section: used by slide(layout: "section") and by automatic level-one heading slides.

Each value is either a deferred mosaic.layouts.* value or a low-level mosaic.grids.* tree. Note that this option is distinct from the cells: option above, which supplies inherited cell content rather than structure.

layouts: (
  content: mosaic.layouts.content(variant: "header-body", columns: 2),
)

str
Which document to render.

• "slides": the presentation itself.
• "speaker": each frame above the notes that apply to it.
• "notes": the notes alone, without the slide image.
• "split": each frame beside its notes on a double-width page, the layout pympress and pdfpc cut in half to drive two screens.

array
Counters restored to their pre-slide values before each continuation frame, so content repeated across the frames of one logical slide advances them once rather than once per frame.

frozen-counters: (counter(figure.where(kind: image)),)