Typst
This skill targets Typst 0.15+. For Typst 0.14.2, use the typst-0.14.2
repository tag for the previous skill snapshot.
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):
| 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
#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.
| 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 |
| Upgrade older Typst code, 0.15 breaking changes |
migration.md |
| Use Typst CLI commands and build options |
cli.md |
| Extract data from documents, multi-pass builds |
query.md |
Developing Packages and Templates
| When you need to... |
Read |
State, counters, in-document query(), XML |
advanced.md |
| CLI introspection, metadata export, multi-pass |
query.md |
| Create a reusable template function |
template.md |
| Create or publish a package |
package.md |
| Verify output (HTML/PNG/pdftotext, repr) |
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
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 |
A short note or memo |
basics.md, styling.md |
| styled-document.typ |
A multi-section report with page styling |
styling.md, tables.md |
| template-report.typ |
A reusable template for a series |
template.md |
| tables-showcase.typ |
A data-heavy doc (tables, CSV/JSON) |
tables.md, types.md |
| academic-paper.typ |
A paper with citations, theorems, math |
academic.md |
| query-export.typ |
Metadata export or multi-pass builds |
query.md |
| package-example/ |
A publishable package |
package.md |
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 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 --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.
1---2name: typst3description: 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 Typst4---5
6# Typst
7
8This skill targets Typst 0.15+. For Typst 0.14.2, use the `typst-0.14.2`
9repository tag for the previous skill snapshot.
10
11## Compilation
12
13```bash
14typst compile document.typ # compile once → PDF
15typst compile document.typ output.pdf # explicit output path
16typst compile document.typ -f png # export as PNG image
17typst compile src/main.typ --root . # set project root for /path imports
18typst watch document.typ # recompile on change
19typst eval --in document.typ 'query(heading).len()' # Typst 0.15+ introspection
20```
21
22For command options beyond this quick reference, see [cli.md](cli.md).
23
24Agent verification — choose by what you need to check (see [debug.md](debug.md) for details):
25
26| Method | Command | Best for |
27| ----------- | ----------------------------------------------------------------------- | ----------------------------------------- |
28| HTML export | `typst compile doc.typ /dev/stdout -f html --features html 2>/dev/null` | Text content, structure, headings, tables |
29| PNG export | `typst compile doc.typ page-{p}.png -f png` | Visual layout, alignment, spacing, fonts |
30| pdftotext | `typst compile doc.typ && pdftotext doc.pdf -` | Fallback for page-specific content |
31
32## Minimal Document
33
34```typst
35#set page(paper: "a4", margin: 2cm)
36#set text(size: 11pt)
37
38= Title
39
40Content goes here.
41```
42
43## Writing Documents
44
45**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.
46
47| When you need to... | Read |
48| -------------------------------------------------- | ------------------------------ |
49| Learn syntax, imports, functions, control flow | [basics.md](basics.md) |
50| Learn data types, operators, string/array methods | [types.md](types.md) |
51| Style pages, headings, figures, layout | [styling.md](styling.md) |
52| Tables, grids, cell spans, borders, data tables | [tables.md](tables.md) |
53| Academic papers, bibliography, theorems, equations | [academic.md](academic.md) |
54| Convert from Markdown or LaTeX | [conversion.md](conversion.md) |
55| Upgrade older Typst code, 0.15 breaking changes | [migration.md](migration.md) |
56| Use Typst CLI commands and build options | [cli.md](cli.md) |
57| Extract data from documents, multi-pass builds | [query.md](query.md) |
58
59## Developing Packages and Templates
60
61| When you need to... | Read |
62| ---------------------------------------------- | -------------------------- |
63| State, counters, in-document `query()`, XML | [advanced.md](advanced.md) |
64| CLI introspection, metadata export, multi-pass | [query.md](query.md) |
65| Create a reusable template function | [template.md](template.md) |
66| Create or publish a package | [package.md](package.md) |
67| Verify output (HTML/PNG/pdftotext, repr) | [debug.md](debug.md) |
68| Profile performance (--timings, hotspots) | [perf.md](perf.md) |
69
70[basics.md](basics.md) and [types.md](types.md) are also the foundation for developers.
71
72## Finding Packages
73
74Search the embedded index of Typst Universe packages (updated weekly):
75
76```bash
77python3 scripts/search-packages.py "what you need"
78python3 scripts/search-packages.py "chart" --category visualization
79python3 scripts/search-packages.py --category cv --top 5
80python3 scripts/search-packages.py --list-categories
81```
82
83## Common Errors
84
85| Error | Cause | Fix |
86| ------------------------------------------------ | ---------------------------- | ---------------------------------------------------- |
87| "unknown variable" | Undefined identifier | Check spelling, ensure `#let` before use |
88| "expected X, found Y" | Type mismatch | Check function signature in docs |
89| "file not found" | Bad import path | Paths resolve relative to current file |
90| "unknown font" | Font not installed | Use system fonts or web-safe alternatives |
91| "maximum function call depth exceeded" | Deep recursion | Use iteration instead |
92| "can only be used when context is known" | Missing `context` wrapper | Wrap in `context { ... }` |
93| "unexpected argument" | `=` instead of `:` for args | Named args use `:` syntax: `func(name: value)` |
94| "variables from outside are read-only" | Mutating captured variable | Use loop accumulation or `state()` — see advanced.md |
95| "expected content, found string" (or vice versa) | Content/string type mismatch | Use `[#str-var]` to embed string in content |
96| set/show rule has no effect | Rule placed after content | Place set/show rules before the content they target |
97
98## Examples
99
100Copy the closest starter, adjust, compile. For CVs, letters, or slides, search packages: `python3 scripts/search-packages.py --category cv` (or `letter`, `presentation`).
101
102| Example | Start here when you want... | Next read |
103| --------------------------------------------------- | ---------------------------------------- | ------------------------------------------------ |
104| [basic-document.typ](examples/basic-document.typ) | A short note or memo | [basics.md](basics.md), [styling.md](styling.md) |
105| [styled-document.typ](examples/styled-document.typ) | A multi-section report with page styling | [styling.md](styling.md), [tables.md](tables.md) |
106| [template-report.typ](examples/template-report.typ) | A reusable template for a series | [template.md](template.md) |
107| [tables-showcase.typ](examples/tables-showcase.typ) | A data-heavy doc (tables, CSV/JSON) | [tables.md](tables.md), [types.md](types.md) |
108| [academic-paper.typ](examples/academic-paper.typ) | A paper with citations, theorems, math | [academic.md](academic.md) |
109| [query-export.typ](examples/query-export.typ) | Metadata export or multi-pass builds | [query.md](query.md) |
110| [package-example/](examples/package-example/) | A publishable package | [package.md](package.md) |
111
112## Dependencies
113
114- **typst CLI 0.15+ recommended**: Install from https://typst.app or via package manager
115 - macOS: `brew install typst`
116 - Linux: `cargo install typst-cli`
117 - Windows: `winget install typst`
118- **pdftotext** (optional): For text-level output verification
119- **Python 3.10+** (optional): For package search and validation scripts
120- **jq** (optional): For parsing JSON output from `typst eval` in shell scripts
121
122## API Reference Search
123
124Search the embedded index of Typst API functions, methods, and constructors:
125
126```bash
127python3 scripts/search-api.py "image width fit"
128python3 scripts/search-api.py "color lighten" --kind method
129python3 scripts/search-api.py --name str.position -v
130python3 scripts/search-api.py "rightarrow" --kind symbol # LaTeX names work
131python3 scripts/search-api.py --list-categories
132```
133
134## Ecosystem Tools
135
136Ecosystem tools: **tinymist** (LSP/editor), **typstyle** (formatter), **typst-package-check** (package validator), **tytanic** (visual test runner). For package tooling details, see [package.md](package.md).
lucifer1004