---

name: typst description: 'Typst document creation and package development. Use when: (1) Working with .typ files, (2) User mentions typst, typst.toml, or typst-cli, (3) Creating or using Typst packages, (4) Developing document templates, (5) Converting Markdown/LaTeX to Typst'

Typst

Modern typesetting system — simpler than LaTeX, faster compilation, programmable.

Compilation

typst compile document.typ              # compile once
typst compile document.typ output.pdf   # explicit output path
typst compile src/main.typ --root .     # set project root for /path imports
typst watch document.typ                # recompile on change

Agents cannot preview PDFs. Verify via exit code and pdftotext:

typst compile document.typ && pdftotext document.pdf - | head -20

Minimal Document

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

= Title

Content goes here.

Writing Documents

| When you need to... | Read | | -------------------------------------------------- | ------------------------------ | | Learn syntax, imports, functions, control flow | basics.md | | Learn data types, operators, string/array methods | types.md | | Style pages, headings, figures, layout | styling.md | | Tables, grids, cell spans, borders, data tables | tables.md | | Academic papers, bibliography, theorems, equations | academic.md | | Convert from Markdown or LaTeX | conversion.md |

Start with basics.md — it covers modes, imports, functions, control flow, and common pitfalls. For data types and operators, see types.md.

Developing Packages and Templates

| When you need to... | Read | | ----------------------------------------- | -------------------------- | | Use state, context, query, or parse XML | advanced.md | | Create a reusable template function | template.md | | Create or publish a package | package.md | | Debug output (pdftotext, repr, measure) | debug.md | | Profile performance (--timings, hotspots) | perf.md |

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

Import Pattern

#import "@preview/package-name:version": *
#import "@preview/package-name:version": specific-func

Common Errors

| Error | Cause | Fix | | ------------------------------------------------ | ---------------------------- | ---------------------------------------------------- | | "unknown variable" | Undefined identifier | Check spelling, ensure #let before use | | "expected X, found Y" | Type mismatch | Check function signature in docs | | "file not found" | Bad import path | Paths resolve relative to current file | | "unknown font" | Font not installed | Use system fonts or web-safe alternatives | | "maximum function call depth exceeded" | Deep recursion | Use iteration instead | | "can only be used when context is known" | Missing context wrapper | Wrap in context { ... } | | "unexpected argument" | = instead of : for args | Named args use : syntax: func(name: value) | | "variables from outside are read-only" | Mutating captured variable | Use loop accumulation or state() — see advanced.md | | "expected content, found string" (or vice versa) | Content/string type mismatch | Use [#str-var] to embed string in content | | set/show rule has no effect | Rule placed after content | Place set/show rules before the content they target |

Examples

| Example | Description | | --------------------------------------------------- | ---------------------------------------------------- | | basic-document.typ | Complete beginner document with all common elements | | styled-document.typ | Set/show rules, page layout, multi-region document | | template-report.typ | Reusable template with headers, counters, note boxes | | tables-showcase.typ | Table features: spans, stripes, grids, data gen | | academic-paper.typ | Paper with theorems, equations, bibliography layout | | package-example/ | Minimal publishable package with submodules |

Dependencies

• typst CLI: 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.8+ (optional): For package search script