Typst Support - Theme

Themes are the final layer of Typst support. They combine the rendering target, book metadata, and content helpers into the page chrome and reusable paged styles.

Start with Built-in Themes to configure Starlight or mdBook. See Custom Theme when implementing the theme contract directly.

#import "@preview/shiroa:0.4.0": html-support
#import html-support: (
  add-scripts,
  add-styles,
  inline-assets,
  set-slot,
  virt-slot,
)

#import "@preview/shiroa:0.4.0": html-support
#import html-support: (
  add-scripts,
  add-styles,
  inline-assets,
  set-slot,
  virt-slot,
)

These helpers are intended for custom themes:

• data-url(mime, src)data-url(mime, src) encodes bytes or text as a Base64 data URL.
• virt-slot(name)virt-slot(name) inserts a named placeholder.
• set-slot(name, body)set-slot(name, body) returns a show rule that replaces matching placeholders.
• add-assets(asset, cond: true)add-assets(asset, cond: true) records a CSS or JavaScript raw block in the global theme asset state.
• add-stylesadd-styles and add-scriptsadd-scripts are aliases of add-assetsadd-assets for intent.
• inline-assets(body)inline-assets(body) converts raw(lang: "css")raw(lang: "css") and raw(lang: "js")raw(lang: "js") blocks into inline HTML assets on an HTML target.
• shiroa-assetsshiroa-assets is the state containing assets registered by add-assetsadd-assets.

Slots and the asset state are low-level theme contracts. A theme that collects assets must emit shiroa-assets.final().values()shiroa-assets.final().values() through inline-assetsinline-assets in its HTML head.

#import "@preview/shiroa:0.4.0": templates
#import templates: (
  code-block-rules,
  equation-rules,
  markup-rules,
  theme-box,
  theme-box-styles-from,
)

#import "@preview/shiroa:0.4.0": templates
#import templates: (
  code-block-rules,
  equation-rules,
  markup-rules,
  theme-box,
  theme-box-styles-from,
)

The module contains the reusable styling layer used by the initialized page template:

• main-sizemain-size, heading-sizesheading-sizes, and list-indentlist-indent provide target-aware default dimensions.
• markup-rulesmarkup-rules applies spacing, lists, headings, links, and heading anchors.
• equation-rulesequation-rules adapts block and inline equations for native HTML.
• code-block-rulescode-block-rules configures zebrawzebraw code rendering for paged and HTML targets.
• book-theme-frombook-theme-from resolves one color preset for a target.
• theme-box-styles-fromtheme-box-styles-from resolves the default, light, and dark theme records.
• theme-boxtheme-box renders target-appropriate light and dark variants.
• make-unique-labelmake-unique-label, heading-referenceheading-reference, heading-hashheading-hash, and static-heading-linkstatic-heading-link implement stable heading destinations within one compilation.
• paged-load-trampolinepaged-load-trampoline creates the JavaScript loader used by a dyn-paged html-wrapperhtml-wrapper page.

Most styling helpers expect the theme dictionaries produced by theme-box-styles-fromtheme-box-styles-from. The generated templates/page.typtemplates/page.typ is the canonical complete example; custom themes can use only the pieces they need.