Typst

Typst

This skill targets Typst 0.15+ by default. For Typst 0.14.2, use the typst-0.14.2 repository tag for the previous skill snapshot, typst query for CLI introspection, or --channel 0.14.2 with API search.

Compilation

typst compile document.typ              # compile once → PDF
typst compile document.typ output.pdf   # explicit output path
typst compile document.typ -f png       # export as PNG image
typst compile src/main.typ --root .     # set project root for /path imports
typst watch document.typ                # recompile on change
typst eval --in document.typ 'query(heading).len()'  # Typst 0.15+ introspection

For command options beyond this quick reference, see cli.md.

Agent verification — choose by what you need to check (see debug.md for details):

Minimal Document

#set page(paper: "a4", margin: 2cm)
#set text(size: 11pt)

= Title

Content goes here.

Writing Documents

Starting a new document? Copy the closest recipe from Examples below — it's faster than starting blank and each row names the docs to read next.

Developing Packages and Templates

basics.md and types.md are also the foundation for developers.

Finding Packages

Search the embedded index of Typst Universe packages (updated weekly):

python3 scripts/search-packages.py "what you need"
python3 scripts/search-packages.py "chart" --category visualization
python3 scripts/search-packages.py --category cv --top 5
python3 scripts/search-packages.py --list-categories

Common Errors

Examples

Copy the closest starter, adjust, compile. For CVs, letters, or slides, search packages: python3 scripts/search-packages.py --category cv (or letter, presentation).

Dependencies

• typst CLI 0.15+ recommended: Install from https://typst.app or via package manager
• macOS: brew install typst
• Linux: cargo install typst-cli
• Windows: winget install typst
• pdftotext (optional): For text-level output verification
• Python 3.10+ (optional): For package search and validation scripts
• jq (optional): For parsing JSON output from typst eval or typst query in shell scripts

API Reference Search

Search the embedded index of Typst API functions, methods, and constructors:

python3 scripts/search-api.py "image width fit"
python3 scripts/search-api.py "color lighten" --kind method
python3 scripts/search-api.py --name str.position -v
python3 scripts/search-api.py "rightarrow" --kind symbol   # LaTeX names work
python3 scripts/search-api.py "path" --channel 0.14.2      # legacy Typst 0.14 API
python3 scripts/search-api.py --list-categories

Ecosystem Tools

Ecosystem tools: tinymist (LSP/editor), typstyle (formatter), typst-package-check (package validator), tytanic (visual test runner). For package tooling details, see package.md.

Academic Writing

For page layout, see styling.md. For reusable templates, see template.md. For state and counters, see advanced.md.

Paper Structure

#set page(paper: "us-letter", margin: 1in)
#set text(font: "New Computer Modern", size: 12pt)
#set par(justify: true, leading: 0.65em, first-line-indent: 0.5in)
#set heading(numbering: "1.1")

// Title block
#align(center)[
  #text(17pt, weight: "bold")[Paper Title]
  #v(0.5em)
  Author Name \
  _Institution_ \
  #link("mailto:email@example.edu")
  #v(1em)
]

// Abstract
#heading(outlined: false, numbering: none)[Abstract]
#par(first-line-indent: 0pt)[
  This paper presents...
]
#v(1em)

// Body
= Introduction

The rest of the paper...

Bibliography and Citations

Setup

Place a .bib file (BibTeX or BibLaTeX format) in your project:

// At the end of your document
#bibliography("refs.bib")

Citation Syntax

As shown by @smith2024.              // Smith (2024) — narrative
This was proven @smith2024.          // (Smith, 2024) — parenthetical
See @smith2024[pp. 12-15].           // (Smith, 2024, pp. 12-15) — with supplement
Multiple sources @smith2024 @doe2023.

Citation Styles

#bibliography("refs.bib", style: "ieee")          // [1], [2], ...
#bibliography("refs.bib", style: "apa")            // (Author, Year)
#bibliography("refs.bib", style: "chicago-author-date")
#bibliography("refs.bib", style: "mla")
#bibliography("refs.bib", style: "chicago-notes")  // Footnote style

Full list: https://typst.app/docs/reference/model/bibliography/

Bibliography Title

#bibliography("refs.bib", title: [References], style: "ieee")
#bibliography("refs.bib", title: none)   // No heading

Multiple .bib Files

#bibliography(("primary.bib", "secondary.bib"), style: "apa")

Multiple Bibliographies (Typst 0.15+)

Use target or group to produce separate reference lists, for example primary sources vs. secondary sources. Keep a single bibliography when the venue expects one reference section.

#bibliography("refs.bib", title: [Primary Sources], target: <primary>)
#bibliography("refs.bib", title: [Secondary Sources], target: <secondary>)

Equations

Inline and Display Math

The equation $E = m c^2$ is well known.

The quadratic formula is:
$ x = (-b plus.minus sqrt(b^2 - 4 a c)) / (2 a) $

Equation Numbering

#set math.equation(numbering: "(1)")

$ integral_0^infinity e^(-x^2) dif x = sqrt(pi) / 2 $ <eq:gaussian>

As shown in @eq:gaussian...

Aligned Equations

$ a &= b + c \
  &= d + e + f $

Theorem Environments

Typst has no built-in theorem environment, but you can build one with counters and show rules.

Simple Theorem Block

#let theorem-counter = counter("theorem")

#let theorem(body, name: none) = {
  theorem-counter.step()
  block(
    width: 100%,
    inset: 10pt,
    stroke: (left: 2pt + black),
    {
      context {
        let num = theorem-counter.display()
        [*Theorem #num*]
        if name != none [ _(#name)_]
        [*.* ]
      }
      emph(body)
    },
  )
}

#theorem[Every even integer greater than 2 is the sum of two primes.]
#theorem(name: "Fermat's Last")[No three positive integers satisfy $a^n + b^n = c^n$ for $n > 2$.]

Proof Block

#let proof(body) = block(
  width: 100%,
  inset: (left: 10pt),
  {
    [_Proof._ ]
    body
    h(1fr)
    $square$
  },
)

#proof[
  By contradiction, assume...
  Therefore the statement holds.
]

Shared Counter for Theorem-Like Environments

#let thm-counter = counter("theorem")

#let make-env(kind) = (body, name: none) => {
  thm-counter.step()
  block(
    width: 100%,
    inset: 10pt,
    stroke: (left: 2pt + black),
    {
      context {
        let num = thm-counter.display()
        [*#kind #num*]
        if name != none [ _(#name)_]
        [*.* ]
      }
      if kind == "Theorem" or kind == "Lemma" { emph(body) } else { body }
    },
  )
}

#let theorem = make-env("Theorem")
#let lemma = make-env("Lemma")
#let definition = make-env("Definition")
#let corollary = make-env("Corollary")

#definition[A group is a set $G$ with a binary operation...]
#theorem[Every finite group of prime order is cyclic.]
#corollary[Every group of order 2 is isomorphic to $ZZ slash 2 ZZ$.]

Chapter-Linked Numbering

#let thm-counter = counter("theorem")
#show heading.where(level: 1): it => {
  thm-counter.update(0)
  it
}

#let theorem(body) = {
  thm-counter.step()
  context {
    let ch = counter(heading).get().first()
    let n = thm-counter.get().first()
    block(
      width: 100%,
      inset: 10pt,
      stroke: (left: 2pt + black),
      [*Theorem #ch.#n.* ] + emph(body),
    )
  }
}

Figure and Table Numbering

// Number figures as "Figure 1", tables as "Table 1"
#set figure(numbering: "1")

// Reference: "see Figure 1", "see Table 2"
#figure(table(columns: 2, [A], [B]), caption: [Sample data]) <tab:data>
See @tab:data for results.

Supplemental Figures

#set figure.caption(separator: [. ])

#figure(
  image("plot.png", width: 80%),
  caption: [Results of experiment A],
  supplement: [Fig.],
) <fig:results>

For two-column layout and full-width elements in multi-column documents, see styling.md.

Common Academic Patterns

Advanced Typst Patterns

For language basics (syntax, imports, functions), see basics.md. For data types and operators, see types.md. For labels, references, and everyday styling, see styling.md.

XML Parsing

Typst has built-in XML parsing:

```typst #let xml-content = `xml <root> <item name="first">Value 1</item> <item name="second">Value 2</item> </root> ``.text

#let doc = xml(xml-content) // doc is an array of nodes

// Navigate structure #let root = doc.first() // Root element #let children = root.children // Child nodes #let attrs = root.attrs // Attributes dictionary

// Find elements by tag #let find-child(node, tag) = { node.children.find(c => ( type(c) == dictionary and c.at("tag", default: "") == tag )) }

#let find-children(node, tag) = { node.children.filter(c => ( type(c) == dictionary and c.at("tag", default: "") == tag )) }

// Get text content (handles nested text) #let get-text(node) = { if type(node) == str { return node } if type(node) != dictionary { return "" } node.children.map(c => { if type(c) == str { c } else { get-text(c) } }).join("") } ````

XML Node Structure

// Element node
(
  tag: "element-name",
  attrs: (attr1: "value1", attr2: "value2"),
  children: (/* child nodes or strings */),
)

// Text nodes are plain strings in the children array

State and Context

State allows tracking information across a document. Requires context to read.

Basic State

#let counter = state("my-counter", 0)

// Update state
#counter.update(n => n + 1)

// Read state (must be in context)
#context counter.get()

// Display with context
#context [Count: #counter.get()]

Custom Counters

#let example-counter = counter("example")

#let example(body) = {
  example-counter.step()
  block[*Example #context example-counter.display():* #body]
}

State for Headers

#let chapter-title = state("chapter", none)

#show heading.where(level: 1): it => {
  chapter-title.update(it.body)
  it
}

#set page(header: context { chapter-title.get() })

Final Values

// Get final value (at document end)
#let my-counter = state("my-counter", 0)
#context {
  let final-count = my-counter.final()
  [Total: #final-count]
}

Tracking Across Document

// Track citations
#let _citations = state("citations", (:))

#let cite-marker(key) = {
  [#metadata((key: key)) <my-cite>]
  _citations.update(c => {
    if key not in c { c.insert(key, 0) }
    c.at(key) += 1
    c
  })
}

// At document end
#context {
  let data = _citations.final()
  // Process collected data...
}

Query System

Query finds elements in the document. Requires context. For CLI introspection with typst eval (Typst 0.15+) or typst query (0.14 fallback), see query.md.

By Label

// Place metadata markers
#metadata((key: "item1", value: 42)) <marker>

// Query all markers
#context {
  let items = query(<marker>)
  for item in items {
    let data = item.value
    [Key: #data.key, Value: #data.value]
  }
}

By Selector

// Query all headings
#context {
  let headings = query(heading)
  for h in headings { [- #h.body] }
}

// Query specific heading level
#context {
  let h1s = query(heading.where(level: 1))
}

Within an Ancestor (Typst 0.15+)

Use selector.within to restrict matches to a section, figure, or other ancestor. This is especially useful for multi-document HTML bundles.

= Methods <sec:methods>

== Setup

#context {
  let local = query(heading.where(level: 2).within(<sec:methods>))
  [Method subsections: #local.len()]
}

By Label String

#context {
  let target = query(label("ref-mykey"))
  if target.len() > 0 {
    [Found at page #target.first().location().page()]
  }
}

Location-Based

#context {
  let items = query(<marker>)
  let here-loc = here()

  // Find items before current location
  let before = items.filter(i => (
    i.location().position().y < here-loc.position().y
  ))
}

Closure Workarounds

Closures cannot mutate captured variables (see basics.md "Mutability in Closures"). Beyond the loop accumulation pattern, two more options:

Fold for Accumulation

// Build dictionary from array
#let dict = items.fold((:), (acc, item) => {
  acc.insert(item.key, item.value)
  acc
})

State for Cross-Document

#let _data = state("data", ())

#let add-item(item) = {
  _data.update(d => { d.push(item); d })
}

// Read accumulated data
#context {
  let all-items = _data.final()
}

Content Introspection

Content elements (headings, text, figures, etc.) can be inspected and decomposed programmatically. This is essential for advanced show rules and template development.

Core Methods

= Hello *World*

// func() — the element's constructor (for type comparison)
#context {
  let h = query(heading).first()
  let is-heading = h.func() == heading   // true
  let is-text = h.func() == text         // false
}

// fields() — dictionary of all field values
#context {
  let h = query(heading).first()
  let f = h.fields()
  // f.keys() → ("level", "depth", "offset", "numbering", "supplement",
  //             "outlined", "bookmarked", "hanging-indent", "body")
}

// has() / at() — check and access fields
#context {
  let h = query(heading).first()
  let has-body = h.has("body")     // true
  let level = h.at("level")        // 1
}

Content Tree Structure

Content is a tree. Compound elements have children; leaf elements have text. Whitespace is a separate space node:

// [Hello *World*] decomposes to:
// sequence
//   ├── text("Hello")
//   ├── space
//   └── strong
//       └── text("World")

// Access children via fields()
#let body = [Hello *World*]
#let f = body.fields()
// "children" in f → true
// f.children → (text("Hello"), space, strong(...))

Show Rule Decomposition Pattern

Intercept an element, decompose its content, transform parts, reassemble:

// Bold text before first colon in list items
#show list.item: it => {
  let fields = it.body.fields()
  if "text" in fields and ":" in fields.text {
    let idx = fields.text.position(":")
    list.item[*#(fields.text.slice(0, idx)):*#(fields.text.slice(idx + 1))]
  } else if "children" in fields {
    let (before, after, found) = ((), (), false)
    for child in fields.children {
      if found { after.push(child) }
      else if type(child) != str and child.func() == text and ":" in child.text {
        let idx = child.text.position(":")
        before.push(child.text.slice(0, idx))
        found = true
        let post = child.text.slice(idx + 1)
        if post.len() > 0 { after.push(post) }
      } else { before.push(child) }
    }
    if found { list.item[*#(before.join()):*#(after.join())] } else { it }
  } else { it }
}

- Name: John Doe
- Age: 25
- No colon here

Recursive Plain-Text Extraction

Extract plain text from any content element (useful for metadata export, see query.md):

#let plain-text(content) = {
  let fields = content.fields()
  if "text" in fields {
    fields.text
  } else if "children" in fields {
    fields.children.map(c => {
      if type(c) == str { c }
      else if c.func() == [ ].func() { " " }  // space element
      else { plain-text(c) }
    }).join()
  } else if "body" in fields {
    plain-text(fields.body)
  } else if "child" in fields {
    plain-text(fields.child)
  } else { "" }
}

Common Element Fields

For performance profiling and optimization, see perf.md.

You are a Typst package QA agent. You run the full validation and testing suite on a Typst package to ensure it is ready for publishing.

Prerequisites

The package directory must contain a typst.toml manifest. If it doesn't, report this and stop.

QA Pipeline

Run these checks in order. Stop on critical failures.

1. Manifest Validation

typst-package-check check .

If typst-package-check is not installed, check typst.toml manually for required fields: name, version, entrypoint, authors, license, description.

2. Compilation

typst compile <entrypoint>

The entrypoint is specified in typst.toml. Verify it compiles without errors.

3. Formatting

find . -name '*.typ' | xargs typstyle --check

If typstyle is not installed, skip and note it.

4. Visual Tests

tt run

If tytanic (tt) is not installed or no tests/ directory exists, skip and note it.

5. Content Verification

Use HTML export on the entrypoint directly to verify it produces expected output:

typst compile <entrypoint> /dev/stdout -f html --features html 2>/dev/null

6. Checklist Audit

Verify each item:

• [ ] typst.toml has all required fields
• [ ] entrypoint file exists and compiles
• [ ] LICENSE file exists
• [ ] README.md exists with usage examples
• [ ] No compilation warnings
• [ ] Formatting passes (if typstyle available)
• [ ] Visual tests pass (if tytanic available)
• [ ] Package size is reasonable (< 10MB total)

Output Format

## Package QA: <package-name> v<version>

### Results
| Check | Status | Details |
|-------|--------|---------|
| typst-package-check | PASS/FAIL/SKIP | ... |
| Compilation | PASS/FAIL | ... |
| Formatting | PASS/FAIL/SKIP | ... |
| Visual tests | PASS/FAIL/SKIP | ... |
| LICENSE | PASS/FAIL | ... |
| README | PASS/FAIL | ... |

### Issues
- [CRITICAL] ...
- [WARNING] ...

### Verdict
READY / NOT READY for Typst Universe submission

Rules

• Run all available checks. Skip gracefully when tools are missing — note the skip, don't fail.
• Critical failures: compilation errors, missing typst.toml, missing entrypoint, typst-package-check errors.
• Warnings: missing README, missing LICENSE, no tests, formatting issues.
• If the package is a template (has [template] section in typst.toml), also verify the template entrypoint compiles.
• Report the exact commands you ran so the author can reproduce.

You are a Typst document verification agent. You systematically verify that a compiled Typst document meets its requirements using the appropriate verification method for each claim.

Verification Methods

You have three methods. Choose by what you need to check — use multiple when needed:

HTML export is experimental and ignores page-specific features. PNG requires multimodal capability (read the image file). typst eval --in is the default introspection path on Typst 0.15+; use typst query when verifying against Typst 0.14. Element selectors (heading, figure) work on any document; labeled metadata queries require the source to contain metadata elements.

Process

1. Compile — Run typst compile <file> first. If it fails, report the error and stop.

2. Identify claims — What does the document need to satisfy? Extract from:

• User's requirements (explicit)
• Document structure expectations (headings, sections)
• Content correctness (text, data, citations)
• Layout requirements (margins, fonts, columns, page numbers)

3. Select methods — For each claim, pick the cheapest sufficient method:

• "Has section X" → HTML export, grep for <h2>/<h3>
• "Table has correct data" → HTML export, check <table> content
• "Page numbers show" → PNG export (HTML ignores page features)
• "Correct metadata" → typst eval --in with label
• "Layout looks right" → PNG export, read the image
• "N figures exist" → typst eval --in with figure selector, or HTML grep for <figure>

4. Execute — Run verifications in parallel where possible.

5. Report — For each claim, report PASS/FAIL with evidence.

Output Format

## Verification: <document>

**Compiled**: yes/no (exit code)

| # | Claim | Method | Status | Evidence |
|---|-------|--------|--------|----------|
| 1 | ... | HTML | PASS | `<h2>Introduction</h2>` found |
| 2 | ... | PNG | PASS | Page 1 shows correct layout |
| 3 | ... | query | FAIL | Expected 5 figures, found 3 |

**Verdict**: PASS / FAIL

Rules

• Run verification commands yourself. Do not trust claims without output.
• Use the cheapest method that answers the question. Don't export PNG to check if a heading exists.
• If a requirement is ambiguous, state what you checked and what remains unverifiable.
• If HTML export shows warnings about ignored features, note which claims may need PNG verification.
• Element selectors do not require metadata(); use typst eval --in <file> 'query(heading).len()' for structure counts on Typst 0.15+, or typst query <file> "heading" on 0.14. Labeled metadata queries require the source to contain matching metadata() elements.

Source Formatting (optional)

When the user also asks for formatting hygiene on edited .typ files:

1. Skip this section if command -v typstyle returns nothing. 2. Run typstyle --check <file> for each file the current task created or edited. 3. On failure, inspect with typstyle --diff <file> before deciding. 4. Apply with typstyle -i <file> only when every changed line is yours. If the diff touches pre-existing code you did not edit, stop and ask the user before formatting. 5. Report formatted files separately from output verification — they are distinct claims.

Typst Language Fundamentals

For data types, operators, and built-in functions, see types.md.

Modes

Typst has two modes that determine how text is interpreted:

Markup Mode

Default mode at document top level. Text is rendered as content:

Hello *bold* and _italic_ text.

= Heading
- List item

Code Mode

Entered with #. Expressions and statements:

#let x = 1 + 2
#if condition { [content] }
#for i in range(5) { [Item #i] }

Switching Between Modes

// Code → Markup: use [ ]
#let greeting = [Hello *world*]

// Markup → Code: use #
The answer is #(1 + 2).

Imports and Paths

Import Syntax

// Import from local file (relative to current file)
#import "utils.typ": helper, format
#import "lib/core.typ": *

// Import from Typst Universe packages
#import "@preview/package-name:0.1.0": func1, func2

// Import from local packages
#import "@local/my-package:0.1.0": *

Path Resolution Rules

// File structure:
// project/
// ├── main.typ
// └── src/
//     ├── lib.typ
//     └── utils.typ

// In main.typ:
#import "src/lib.typ": *      // ✅ Relative to main.typ
#import "/src/lib.typ": *     // ✅ Root-relative (same result)

// In src/lib.typ:
#import "utils.typ": *        // ✅ Relative to lib.typ (finds src/utils.typ)
#import "/src/utils.typ": *   // ✅ Root-relative
#import "../main.typ": *      // ✅ Parent directory

Project Root (--root)

The project root controls:

1. Where /-prefixed paths resolve from 2. Security boundary (files outside root cannot be accessed)

# Default: root is the main file's directory
typst compile src/main.typ
# Root = src/, so "/lib.typ" looks for src/lib.typ

# Explicit root: set project root to current directory
typst compile src/main.typ --root .
# Root = ., so "/lib.typ" looks for ./lib.typ

# Common pattern for multi-file projects
typst compile document.typ --root .

Common Path Errors

Image and Data Files

// Images use the same path rules
#image("images/diagram.png")       // Relative to current file
#image("/assets/logo.png")         // Relative to project root

// Reading data files
#let data = json("data/config.json")
#let content = read("templates/header.typ")

Include vs Import

// import: brings symbols into scope
#import "utils.typ": helper
#helper()

// include: directly inserts file content as-is
#include "chapter1.typ"  // Content appears here

Scope difference:

// chapters/intro.typ (content file)
This is chapter 1.

// vars.typ (module file)
#let shared-title = "Intro"

// main.typ
#include "chapters/intro.typ"
#shared-title  // ❌ Error! Variables defined in included files
               // do NOT leak to parent scope

// To share variables, use import from a module file:
#import "vars.typ": shared-title
#shared-title  // ✅ Works

Use include for document content, import for reusable functions/variables.

Variables

// Immutable binding
#let name = "Alice"
#let count = 42
#let items = (1, 2, 3)

// Destructuring
#let (a, b) = (1, 2)
#let (first, ..rest) = (1, 2, 3, 4)

// Dictionary destructuring
#let (name: n, age: a) = (name: "Bob", age: 30)

Data Types, Operators, and Built-ins

See types.md for the full reference. Quick summary:

• Primitives: int, float, str, bool, none
• Collections: arrays (1, 2, 3), dictionaries (key: val)
• Content: [Hello *world*]

Functions

Basic Functions

#let greet(name) = [Hello, #name!]

#greet("Alice")  // Hello, Alice!

Default Parameters

#let greet(name, greeting: "Hello") = [#greeting, #name!]

#greet("Bob")                    // Hello, Bob!
#greet("Bob", greeting: "Hi")    // Hi, Bob!

Variadic Arguments

#let sum(..nums) = {
  let total = 0
  for n in nums.pos() {
    total += n
  }
  total
}

#sum(1, 2, 3)  // 6

Named and Positional Args

#let format(..args) = {
  let positional = args.pos()   // Array
  let named = args.named()      // Dictionary
  // ...
}

Anonymous Functions (Lambdas)

#let double = x => x * 2
#let add = (a, b) => a + b

#(1, 2, 3).map(x => x * 2)  // (2, 4, 6)

Control Flow

Conditionals

#if x > 0 {
  [Positive]
} else if x < 0 {
  [Negative]
} else {
  [Zero]
}

// Inline conditional (returns value)
#let sign = if x > 0 { "+" } else { "-" }

Loops

// For loop
#for item in items {
  [- #item]
}

#for (i, item) in items.enumerate() {
  [#i: #item]
}

#for (key, value) in dict {
  [#key = #value]
}

// While loop
#let i = 0
#while i < 5 {
  [#i ]
  i += 1
}

Loop Control

#for item in items {
  if item == "skip" { continue }
  if item == "stop" { break }
  [#item]
}

Common Pitfalls

Mutability in Closures

Closures cannot modify captured variables:

// ❌ WRONG
#let results = ()
#let add(x) = { results.push(x) }  // Error!

// ✅ CORRECT - Modify in loop
#let results = ()
#for item in items {
  results.push(item)
}

None Returns

Functions without explicit return value return none:

#let maybe(x) = {
  if x > 0 { x }
  // Returns none if x <= 0
}

// Handle none
#let result = maybe(-1)
#if result != none {
  [Got: #result]
} else {
  [No result]
}

Content vs String

// Content brackets are literal text — code is not evaluated inside
[1 + 2]         // Shows literal "1 + 2"
[Result: #(1 + 2)]  // Shows "Result: 3"

// Concatenation differs by type
#let result = [#prefix#body#suffix]       // content
#let combined = prefix-str + body-str     // string

// Check if "empty"
#let is-empty(x) = { x == none or x == "" or x == [] }

Spacing

// Adjacent code blocks merge without space
#[A]#[B]  // "AB"

// Add explicit space
#[A] #[B]  // "A B"
#[A]#h(1em)#[B]  // "A  B" (1em space)

Error Handling

Use assert(condition, message: "...") for preconditions and panic("...") for unreachable states. For assertion patterns and debug techniques, see debug.md.

Typst CLI

For full option lists, run typst <command> --help. This page is a routing index plus a few CLI gotchas that are not already covered elsewhere.

What This Adds

• Pointers to the right existing reference doc.
• CI/export flag combinations that do not fit a language or debugging guide.
• Pitfalls around PDF standards, bundle export, dependency files, package caches, templates, and page-numbered outputs.

Command Choice

CI Export Recipe

typst compile doc.typ out.pdf --root . \
  --creation-timestamp "$SOURCE_DATE_EPOCH" \
  --package-cache-path ./.typst-cache \
  --deps deps.json --deps-format json

Use this shape when comparing artifacts across machines. Pin the root, timestamp, and package cache; record dependencies for rebuild logic. In Typst 0.15, JSON deps include outputs. --deps-format make is for Makefiles; zero handles paths that cannot be represented as Unicode.

PDF Standards

typst compile doc.typ out.pdf --pdf-standard a-4
typst compile doc.typ out.pdf --pdf-standard ua-1
typst compile doc.typ out.pdf --pdf-standard a-4,ua-1

Use CLI values like 1.7, 2.0, a-4, or ua-1; do not write pdf/a-4 or pdf/ua-1. Comma-separated standards such as a-4,ua-1 are valid. --no-pdf-tags is an explicit size/compatibility tradeoff.

Bundle Export

typst compile site.typ dist -f bundle --features bundle,html

Bundle export is experimental in Typst 0.15. Use document("page.html")[...] for pages and asset("robots.txt", "...") for extra files.

Template Init

typst init @preview/charged-ieee
typst init @preview/charged-ieee:0.1.0 my-paper
typst init @local/my-template:0.1.0 draft --package-path ./packages

Use @local/... with --package-path when testing templates before publication.

Gotchas

• - means stdin for input and stdout for output, but writing PDF/PNG bytes to a terminal is rarely useful.
• Multi-page PNG/SVG outputs need a template such as page-{p}.png; {0p} pads page numbers and {t} inserts total page count.
• --pages uses one-indexed physical page numbers, not the document's printed page counter.
• watch is for human feedback loops; use compile, eval, or 0.14 query in CI.
• typst completions <shell> exists for shell setup, but agents normally do not need it.

0.14 Compatibility

• Use typst query instead of typst eval; see query.md.
• Search legacy APIs with python3 scripts/search-api.py "path" --channel 0.14.2.
• The typst-0.14.2 repository tag freezes the old skill snapshot.

When to Read Help

Use typst compile --help, typst watch --help, typst eval --help, typst query --help, or typst init --help when you need the complete current option list. This page is intentionally not a mirror of those outputs.

Converting Documents to Typst

For Typst language fundamentals (modes, functions), see basics.md. For types and operators, see types.md. For advanced table features, see tables.md.

Basic Formatting

For full Typst syntax details on headings, lists, links, and references, see basics.md.

From LaTeX: Package and Concept Map

Typst is "batteries included" — most common LaTeX packages are built in:

Concept mappings

Set rules act like LaTeX declarations scoped to the current block; direct function calls act like argument-style commands.

"LaTeX look" starter

Reproduces the Computer Modern / justified / tight-leading look of a classic LaTeX article:

#set page(margin: 1.75in)
#set par(leading: 0.55em, spacing: 0.55em, first-line-indent: 1.8em, justify: true)
#set text(font: "New Computer Modern")
#show raw: set text(font: "New Computer Modern Mono")
#show heading: set block(above: 1.4em, below: 1em)

Math Conversion

Inline vs Display Math

// Inline math
The formula $a + b = c$ is simple.

// Display math
$ integral_0^infinity e^(-x) dif x = 1 $

Common Conversions

Math Examples

// Fraction
$ frac(a + b, c) $

// Matrix
$ mat(1, 2; 3, 4) $

// Cases
$ f(x) = cases(
  x^2 "if" x > 0,
  0 "otherwise"
) $

// Aligned equations
$ a &= b + c \
  &= d + e $

Using mitex for LaTeX Math

For complex LaTeX math, use the mitex package:

#import "@preview/mitex:0.2.6": mitex, mi

// Display math
#mitex(`\frac{\partial f}{\partial x}`)

// Inline math
The value is #mi(`\alpha + \beta`).

Code Blocks

Inline code uses backticks (same as Markdown). Fenced code blocks use triple backticks with language name. For programmatic raw content:

#raw("print('hello')", lang: "python", block: true)

Tables

#table(
  columns: (auto, 1fr, 1fr),
  align: (left, center, right),

  // Header row
  [*Name*], [*Value*], [*Unit*],

  // Data rows
  [Length], [10], [cm],
  [Width], [5], [cm],
)

From Markdown Tables

Markdown:

| Name | Value |
| ---- | ----- |
| A    | 1     |
| B    | 2     |

Typst:

#table(
  columns: 2,
  [*Name*], [*Value*],
  [A], [1],
  [B], [2],
)

Figures and Images

#figure(
  image("diagram.png", width: 80%),
  caption: [A diagram showing the process],
) <fig:diagram>

// Reference
See @fig:diagram for details.

Block Elements

Quotes

#quote(block: true)[
  To be or not to be.
]

// With attribution
#quote(block: true, attribution: [Shakespeare])[
  To be or not to be.
]

Admonitions / Callouts

// Simple box
#block(
  fill: luma(240),
  inset: 1em,
  radius: 4pt,
)[
  *Note:* Important information here.
]

// Custom admonition function
#let note(body) = block(
  fill: rgb("#e8f4f8"),
  inset: 1em,
  radius: 4pt,
  width: 100%,
)[*Note:* #body]

#note[Remember to save your work.]

Escaping Rules

Special Characters

Characters requiring escape with backslash:

In Raw Strings

Inside #raw("..."), only escape:

• \ → \\
• " → \"

#raw("path\\to\\file", lang: "text")

Document Structure

From LaTeX

LaTeX:

\documentclass{article}
\title{My Document}
\author{Author Name}
\begin{document}
\maketitle
\section{Introduction}
Content here.
\end{document}

Typst:

#set document(title: "My Document", author: "Author Name")
#set page(paper: "a4")

#align(center, text(20pt)[*My Document*])
#align(center)[Author Name]

= Introduction
Content here.

From Markdown

Markdown:

---
title: My Document
author: Author Name
---

# Introduction

Some **bold** and _italic_ text.

- List item 1
- List item 2

Typst:

#set document(title: "My Document", author: "Author Name")

= Introduction

Some *bold* and _italic_ text.

- List item 1
- List item 2

Current Limitations vs LaTeX

• Plotting ecosystem: LaTeX has mature PGF/TikZ. Typst's cetz is catching up but narrower. See package search for alternatives.
• Mid-page margin changes: #set page(margin: ...) forces a page break. For local stretching, use pad() with negative padding.
• Change bars / track-changes workflows: No first-class equivalent yet.
• `\input` with partial scope: Typst include evaluates a whole file; scoping differs from TeX's \input.
• Some niche journal templates may not yet be on Typst Universe — check before committing a submission to Typst-only.

Using Pandoc for Conversion

Pandoc (since v2.18) supports Typst as an output format.

pandoc -f markdown -t typst input.md -o output.typ    # Markdown → Typst
pandoc -f latex -t typst input.tex -o output.typ       # LaTeX → Typst
pandoc input.md -o output.pdf --pdf-engine=typst        # Markdown → PDF via Typst

Common Options

pandoc input.md -t typst -o output.typ \
  -V papersize=a4 -V fontsize=12pt -V mainfont="Libertinus Serif" \
  -V section-numbering="1.1" --toc

Key -V variables: title, author, papersize, margin, fontsize, mainfont/mathfont/codefont, section-numbering, page-numbering, columns, linestretch, linkcolor. These can also be set via YAML frontmatter.

Custom templates: pandoc -D typst > template.typ, then pandoc input.md --template=template.typ -o output.typ.

Known Limitations

• Citations: @ref in Markdown → #cite(<ref>) in Typst. Escape literal @ with \@.
• Complex tables: Cell merging needs manual adjustment.
• Raw Typst blocks: Use ``` `{=typst} ``` fenced blocks for unsupported features.

Review and refine Pandoc output — custom styling and advanced layout usually need manual adjustment.

Typst Debugging Techniques

For language basics, see basics.md. For type inspection (type(), repr()), see types.md. For state/context debugging, see advanced.md.

Agent Verification Methods

Agents cannot preview PDFs directly. Three methods, choose by what you need to check:

HTML Export — Text and Structure

Outputs semantic HTML (headings → <h2>, tables → <table>, figures → <figure>). Best for verifying content, structure, and data correctness.

typst compile document.typ /dev/stdout -f html --features html 2>/dev/null
typst compile document.typ /dev/stdout -f html --features html 2>/dev/null | grep -i "expected text"

HTML export is experimental and ignores page-specific features (headers, footers, page numbers).

PNG Export — Visual Layout

Exports rendered pages as images. Use when layout matters — alignment, spacing, font rendering, page breaks, multi-column, headers/footers. Requires a multimodal agent.

# Export all pages ({p} = page number, required for multi-page documents)
typst compile document.typ "page-{p}.png" -f png

# Export specific pages only
typst compile document.typ "page-{p}.png" -f png --pages 1-3

# Higher resolution (default: 144 PPI)
typst compile document.typ "page-{p}.png" -f png --ppi 288

Then read the PNG file(s) to visually inspect the rendered output.

pdftotext — Fallback

Plain text extraction. Use when HTML export fails or for quick page-count checks.

typst compile document.typ && pdftotext document.pdf -

Object Inspection with repr

Use repr() to inspect complex objects during development:

// Basic inspection
#repr(some-variable)

// Inspect function arguments
#let my-func(..args) = {
  [DEBUG: #repr(args.pos()) | #repr(args.named())]
  // actual logic...
}

// Inspect content structure
#let c = [Hello *world*]
#repr(c)  // Shows internal content structure

// Inspect dictionary/array
#let data = (name: "test", items: (1, 2, 3))
#repr(data)  // "(name: "test", items: (1, 2, 3))"

Type + Repr Pattern

// Full debug info
#let debug-value(v) = {
  text(fill: red, size: 8pt)[
    [#type(v)] #repr(v)
  ]
}

#debug-value((a: 1, b: (2, 3)))
// Output: [dictionary] (a: 1, b: (2, 3))

Conditional Debug Output

#let DEBUG = true

#let debug(label, value) = if DEBUG {
  block(
    fill: yellow.lighten(80%),
    inset: 4pt,
    radius: 2pt,
    text(size: 8pt, fill: red)[#label: #repr(value)]
  )
}

// Usage
#debug("config", config)
#debug("items count", items.len())

Layout Debugging with measure

Use measure() to debug sizing and spacing issues. Requires context.

Basic Measurement

#context {
  let size = measure([Hello World])
  [Width: #size.width, Height: #size.height]
}
// Output: Width: 52.5pt, Height: 10pt

Measure + Repr + Place Pattern

For debugging layout issues, combine measurement with visual markers:

// Debug helper: shows measurement overlay
#let debug-measure(content, label: none) = context {
  let size = measure(content)
  let lbl = if label != none { label } else { "" }

  box[
    #content
    #place(
      top + left,
      dx: size.width,
      text(size: 6pt, fill: red)[
        #lbl #repr(size.width) × #repr(size.height)
      ]
    )
  ]
}

// Usage
#debug-measure([Some content], label: "box1")

Visual Boundary Boxes

// Show element boundaries
#let debug-box(content) = context {
  let size = measure(content)
  box(
    stroke: 0.5pt + red,
    inset: 0pt,
  )[
    #content
    #place(
      bottom + right,
      text(size: 5pt, fill: red)[#repr(size)]
    )
  ]
}

#debug-box[This text has visible boundaries]

Spacing Debug

// Visualize spacing between elements
#let debug-spacing(a, b, gap: 1em) = context {
  let size-a = measure(a)
  let size-b = measure(b)

  box[
    #a
    #h(gap)
    #place(
      dx: size-a.width,
      text(size: 6pt, fill: blue)[← #repr(gap) →]
    )
    #b
  ]
}

#debug-spacing([Left], [Right], gap: 2em)

Page Position Debug

// Show current position on page
#let debug-position() = context {
  let pos = here().position()
  place(
    dx: -20pt,
    text(size: 5pt, fill: gray)[
      (#repr(pos.x), #repr(pos.y))
    ]
  )
}

Some content #debug-position()
More content #debug-position()

State Debugging

#let my-state = state("debug-example", 0)

// Track state changes
#let debug-state-change(label) = context {
  let val = my-state.get()
  text(size: 7pt, fill: purple)[
    [#label] state = #repr(val)
  ]
}

#debug-state-change("before")
#my-state.update(n => n + 1)
#debug-state-change("after")

Query Debugging

// Debug query results
#context {
  let headings = query(heading)

  block(
    fill: luma(240),
    inset: 8pt,
    width: 100%,
  )[
    *Query Debug: #headings.len() headings found*
    #for (i, h) in headings.enumerate() {
      [

        #(i + 1). Level #h.level: #repr(h.body)
      ]
    }
  ]
}

Assertion-Based Debugging

// Fail fast with clear messages
#let validate-config(cfg) = {
  assert(type(cfg) == dictionary, message: "Config must be dictionary")
  assert("name" in cfg, message: "Config missing required 'name' field")
  assert(cfg.at("size", default: 10) > 0, message: "Size must be positive")
}

#validate-config((name: "test", size: 12))

Production Cleanup

Remove debug code before publishing:

// Single flag controls all debug output
#let DEBUG = false  // Set to true during development

#let debug(..args) = if DEBUG { /* debug logic */ }
#let debug-box(c) = if DEBUG { /* with borders */ } else { c }
#let debug-measure(c, ..) = if DEBUG { /* with overlay */ } else { c }

Or use conditional compilation:

# Compile with debug flag via CLI (requires wrapper)
typst compile document.typ --input debug=true

// In document
#let DEBUG = sys.inputs.at("debug", default: "false") == "true"

example-utils

A minimal example Typst package demonstrating package structure and conventions.

Installation

Local Development

Copy to your local packages directory:

# Linux/macOS
mkdir -p ~/.local/share/typst/packages/local/example-utils/0.1.0
cp -r . ~/.local/share/typst/packages/local/example-utils/0.1.0/

# Then import in your document
#import "@local/example-utils:0.1.0": *

From Typst Universe (after publishing)

#import "@preview/example-utils:0.1.0": *

Usage

#import "@local/example-utils:0.1.0": note, callout, badge, iso-date, divider

// Note boxes
#note[This is an info note.]
#note(type: "warning")[Be careful!]
#note(type: "error", title: "Error")[Something went wrong.]
#note(type: "tip", title: "Pro Tip")[This is helpful.]

// Callout box
#callout(title: "Important")[
  This is a callout with a colored header.
]

// Badge
Status: #badge[Active] #badge(color: red)[Deprecated]

// Date formatting
Today: #iso-date(datetime.today())

// Divider
#divider()

API Reference

note(body, type: "info", title: none)

Creates a styled note box.

• body: Content to display
• type: One of "info", "warning", "error", "tip"
• title: Optional title

callout(body, title: [Note], color: rgb("#3b82f6"))

Creates a callout box with colored header.

badge(label, color: rgb("#3b82f6"), text-color: white)

Creates a colored badge/tag.

iso-date(d)

Formats a datetime as YYYY-MM-DD.

divider(width: 100%, stroke: 0.5pt + gray)

Creates a horizontal divider line.

Package Structure

example-utils/
├── typst.toml      # Package manifest
├── lib.typ         # Public API entrypoint
├── README.md       # Documentation
└── src/
    ├── boxes.typ       # Box components (note, callout)
    └── formatting.typ  # Formatting utilities (badge, iso-date)

License

MIT

Typst Package Development

For Typst language basics (syntax, functions), see basics.md. For types and operators, see types.md.

Complete example: See examples/package-example/ for a minimal publishable package with submodules.

Package Structure

my-package/
├── typst.toml       # Package manifest (required)
├── lib.typ          # Public API entrypoint
├── src/             # Internal modules
│   ├── core.typ
│   └── utils.typ
├── LICENSE
└── README.md

typst.toml Manifest

[package]
name = "my-package"
version = "0.1.0"
entrypoint = "lib.typ"
authors = ["Your Name <@github-username>"]
license = "MIT"
description = "Short description"
repository = "https://github.com/user/my-package"
keywords = ["keyword1", "keyword2"]
categories = ["utility"]
compiler = "0.12.0"
exclude = ["tests/*", "docs/*"]

Optional Template Section

[template]
path = "template"
entrypoint = "main.typ"
thumbnail = "thumbnail.png"

Valid Categories

Module System

Import Syntax

// From Typst Universe
#import "@preview/package:0.1.0": func1, func2
#import "@preview/package:0.1.0": *

// From local file
#import "src/core.typ": main-func
#import "utils.typ": long-name as short

Entrypoint Pattern (lib.typ)

// Re-export public API only
#import "src/core.typ": main-func, Config
#import "src/utils.typ": helper

Path Resolution in Packages

Important: Inside a package, the root path (/) resolves to the package directory itself, not the user's project root.

// Package structure:
// my-package/
// ├── lib.typ (entrypoint)
// └── src/
//     ├── core.typ
//     └── assets/
//         └── icon.svg

// In lib.typ:
#import "/src/core.typ": *     // ✅ Resolves to my-package/src/core.typ

// In src/core.typ:
#import "/src/assets/icon.svg" // ✅ Resolves to my-package/src/assets/icon.svg
#import "assets/icon.svg"      // ✅ Same result (relative to core.typ)

This isolation ensures packages are self-contained and don't depend on the user's file structure.

Modules must form a DAG (no circular imports).

API Design

Function Documentation

/// Creates a styled note box.
/// - body (content): The content to display
/// - type (string): "info", "warning", or "error"
/// -> content
#let note(body, type: "info") = { ... }

For configuration patterns (default dictionaries, overrides), see template.md.

Local Development

Local Package Path

Install locally:

mkdir -p ~/.local/share/typst/packages/local/my-package/0.1.0
cp -r . ~/.local/share/typst/packages/local/my-package/0.1.0/

Testing Locally

#import "@local/my-package:0.1.0": *
#my-func(test-input)

Visual Regression Testing with tytanic

tytanic (tt) compiles test files, renders pages to PNG, and diffs against stored references.

cargo install tytanic

Directory layout:

my-package/
├── typst.toml
├── lib.typ
└── tests/
    └── basic/
        ├── test.typ       # test document
        └── ref/
            └── 1.png      # reference image (one per page)

Test file (tests/basic/test.typ):

#import "/lib.typ": *
#my-func("test input")

Commands:

tt run                  # compile and compare all tests against refs
tt run basic            # run a specific test
tt update               # accept current output as new references
tt list                 # list discovered tests

Commit ref/ images to version control so CI can detect regressions. See the tytanic guide for ephemeral references and advanced test modes.

Formatting with typstyle

cargo install typstyle
typstyle -i lib.typ src/*.typ       # format in place
typstyle --check lib.typ src/*.typ  # CI check (exit 1 if unformatted)

Publishing

Validate with typst-package-check

Run the official validator before submitting to Typst Universe:

cargo install typst-package-check
typst-package-check check .

Checks: typst.toml schema, entrypoint exists, package compiles, license valid, file size limits.

To Typst Universe

1. Run typst-package-check check . and fix any errors 2. Fork https://github.com/typst/packages 3. Add package to packages/preview/my-package/0.1.0/ 4. Create pull request

Versioning

Checklist

• [ ] typst.toml complete
• [ ] entrypoint file exports public API
• [ ] LICENSE included
• [ ] README.md with usage examples
• [ ] typst-package-check check . passes
• [ ] typstyle --check passes
• [ ] tt run passes (if visual tests exist)

Best Practices

1. Minimal exports: Only expose what users need 2. Sensible defaults: All optional parameters have defaults 3. Document API: Use /// comments for all public functions 4. Semantic versioning: Follow semver strictly 5. No breaking changes: Deprecate before removing

Typst Performance Profiling

Use Typst's built-in timing trace to find slow stages and hotspots.

Generate Timing Trace

# Emit Chrome trace-style JSON
typst compile document.typ output.pdf --root . --timings build/timings.json 2>&1

Notes:

• --timings writes trace events in Chrome trace format.
• --root should match your project root for correct imports.

View the Trace

Open in any trace viewer:

• Chrome: chrome://tracing
• Perfetto: https://ui.perfetto.dev/

Load build/timings.json to explore event timelines.

Aggregate Hotspots (Top N)

Use the bundled script to summarize total time by event name:

python3 scripts/perf-timings.py build/timings.json

Output includes a summary header (event count, threads, wall time) followed by a table with count, total, avg, and max per event.

CLI Examples

# Top 5 rows
python3 scripts/perf-timings.py build/timings.json --top 5

# Self time (excluding children) — reveals true hotspots vs containers
python3 scripts/perf-timings.py build/timings.json --self-time

# Show source file:line locations from trace args
python3 scripts/perf-timings.py build/timings.json --source --top 5

# Per-thread breakdown — check if work is balanced across threads
python3 scripts/perf-timings.py build/timings.json --by-thread --contains layout

# Only entries with total >= 50ms
python3 scripts/perf-timings.py build/timings.json --min-ms 50

# Filter by substring
python3 scripts/perf-timings.py build/timings.json --contains layout --top 3

# Sort by count instead of total time
python3 scripts/perf-timings.py build/timings.json --sort count --top 3

# JSON output for tooling (includes all fields: total, self, avg, max, sources)
python3 scripts/perf-timings.py build/timings.json --json --top 2

Interpreting Self Time

Total time includes children. Self time subtracts direct child durations.

Use --self-time to sort by self time and find the actual bottlenecks.

Example

Run the bundled perf test:

typst compile examples/perf-test.typ build/perf-test.pdf --root . --timings build/timings.json
python3 scripts/perf-timings.py build/timings.json

Practical Tips

• Use --self-time first to find real bottlenecks, not just wrapper events.
• Use --source to map hotspots back to specific lines in your .typ files.
• Use --by-thread to check if one thread is bottlenecked while others are idle.
• Re-run with the same inputs to compare timing deltas.
• Use --font-path if your project relies on non-system fonts.
• Large query() or state() usage can dominate timelines; optimize those first.

CLI Introspection (typst eval / typst query)

For the in-document query() function, see advanced.md. For language basics, see basics.md.

Use typst eval --in <file> on Typst 0.15+. It evaluates a Typst expression in a document context and serializes the result as JSON or YAML. typst query is deprecated in Typst 0.15, but remains the 0.14 fallback.

Version Check

typst --version

Typst 0.15+: typst eval

typst eval --in doc.typ 'query(heading).len()'
typst eval --in doc.typ 'query(<doc-info>).first().value' --pretty
typst eval --in doc.typ 'query(<task>).map(it => it.value)' --pretty

Use typst eval for expression probes too:

typst eval '1 + 2'
typst eval 'type("hi")'

0.14 Fallback: typst query

typst query [OPTIONS] <INPUT> <SELECTOR>

typst query accepts element selectors and labels:

typst query doc.typ "heading"
typst query doc.typ "figure"
typst query doc.typ "<doc-info>" --field value --one --pretty

The useful 0.14 options are --field, --one, --format json|yaml, --pretty, --input, and --root.

Selectors

Element type

typst eval --in doc.typ 'query(heading).len()'
typst eval --in doc.typ 'query(figure).len()'
typst eval --in doc.typ 'query(math.equation).len()'

Label

typst eval --in doc.typ 'query(<my-label>).first().value'

Filtered with .where()

typst eval --in doc.typ 'query(heading.where(level: 1)).len()'
typst eval --in doc.typ 'query(figure.where(kind: image)).len()'
typst eval --in doc.typ 'query(figure.where(kind: table)).len()'

Restricted with .within() (Typst 0.15+)

typst eval --in doc.typ 'query(heading.where(level: 2).within(<methods>)).len()'

metadata() Export

metadata(value) creates invisible content that holds any Typst value. Attach a label, then inspect it from the CLI.

#metadata("1.0.0") <version>
#metadata((title: "Report", status: "draft")) <doc-info>

typst eval --in doc.typ 'query(<version>).first().value'
# -> "1.0.0"

typst eval --in doc.typ 'query(<doc-info>).first().value' --pretty
# -> {"title": "Report", "status": "draft"}

0.14 equivalent

typst query doc.typ "<version>" --field value --one
typst query doc.typ "<doc-info>" --field value --one --pretty

Type Mapping

Label Placement in context

The label must go on metadata() itself, inside the context block:

// CORRECT: label on metadata
#context {
  let data = query(heading).len()
  [#metadata(data) <heading-count>]
}

// WRONG: label on context block, returns context content with no value field
#context {
  metadata(query(heading).len())
} <heading-count>

Patterns

Extract document metadata

// doc.typ
#metadata((
  title: "Product Spec",
  version: "2.1.0",
  authors: ("Alice", "Bob"),
  status: "final",
)) <doc-info>

typst eval --in doc.typ 'query(<doc-info>).first().value' --pretty
VERSION=$(typst eval --in doc.typ 'query(<doc-info>).first().value.at("version")' | jq -r .)

Export document statistics

#context {
  let stats = (
    headings: query(heading).len(),
    figures: query(figure).len(),
    equations: query(math.equation).len(),
    pages: counter(page).final().first(),
  )
  [#metadata(stats) <doc-stats>]
}

typst eval --in doc.typ 'query(<doc-stats>).first().value' --pretty
# -> {"headings":5,"figures":3,"equations":12,"pages":8}

Export TOC with page numbers

Heading bodies are content, not strings. Use the plain-text helper from advanced.md (Content Introspection section) to extract text.

#let plain-text(value) = repr(value)

#context {
  let toc = query(heading).map(h => {
    let pg = counter(page).at(h.location()).first()
    (level: h.level, title: plain-text(h.body), page: pg)
  })
  [#metadata(toc) <toc-export>]
}

typst eval --in doc.typ 'query(<toc-export>).first().value' --pretty
# -> [{"level":1,"title":"Introduction","page":1}, ...]

Multi-pass compilation

Query in pass 1, feed back via --input in pass 2. Example: "Page X of N" footer.

// main.typ
#let total = sys.inputs.at("total-pages", default: none)

#set page(footer: context {
  let current = counter(page).get().first()
  if total != none [Page #current of #total] else [Page #current]
})

= Chapter One
#lorem(200)

= Chapter Two
#lorem(300)

#context [#metadata(counter(page).final().first()) <page-count>]

PAGES=$(typst eval --in main.typ 'query(<page-count>).first().value')
typst compile main.typ --input "total-pages=$PAGES"

Conditional metadata with sys.inputs

Label must be on metadata() inside the if, not on the if block.

#let mode = sys.inputs.at("mode", default: "normal")
#if mode == "ci" [
  #metadata((
    version: "1.0.0",
    packages: ("cetz", "tablex"),
  )) <ci-meta>
]

typst eval --in doc.typ 'query(<ci-meta>).first().value' --input mode=ci --pretty

Structured task/status tracking

Multiple elements can share a label. query(<task>) returns all matching metadata elements.

#let task(name, status, priority: "medium") = {
  metadata((name: name, status: status, priority: priority))
}

#task("Design API", "done", priority: "high") <task>
#task("Write tests", "in-progress") <task>
#task("Deploy", "pending", priority: "low") <task>

typst eval --in doc.typ 'query(<task>).map(it => it.value)' --pretty
# -> [{"name":"Design API","status":"done","priority":"high"}, ...]

CI version gate

#!/bin/bash
EXPECTED="2.1.0"
ACTUAL=$(typst eval --in doc.typ 'query(<version>).first().value' | tr -d '"')
if [ "$ACTUAL" != "$EXPECTED" ]; then
  echo "Version mismatch: expected $EXPECTED, got $ACTUAL" >&2
  exit 1
fi

Batch validation

for f in docs/*.typ; do
  typst eval --in "$f" 'query(<doc-info>).first().value' > /dev/null 2>&1 \
    || echo "MISSING metadata: $f" >&2
done

Agent Workflow

Use typst eval --in to verify document structure without opening a PDF:

typst eval --in doc.typ 'query(<expected-section>).len() > 0' | grep true
typst eval --in doc.typ 'query(figure).len()'                    # figure count
typst eval --in doc.typ 'query(<doc-info>).first().value.at("status")' | jq -e '. == "final"'

See query-export.typ for a runnable example.

Fileless Probe

For a raw expression:

typst eval '1 + 2'
# -> 3

For document-context probes from stdin:

printf '#metadata(1 + 2) <probe>\n' | typst eval --in - 'query(<probe>).first().value'
# -> 3

Useful when docs or search are ambiguous about return types or runtime behavior. Exit code 1 on compile failure; stderr carries the error.