Typst Skill

Current version: Typst 0.14.2 (Dec 2025)

Smart Defaults

If you know nothing else, follow these rules:

1. Always import @local/qk:2.1.0 — #import "@local/qk:2.1.0": *
2. Always use qk-doc or qk-report preset (unless user specifies custom)
3. Always use touying for presentations (not raw page dimensions) — see references/touying-guide.md
4. Always #set figure(placement: auto) — prevents blank half-pages
5. Always add alt: to images — image("path.png", alt: "description")
6. Always escape $ in content — scan for bare $ before compiling
7. Default fonts: Libertinus Serif (body), Inter (headings), New Computer Modern Math (math), Fira Code (code)
8. Default compile: typst compile --root .. Source/<file>.typ
9. When in doubt about template: Study Guide
10. When in doubt about visual tool: diagrams → fletcher; charts → see decision tree (simple → cetz-plot, statistical → matplotlib+seaborn, grammar → plotnine, complex → matplotlib)
11. Always scan project for existing .typ files and match their style (fonts, colors, qk preset) unless user specifies otherwise

New Document Decision Tree

User request → scan for keywords:
  "resume/CV/job"           → CV / Résumé template
  "slides/presentation"     → Presentation (touying — metropolis default)
  "lecture/class/academic"   → Academic Lecture (touying — university theme)
  "essay/thesis/paper"      → Essay
  "report/brief/client"     → Business Report
  "research/analysis"       → Research Report
  "study guide/revision"    → Study Guide
  "reference/glossary"                      → Annotated Reference
  "cheatsheet/reference card/formula sheet" → Cheatsheet template
  "exam/problem set/homework"              → Exam template
  "flashcard/Q&A/quiz"                     → Flashcard template
  ambiguous?                → ask purpose + audience → pick template

Steps:

1. Auto-detect template from keywords above
2. Import @local/qk:2.1.0 at top
3. Use qk-doc or qk-report preset when applicable
4. Auto-select template. State choice in Phase 3 summary. User can re-invoke with explicit type override if wrong.
5. Build from references/templates.md
6. Custom styles are fine — templates are starting points, not constraints

Visual Tool Routing (compact)

Diagrams (always native Typst — NEVER Python):

Charts (generate SVG, embed with #figure(image(...))):

Images & layout:

Detail and examples in references/tool-routing.md.

Proactive Behaviors

Visual Auto-detection

When writing Typst documents, automatically identify content that benefits from visuals. Do NOT wait for the user to request them. Route by content type: diagrams → native Typst (fletcher/chronos/timeliney/herodot); charts → cetz-plot (simple) / matplotlib or plotnine (complex) — generate SVG, embed; images → /image-search / /mindmap / gemini-generate-image MCP.

See references/tool-routing.md for full examples, fallback chains, and auto-invoke rules.

Content Structure

• Suggest TOC (#outline()) at 4+ sections
• Suggest file split at 40+ pages — see references/common-patterns.md "Large Documents"
• Convert prose lists to tables when 3+ items with attributes

Component Library Auto-use

When writing content, automatically convert matching patterns to @local/qk:2.1.0 components:

Cross-referencing

Add <label> + @ref for recurring concepts across sections.

Accessibility (Typst 0.14+)

• alt: on all figures — image("path.png", alt: "description")
• Semantic heading hierarchy — don't skip levels
• table.header() for repeating headers — improves PDF/UA accessibility

Fallback Chains

Reference File Index

Version Notes (0.13–0.14)

Deprecated: path → curve · pdf.embed → pdf.attach · image.decode → pass bytes directly · polylux:0.3.1 → polylux:0.4.0 or touying

| touying 0.6.1 | 0.6 | Presentation framework — #show: theme.with(...) API (NOT the old register() pattern) |

CLI Commands

typst compile document.typ                     # Compile to PDF
typst compile document.typ --root ..           # Set project root
typst compile document.typ out.pdf --pages 1-5 # Specific pages
typst watch document.typ                       # Watch and recompile
typst fonts                                    # List available fonts
typst query doc.typ "heading.where(level: 1)"  # Query document structure

--root flag: When a .typ file uses #import or #image() with paths outside its directory, set --root to the project root.

Batch compile: for f in *.typ; do typst compile "$f"; done

Conventions

• Source files in Source/, compiled PDFs in PDFs/
• Compile with --root .. when .typ references parent directory assets
• For multi-file projects: main.typ + #include sections + shared lib.typ
• File naming: lowercase-kebab-case (e.g., portfolio-theory-guide.typ)

Fonts

Variable font warning: Apple system fonts (New York, SF Pro) are variable → "variable fonts are not currently supported." Install static .otf/.ttf versions or use alternatives.

CJK fallback: #set text(font: ("New Computer Modern", "Songti SC"))

Documentation

• Official Reference
• Package Registry
• Tutorial
• Changelog