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.