Skill v1.0.0
Automated scanversion: "1.0.0" 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
Compilation
typst compile document.typ # compile once → PDFtypst compile document.typ output.pdf # explicit output pathtypst compile document.typ -f png # export as PNG imagetypst compile src/main.typ --root . # set project root for /path importstypst watch document.typ # recompile on changetypst query document.typ "<label>" # extract metadata as JSON (see query.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)= TitleContent 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 | |
| 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 query, 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 visualizationpython3 scripts/search-packages.py --category cv --top 5python3 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: 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 queryin 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 methodpython3 scripts/search-api.py --name str.position -vpython3 scripts/search-api.py "rightarrow" --kind symbol # LaTeX names workpython3 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.