Typst

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:

1. 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

1. 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.

1. 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: | typo or missing #let | 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. |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ChanMeng666
• Source: ChanMeng666/typst-claude-skill
• License: MIT

Install and usage instructions live in the source repository linked above.