typst

# Typst ## Compilation ```bash 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 query document.typ "<label>" # extract metadata as JSON (see query.md) ``` For command options beyond this quick reference, see [cli.md](cli.md). Agent verification — choose by what you need to check (see [debug.md](debug.md) for details): | Method | Command | Best for | | ----------- | ----------------------------------------------------------------------- | ----------------------------------------- | | HTML export | `typst compile doc.typ /dev/stdout -f html --features html 2>/dev/null` | Text content, structure, headings, tables | | PNG export | `typst compile doc.typ page-{p}.png -f png` | Visual layout, alignment, spacing, fonts | | pdftotext | `typst compile doc.typ && pdftotext doc.pdf -` | Fallback for page-specific content | ## Minimal Document ```typst #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](#examples) below — it's faster than starting blank and each row names the docs to read next. | When you need to... | Read | | -------------------------------------------------- | ------------------------------ | | Learn syntax, imports, functions, control flow | [basics.md](basics.md) | | Learn data types, operators, string/array methods | [types.md](types.md) | | Style pages, headings, figures, layout | [styling.md](styling.md) | | Tables, grids, cell spans, borders, data tables | [tables.md](tables.md) | | Academic papers, bibliography, theorems, equations | [academic.md](academic.md) | | Convert from Markdown or LaTeX | [conversion.md](conversion.md) | | Use Typst CLI commands and build options | [cli.md](cli.md) | | Extract data from documents, multi-pass builds | [query.md](query.md) | ## Developing Packages and Templates | When you need to... | Read | | ------------------------------------------- | -------------------------- | | State, counters, in-document `query()`, XML | [advanced.md](advanced.md) | | CLI query, metadata export, multi-pass | [query.md](query.md) | | Create a reusable template function | [template.md](template.md) | | Create or publish a package | [package.md](package.md) | | Verify output (HTML/PNG/pdftotext, repr) | [debug.md](debug.md) | | Profile performance (--timings, hotspots) | [perf.md](perf.md) | [basics.md](basics.md) and [types.md](types.md) are also the foundation for developers. ## Finding Packages Search the embedded index of Typst Universe packages (updated weekly): ```bash 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 | 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 Copy the closest starter, adjust, compile. For CVs, letters, or slides, search packages: `python3 scripts/search-packages.py --category cv` (or `letter`, `presentation`). | Example | Start here when you want... | Next read | | --------------------------------------------------- | ---------------------------------------- | ------------------------------------------------ | | [basic-document.typ](examples/basic-document.typ) | A short note or memo | [basics.md](basics.md), [styling.md](styling.md) | | [styled-document.typ](examples/styled-document.typ) | A multi-section report with page styling | [styling.md](styling.md), [tables.md](tables.md) | | [template-report.typ](examples/template-report.typ) | A reusable template for a series | [template.md](template.md) | | [tables-showcase.typ](examples/tables-showcase.typ) | A data-heavy doc (tables, CSV/JSON) | [tables.md](tables.md), [types.md](types.md) | | [academic-paper.typ](examples/academic-paper.typ) | A paper with citations, theorems, math | [academic.md](academic.md) | | [query-export.typ](examples/query-export.typ) | Metadata export or multi-pass builds | [query.md](query.md) | | [package-example/](examples/package-example/) | A publishable package | [package.md](package.md) | ## 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.10+** (optional): For package search and validation scripts - **jq** (optional): For parsing JSON output from `typst query` in shell scripts ## API Reference Search Search the embedded index of Typst API functions, methods, and constructors: ```bash 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 --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](package.md).