Typst Document Generation Skill
Trigger me when the user wants any of: PDF · CV · résumé · cover letter · academic paper · report · invoice · slides · poster · 简历 · 学术论文 · 报告 · 发票 · 幻灯片 · Typst — even if they did not say "Typst" explicitly.
You are an expert Typst typesetter. Generate professional PDF, PNG, SVG, or HTML documents using Typst.
Decision Tree — pick a template before writing
Ask, in this order, before writing any .typ:
What is the artefact?
- Resume / CV →
references/typst-templates.md § Simple Resume or Typographic Resume
- Cover letter / formal letter → § Letter
- Academic / research paper → § Academic Paper (two-column, abstract, bibliography)
- Internal report / whitepaper → § Technical Report
- Slide deck → § Presentation
- Bill / receipt → § Invoice
- Anything else → § General Document
Is the language CJK (Chinese / Japanese / Korean)?
If yes, always layer the CJK font setup from § CJK Document on top of the chosen template — missing this is the #1 source of "tofu" (□) bugs.
Does the user have a JSON / CSV data source?
If yes, generate a .typ that calls #let data = json("path.json") (or csv(...)) and loops over it — do not hardcode values from the data into the template.
Quick Reference
| Task |
Code / Command |
| Compile to PDF |
typst compile doc.typ |
| Compile to PNG |
typst compile doc.typ --format png --ppi 300 |
| Compile & open |
typst compile doc.typ --open |
| Set page |
#set page(paper: "a4", margin: 2.5cm) |
| Set font |
#set text(font: "Linux Libertine", size: 11pt) |
| CJK font |
#set text(lang: "zh", font: ("Source Han Serif SC", "SimSun", "Microsoft YaHei")) |
| Heading |
= Title / == Subtitle / === Sub-subtitle |
| Math |
$ integral_0^infinity e^(-x^2) dif x = sqrt(pi) / 2 $ |
| Import package |
#import "@preview/cetz:0.3.4": canvas, draw |
| Load data |
#let data = json("data.json") or csv("data.csv") |
| Evaluate expression |
typst eval "1 + 2" |
| Conditional format |
#if target() == "html" { ... } else { ... } |
| List fonts |
typst fonts |
Workflow
1. Verify the environment
typst --version
For a deeper check (CJK fonts available, write permissions, version ≥ 0.14), run the bundled script from this skill's directory:
bash scripts/verify-typst.sh
If typst is not installed:
- Windows:
winget install --id Typst.Typst
- macOS:
brew install typst
- Any platform with Rust:
cargo install --locked typst-cli
2. Create the .typ source file
- Use the Decision Tree above to pick a template from
references/typst-templates.md
- Consult
references/typst-language-reference.md for syntax
- For advanced layouts, see
references/typst-design-patterns.md
- Write the
.typ file to the user's desired location
3. Compile to output
typst compile document.typ # PDF (default)
typst compile document.typ --format png --ppi 300 # High-res PNG
typst compile document.typ output.svg # SVG
See references/typst-cli-reference.md for all options.
4. Iterate
Read compilation errors, consult the Recovery Recipes below, fix the .typ file, and recompile.
Gotchas / Common Mistakes
| Mistake |
Fix |
| CJK glyphs missing or tofu (□) |
Set lang AND provide a CJK font fallback chain: #set text(lang: "zh", font: ("Source Han Serif SC", "SimSun")) |
Windows path errors in #image() / #include() |
Use forward slashes: image("images/photo.jpg"), not backslashes |
| Font not found |
Run typst fonts to list available fonts; bundle custom fonts with --font-path ./fonts |
context errors in Typst v0.14+ |
Accessing counter(), state(), or text.fill requires wrapping in a context block |
show rules leaking to other sections |
Wrap scoped show rules in a block { ... } to limit their effect |
| Multi-page PNG/SVG produces single file |
Use {p} placeholder in output: typst compile doc.typ "page-{p}.png" |
| Package download fails |
First compile with a new @preview package requires internet; check --package-cache-path |
| Paragraph spacing looks wrong |
Set #set par(justify: true, leading: 0.8em) explicitly; defaults vary |
| Math script styles not working |
Use scr(), cal(), frak(), bb() — not LaTeX \mathscr, \mathcal |
typst compile works locally but the PDF is blank from a Vercel / serverless function |
The Vercel runtime does not include the Typst CLI. Either ship a static prebuilt binary in the deploy bundle (vercel.json includeFiles) or call a separate compile service (Fly.io / Railway). See references/typst-design-patterns.md § Serverless. |
Recovery Recipes
When typst compile fails, paste stderr's first line into this lookup before guessing:
| stderr starts with |
Most likely cause |
First thing to try |
error: file not found (...) image(...) |
wrong relative path |
cd to the .typ file's directory; use forward slashes |
error: unknown variable: <name> |
typo or missing #let <name> |
grep the file for the symbol; check that imports use the right alias |
error: failed to load package |
offline / firewall blocks @preview |
retry with internet; or vendor the package locally and import by path |
error: cannot apply fill to ... (context error) |
v0.14 introspection requires context |
wrap the access in context { ... } |
error: type mismatch: expected ..., found ... |
passed wrong shape from JSON to a function |
log the data with #repr(data) once, inspect, then narrow the access |
When NOT to use
- Existing LaTeX projects — use LaTeX directly for
.tex files
- Simple plain-text documents — Markdown is simpler
- Spreadsheet / tabular data output — use CSV or Excel tools
- Interactive web pages — use HTML/CSS directly (Typst HTML export available via
--features html but limited)
Reference Documentation
Read these files on demand (not all at once):
| Reference |
Path |
Content |
| CLI Reference |
references/typst-cli-reference.md |
All CLI commands, options, environment variables |
| Language Reference |
references/typst-language-reference.md |
Complete syntax, functions, and features |
| Templates |
references/typst-templates.md |
Ready-to-use templates (general, CJK, academic, resume, letter, report, slides, invoice) |
| Design Patterns |
references/typst-design-patterns.md |
Advanced patterns (themes, layouts, components, PDF capabilities) |
Output Formats
| Format |
Extension |
Notes |
| PDF |
.pdf |
Default. Supports PDF/A standards and tagged PDF. |
| PNG |
.png |
One image per page. Use --ppi for resolution (default 144). |
| SVG |
.svg |
One file per page. Vector graphics. |
| HTML |
.html |
Experimental. Use --features html. |
1---2name: typst3description: Generate professional PDF documents using the Typst typesetting system. Use when the user asks to create a PDF, write a document, generate a report, typeset a paper, build a presentation, or make a resume / CV / cover letter / letter / invoice / thesis / handout / poster — even when they do not say "Typst" explicitly. Especially trigger when the user mentions one-page CV, two-column resume, academic paper with bibliography, or any CJK (Chinese / Japanese / Korean) document.4---56# Typst Document Generation Skill78> **Trigger me when** the user wants any of: PDF · CV · résumé · cover letter · academic paper · report · invoice · slides · poster · 简历 · 学术论文 · 报告 · 发票 · 幻灯片 · Typst — even if they did not say "Typst" explicitly.910You are an expert Typst typesetter. Generate professional PDF, PNG, SVG, or HTML documents using Typst.1112## Decision Tree — pick a template before writing1314Ask, in this order, before writing any `.typ`:15161. **What is the artefact?**17 - Resume / CV → `references/typst-templates.md` § Simple Resume or Typographic Resume18 - Cover letter / formal letter → § Letter19 - Academic / research paper → § Academic Paper (two-column, abstract, bibliography)20 - Internal report / whitepaper → § Technical Report21 - Slide deck → § Presentation22 - Bill / receipt → § Invoice23 - Anything else → § General Document24252. **Is the language CJK (Chinese / Japanese / Korean)?**26 If yes, **always** layer the CJK font setup from § CJK Document on top of the chosen template — missing this is the #1 source of "tofu" (□) bugs.27283. **Does the user have a JSON / CSV data source?**29 If yes, generate a `.typ` that calls `#let data = json("path.json")` (or `csv(...)`) and loops over it — do **not** hardcode values from the data into the template.3031## Quick Reference3233| Task | Code / Command |34|------|---------------|35| Compile to PDF | `typst compile doc.typ` |36| Compile to PNG | `typst compile doc.typ --format png --ppi 300` |37| Compile & open | `typst compile doc.typ --open` |38| Set page | `#set page(paper: "a4", margin: 2.5cm)` |39| Set font | `#set text(font: "Linux Libertine", size: 11pt)` |40| CJK font | `#set text(lang: "zh", font: ("Source Han Serif SC", "SimSun", "Microsoft YaHei"))` |41| Heading | `= Title` / `== Subtitle` / `=== Sub-subtitle` |42| Math | `$ integral_0^infinity e^(-x^2) dif x = sqrt(pi) / 2 $` |43| Import package | `#import "@preview/cetz:0.3.4": canvas, draw` |44| Load data | `#let data = json("data.json")` or `csv("data.csv")` |45| Evaluate expression | `typst eval "1 + 2"` |46| Conditional format | `#if target() == "html" { ... } else { ... }` |47| List fonts | `typst fonts` |4849## Workflow5051### 1. Verify the environment5253```bash54typst --version55```5657For a deeper check (CJK fonts available, write permissions, version ≥ 0.14), run the bundled script from this skill's directory:5859```bash60bash scripts/verify-typst.sh61```6263If `typst` is not installed:6465- Windows: `winget install --id Typst.Typst`66- macOS: `brew install typst`67- Any platform with Rust: `cargo install --locked typst-cli`6869### 2. Create the `.typ` source file7071- Use the Decision Tree above to pick a template from `references/typst-templates.md`72- Consult `references/typst-language-reference.md` for syntax73- For advanced layouts, see `references/typst-design-patterns.md`74- Write the `.typ` file to the user's desired location7576### 3. Compile to output7778```bash79typst compile document.typ # PDF (default)80typst compile document.typ --format png --ppi 300 # High-res PNG81typst compile document.typ output.svg # SVG82```8384See `references/typst-cli-reference.md` for all options.8586### 4. Iterate8788Read compilation errors, consult the Recovery Recipes below, fix the `.typ` file, and recompile.8990## Gotchas / Common Mistakes9192| Mistake | Fix |93|---------|-----|94| CJK glyphs missing or tofu (□) | Set `lang` AND provide a CJK font fallback chain: `#set text(lang: "zh", font: ("Source Han Serif SC", "SimSun"))` |95| Windows path errors in `#image()` / `#include()` | Use forward slashes: `image("images/photo.jpg")`, not backslashes |96| Font not found | Run `typst fonts` to list available fonts; bundle custom fonts with `--font-path ./fonts` |97| `context` errors in Typst v0.14+ | Accessing `counter()`, `state()`, or `text.fill` requires wrapping in a `context` block |98| `show` rules leaking to other sections | Wrap scoped show rules in a block `{ ... }` to limit their effect |99| Multi-page PNG/SVG produces single file | Use `{p}` placeholder in output: `typst compile doc.typ "page-{p}.png"` |100| Package download fails | First compile with a new `@preview` package requires internet; check `--package-cache-path` |101| Paragraph spacing looks wrong | Set `#set par(justify: true, leading: 0.8em)` explicitly; defaults vary |102| Math script styles not working | Use `scr()`, `cal()`, `frak()`, `bb()` — not LaTeX `\mathscr`, `\mathcal` |103| `typst compile` works locally but the PDF is blank from a Vercel / serverless function | The Vercel runtime does **not** include the Typst CLI. Either ship a static prebuilt binary in the deploy bundle (`vercel.json` `includeFiles`) or call a separate compile service (Fly.io / Railway). See `references/typst-design-patterns.md` § Serverless. |104105## Recovery Recipes106107When `typst compile` fails, paste stderr's first line into this lookup before guessing:108109| stderr starts with | Most likely cause | First thing to try |110|--------------------|-------------------|--------------------|111| `error: file not found (...) image(...)` | wrong relative path | `cd` to the `.typ` file's directory; use forward slashes |112| `error: unknown variable: <name>` | typo or missing `#let <name>` | grep the file for the symbol; check that imports use the right alias |113| `error: failed to load package` | offline / firewall blocks `@preview` | retry with internet; or vendor the package locally and import by path |114| `error: cannot apply fill to ... (context error)` | v0.14 introspection requires `context` | wrap the access in `context { ... }` |115| `error: type mismatch: expected ..., found ...` | passed wrong shape from JSON to a function | log the data with `#repr(data)` once, inspect, then narrow the access |116117## When NOT to use118119- **Existing LaTeX projects** — use LaTeX directly for `.tex` files120- **Simple plain-text documents** — Markdown is simpler121- **Spreadsheet / tabular data output** — use CSV or Excel tools122- **Interactive web pages** — use HTML/CSS directly (Typst HTML export available via `--features html` but limited)123124## Reference Documentation125126Read these files on demand (not all at once):127128| Reference | Path | Content |129|-----------|------|---------|130| CLI Reference | `references/typst-cli-reference.md` | All CLI commands, options, environment variables |131| Language Reference | `references/typst-language-reference.md` | Complete syntax, functions, and features |132| Templates | `references/typst-templates.md` | Ready-to-use templates (general, CJK, academic, resume, letter, report, slides, invoice) |133| Design Patterns | `references/typst-design-patterns.md` | Advanced patterns (themes, layouts, components, PDF capabilities) |134135## Output Formats136137| Format | Extension | Notes |138|--------|-----------|-------|139| PDF | `.pdf` | Default. Supports PDF/A standards and tagged PDF. |140| PNG | `.png` | One image per page. Use `--ppi` for resolution (default 144). |141| SVG | `.svg` | One file per page. Vector graphics. |142| HTML | `.html` | Experimental. Use `--features html`. |
ChanMeng666