Skip to content

Configuration reference

This is the 0.2.0 reference for the shared styling interface; custom documents use custom(config:). It documents the executable baseline in defaults.typ; it does not claim that every template consumes every key. report, article, book, journal, cover-page, letter, invoice, and proposal templates add or override settings in their own APIs. Their documented differences take precedence over the shared baseline. The declared minimum compiler version is Typst 0.15.0.

Pass only values to change. Satz deep-merges dictionaries: an override such as (colors: (brand-primary: blue)) preserves the other color defaults. Arrays, scalars, and non-dictionary values replace the old value. The generic merge helper does not validate unknown keys. Validation is performed by individual public APIs where supported; in particular, letters, invoices, and covers reject unsupported keys in their documented appearance groups.

Find a setting

Select a field to jump to its type, default, and effect. Template-specific overrides are listed below.

page: page.paper, page.margin, page.binding, page.binding-correction, page.headers, page.columns, page.column-gutter

typography: typography.font, typography.math-font, typography.mono-font, typography.size, typography.line-spacing, typography.leading, typography.list-spacing, typography.paragraph-spacing, typography.first-line-indent, typography.hyphenate, typography.justify

headings: headings.numbering, headings.hyphenate, headings.h1-pagebreak, headings.spacing

heading sizes and gaps: headings.h1-size, headings.h2-size, headings.h3-size, headings.h4-size, headings.h1-above, headings.h2-above, headings.h3-above, headings.h4-above, headings.h1-below, headings.h2-below, headings.h3-below, headings.h4-below

journal: journal.header-below, journal.running-gutter, journal.running-leading, journal.running-header-size, journal.date-size, journal.keywords-size

decorative: decorative.header-size, decorative.footer-size, decorative.date-size, decorative.keywords-size

page-footer: page-footer.format, page-footer.size, page-footer.weight

links: links.color, links.url-color

tables: tables.stroke, tables.inset, tables.font-size, tables.caption-position, tables.caption-gap

figures: figures.placement

callouts: callouts.inset, callouts.radius, callouts.stroke, callouts.title-below, callouts.paragraph-spacing, callouts.list-spacing

captions: captions.size, captions.weight, captions.alignment, captions.label-weight, captions.hanging

toc: toc.depth, toc.title, toc.indent, toc.entry-size, toc.leading, toc.entry-above, toc.main-entry-above, toc.title-below, toc.below

lof: lof.depth, lof.title, lof.indent, lof.entry-size, lof.leading, lof.entry-above, lof.title-below, lof.below, lof.compact

lot: lot.depth, lot.title, lot.indent, lot.entry-size, lot.leading, lot.entry-above, lot.title-below, lot.below, lot.compact

bibliography: bibliography.style

colors: colors.bg-paper, colors.bg-subtle, colors.brand-primary, colors.brand-accent, colors.text-main, colors.text-muted

template-specific: page.header-ascent, decorative.list-indent, decorative.list-body-indent, decorative.list-spacing, decorative.list-block-spacing, headings.h1-number-size, article settings, book settings

Shared defaults

Values below come from defaults.typ. Lengths use Typst units. Colors are Typst color values. auto delegates a choice or policy to the template; none disables a feature or selects the template’s fallback where stated.

Key Type and accepted values Shared default Meaning and scope
page.paper Typst paper name or custom page size "a4" Paper size. See Typst page.
page.margin dictionary of edge names to lengths (top: 2.5cm, bottom: 2.5cm, left: 2.5cm, right: 2.5cm) Page margins. Two-sided templates may derive inside/outside margins.
page.binding none or a horizontal alignment (left / right) none Enables two-sided inside/outside layout where supported.
page.binding-correction length 0pt Extra binding-side space when two-sided layout is enabled.
page.headers boolean false Enables a running header in templates that implement it.
page.columns positive integer 1 Number of page columns where the template supports columns.
page.column-gutter length 5mm Gap between columns.
page.header-ascent length 24.442pt in DFG Extra ascent reserved for the DFG running header. Only used by dfg-proposal.
typography.font font family name "Libertinus Serif" Main text family. Font must be installed or embedded by the runtime.
typography.math-font font family name or auto auto Math typeface; auto retains Typst’s native selection.
typography.mono-font font family name or auto auto Monospaced typeface; auto retains Typst’s native raw-text style.
typography.size length 11pt Main text size.
typography.line-spacing positive number or none none Optional baseline-to-baseline distance as a multiple of the body font size (for example 1.5). Uses the selected font metrics and overrides typography.leading.
typography.leading length 0.65em Distance between line bounds, not a multiplier.
typography.list-spacing non-negative number 0.5 Additional list-item gap as a fraction of the calculated body baseline distance. Follows typography.line-spacing, or font metrics and typography.leading; 0 adds no extra gap.
typography.paragraph-spacing length 1.2em Vertical gap between paragraphs. It is independent of line spacing. If paragraphs are identified by indentation, reduce this gap separately; Satz does not change it when indentation is enabled.
typography.first-line-indent boolean false true indents the first line of every paragraph by one em (the current body font size, e.g. 11pt at 11pt text size), including the first paragraph in a document/container and paragraphs after headings; false uses no indent. The horizontal indent is independent of vertical line and paragraph spacing.
typography.hyphenate boolean false Enables automatic word hyphenation.
typography.justify boolean true Justifies body paragraphs when supported.
headings.numbering Typst numbering pattern/function or none "1.1" Heading numbering passed to the native heading system.
headings.hyphenate boolean false Hyphenation within headings.
headings.h1-pagebreak boolean false Starts level-one headings on a new page where supported.
headings.spacing "koma" or "native" "koma" Uses translated KOMA baseline skips or leaves native Typst spacing.
headings.h1-number-size length 25pt in book Size of the level-one chapter number in the experimental book template.
headings.h1-size … headings.h4-size length 14pt, 12pt, 11pt, 11pt Size for heading levels one through four. Templates may override these.
headings.h1-above … headings.h4-above auto or length auto Space before each level. auto follows headings.spacing; an explicit length overrides the policy.
headings.h1-below … headings.h4-below auto or length auto Space after each level. auto follows native/template policy.
journal.header-below length 1.5em Gap between the complete entry header/date and notes. Journal only.
journal.running-gutter length 1em Gap between running-header columns. Journal only.
journal.running-leading length 0.35em Line gap in a multi-line running header. Journal only.
journal.running-header-size length 9pt Running-header text size. Journal only.
journal.date-size length 10pt Journal date text size. Journal only.
journal.keywords-size length 9pt Journal keyword text size. Journal only.
decorative.header-size length 9pt Running-header text size.
decorative.footer-size length 10pt Footer text size where implemented.
decorative.date-size length 10pt Date text size where implemented.
decorative.keywords-size length 9pt Keyword text size where implemented.
decorative.list-indent length 17.9669pt in DFG Indentation of list and enumeration markers in the DFG template.
decorative.list-body-indent length 5.475 × 72 ÷ 72.27 pt in DFG Gap from each list or enumeration marker to its body text.
decorative.list-spacing length baseline + paragraph-skip - cap in DFG Vertical distance between lines in DFG lists and enumerations.
decorative.list-block-spacing length baseline + paragraph-skip - cap + 3 × 72 ÷ 72.27 pt in DFG Space above and below list and enumeration blocks; uses the DFG font metrics.
page-footer.format Typst numbering pattern/function "1" Page-number format where the template uses the shared footer.
page-footer.size length 10pt Page-number size.
page-footer.weight Typst font-weight value "regular" Page-number weight.
links.color, links.url-color color #0563C1, #0563C1 Internal-reference and external-URL colors in the default neutral palette.
tables.stroke length 0.5pt Default table rule thickness for shared table helpers.
tables.inset length or dictionary such as (x: 8pt, y: 4pt) (x: 8pt, y: 4pt) Cell padding for shared table helpers.
tables.font-size length 10pt Text size in shared styled tables.
tables.caption-position top or bottom top Caption position for the scientific-table show rule.
tables.caption-gap length 6pt Space between a table caption and its table.
figures.placement auto, none, or a vertical alignment none (auto in report) Native placement policy for figures, including tables represented as figures. none keeps them in source order; auto lets Typst place them at a suitable page edge.
callouts.inset length 9pt Inner padding for callout.
callouts.radius length 3pt Corner radius for callout.
callouts.stroke length 0.8pt Border thickness for callout.
callouts.title-below length 1em Gap between callout title and body.
callouts.paragraph-spacing length 1em Paragraph gap inside a callout.
callouts.list-spacing length 1.2em List-item gap inside a callout.
captions.size length 10pt Caption text size.
captions.weight Typst font-weight value "regular" Caption text weight.
captions.alignment Typst alignment left Caption alignment when hanging is false.
captions.label-weight Typst font-weight value "regular" Weight of the caption label, independently of caption text.
captions.hanging boolean true Put the label in its own column so wrapped lines align with the caption text. Set to false for an inline label.
toc.depth none or non-negative integer none 0 disables automatic contents in report/thesis templates. Reports override the shared default to 0; set none to enable all levels. book-contents(depth: 0) instead renders an empty titled list; other depths depend on the template.
toc.title content or none [Table of Contents] Contents title; none omits it.
toc.indent auto or length auto Entry indentation policy.
toc.entry-size length 10pt Contents entry size.
toc.leading length 0.65em Line gap in wrapped entries.
toc.entry-above length 0.65em Gap between ordinary entries.
toc.main-entry-above length 1.25em Extra gap before main-section entries.
toc.title-below length 1.5em Gap below the contents title.
toc.below length 2em Gap after the contents.
lof.depth, lot.depth none or non-negative integer none 0 disables the corresponding list; none uses automatic depth.
lof.title, lot.title content or none [List of Figures], [List of Tables] Heading above the list; none omits the title.
lof.indent, lot.indent auto or length auto Indentation for nested entries.
lof.entry-size, lot.entry-size length 10pt Text size for list entries.
lof.leading, lot.leading length 0.65em Gap between lines in wrapped entries.
lof.entry-above, lot.entry-above length 0.85em Gap before each entry.
lof.title-below, lot.title-below length 1.5em Gap between the list title and first entry.
lof.below, lot.below length 2em Gap after the list.
lof.compact, lot.compact boolean false When true, omit caption text and show only label and page.
bibliography.style CSL style name "apa" Citation style where bibliography support is enabled.
colors.bg-paper, bg-subtle, brand-primary, brand-accent, text-main, text-muted Typst color white, white, black, black, black, black Neutral black-on-white defaults. Use theme: "slate" for the former blue-gray palette.

Article-specific settings

article accepts these additional keys when using article. They control the full-width title block and abstract; headings, page columns and typography still use the shared settings above. See the article API for the function inputs such as authors, affiliations, and date.

Field Type Default Effect
article.title-size length 18pt Size of the title in the full-width front matter.
article.author-size length 11pt Size of author names.
article.affiliation-size length 8.5pt Size of affiliation lines.
article.abstract-size length 9pt Size of abstract text.
article.title-gap length 1em Vertical gap after the title and before the abstract.
article.body-gap length 1.5em Gap between front matter and article body.

Book-specific settings

The experimental book template accepts common shared settings through config and adds the book group below. These keys are used by the book components; defaults are for the candidate implementation.

Field Type Default Effect
book.ink Typst color #24313B Color for the book cover title and chapter headings.
book.running-headers "bottom", "top", or "none" "bottom" Placement of alternating chapter titles. This nested key overrides the direct running-headers: argument.
book.contents.title-before length 24.5pt Space before the contents title.
book.contents.title-after length 26pt Gap after the contents title.
book.contents.title-size length 17pt Contents title size.
book.contents.entry-size length 10pt Text size for contents entries.
book.contents.entry-spacing length 11.8pt Vertical space between contents entries.
book.worked-example.above length 26pt Space before a worked example.
book.worked-example.below length 27pt Space after a worked example.
book.worked-example.inset length 27pt Inner padding for a worked example.
book.worked-example.label-gap length 0pt Gap between the worked-example label and its body.
book.worked-example.label-size length 9pt Worked-example label size.
book.worked-example.body-size length 9pt Worked-example body size.
book.exercise.grid-gap length 11pt Space between an exercise prompt and its answer grid.
book.exercise.group-gap length 20pt Space between exercise groups.
book.footer-dy length 5pt Vertical offset for the page number.
book.cover-top length 28mm Top spacing for the book cover layout.
book.cover-eyebrow-size length 14.3pt Cover eyebrow text size.
book.cover-eyebrow-below length 14mm Space below the eyebrow.
book.cover-title-size length 25pt Cover title size.
book.cover-title-leading length 8pt Gap between cover-title lines.
book.cover-title-below length 13.5mm Space below the cover title.
book.cover-subtitle-size length 14.3pt Cover subtitle size.
book.cover-subtitle-leading length 6.5pt Gap between subtitle lines.
book.cover-subtitle-below length 21.6mm Space below the subtitle.
book.cover-rule-width length 0.8pt Cover divider rule thickness.
book.cover-author-size length 12pt Cover author size.
book.cover-author-below length 3pt Space below the author.
book.cover-note-size length 10pt Cover note size.
book.cover-note-below length 11.2mm Space below the cover note.
book.cover-date-dy length 6.5pt Vertical offset for the cover date.

The complete group is defined by the book template. The book API entry documents its direct arguments and how to compose the book components.

Template-specific appearance defaults

These values override the shared baseline when the named template is used. They are appearance defaults only; the wrappers also expose content-specific arguments described in their source API comments and guides.

Template Defaults or notable differences
custom Defaults to the neutral palette and no automatic contents, figure list, or table list (toc.depth, lof.depth, lot.depth: 0); set a depth to none to enable it. Other values follow the shared defaults. kind defaults to "report"; other kinds can change front matter, numbering, headers, and bibliography behavior. theme accepts the built-in palettes.
report Defaults to theme: "neutral", figures.placement: auto, and toc.depth, lof.depth, lot.depth: 0 (no automatic lists); set a depth to none to enable that list. Other appearance defaults come from the shared document class. theme: none skips a named palette.
article Defaults to theme: "neutral"; page.columns: 2; typography.size: 10pt, hyphenate: true; heading numbering none, sizes 12pt, 10.5pt, 10pt, 10pt; toc.depth, lof.depth, lot.depth: 0; white paper. Article layout fields: title 18pt, author 11pt, affiliation 8.5pt, abstract 9pt, title gap 1.2em, body gap 2.2em.
journal-entry / journal-index Default to theme: "neutral"; page.paper: "iso-b5"; margins (left: 2cm, right: 2cm, top: 2.5cm, bottom: 2.5cm); body Libertinus Serif 11pt, 0.65em leading, no hyphenation, justified; h1 16pt, h2 12pt, h3/h4 11pt; date 10pt, running header 9pt, footer 10pt; list gap 0.65em; black-on-white palette. Journal block, metadata, list, and running-header settings use journal.* above.
letter DIN A4, margins (left: 25mm, right: 20mm, top: 25mm, bottom: 25mm), Inter 11pt, 0.65em leading, justified, no hyphenation, black text/accent, white paper. Canonical direct options include font, paper, margins, font-size, line-spacing, and justify. Nested config only accepts the documented page, typography, color, and link keys.
invoice / rechnung Same DIN page geometry and Inter 11pt, 0.65em leading; output remains German. Canonical direct names are sender, recipient, date, items, qr, qr-amount, and qr-purpose; German names are aliases. Nested config accepts the same limited appearance keys as letters.
book (experimental) Defaults to theme: "neutral"; A4; margins (left: 27mm, right: 25mm, top: 25mm, bottom: 27mm); left binding with 5mm correction; Libertinus Serif 11pt; New Computer Modern Math; 0.74em leading; 14pt paragraph gap; no page headers; black accent and ink. theme: "slate" selects the former blue-gray palette.
cover-page A4, 2.5cm margins, Libertinus Serif 11pt, black-on-white neutral cover palette. theme defaults to "neutral" and layout to "research". Pass title for a generated cover, or body for your own design. layout: "research" aligns the title block left behind a 4.5cm vertical accent rule; layout: "minimal" centers a spare title block. Covers consume only the documented page, font, and color keys; other valid shared keys are accepted and ignored. They do not inherit a following document’s theme or config.
research-proposal / project-proposal No contents/lists; margins (x: 25mm, y: 25mm); white paper, black text and links; paragraph gap 0.7em; heading numbering "1.1".
dfg-proposal DFG form 53.01 (09/26), A4, margins (left: 25mm, right: 20mm, top: 25mm, bottom: 15mm); Arial 11pt, form-specific leading, four-level numbering "1.1.1.1"; no contents/lists; black text/links; left captions.
nwo-proposal Only source-checked 2026 profiles; A4 with 25mm margins; Arial, 9.5pt pre-proposal or 10pt Vici full form; no contents/lists; black text/links. Form profile controls remaining typography and page budget.

These wrappers intentionally do not share identical layouts. Their appearance inputs follow the documented per-template contract; omitted values use the template-specific defaults in this table.