typst

name	typst
description	Syntax guide and ecosystem reference for writing Typst (.typ) files. Use this skill when writing, editing, or debugging Typst documents. Covers core syntax, common errors, packages, and best practices.
license	MIT

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):

Need	Tool
Flowcharts, trees, ER, state diagrams	fletcher
Sequence diagrams	chronos
Gantt charts	timeliney
Linear timelines	herodot

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

Need	Tool
Simple charts (< 3 series, < 20 pts)	cetz-plot (Typst native, qk-cycle colors)
Statistical plots (violin, kde, pair, heatmap)	matplotlib + seaborn (use(), SVG)
Grammar-of-graphics / faceted plots	plotnine (theme_qk(), SVG)
Complex charts (4+ series, annotations)	matplotlib (full API, SVG)

Images & layout:

Need	Tool
Tables, boxes, grids	Typst native
Mind maps	/mindmap (auto-invoke)
Conceptual illustrations	gemini-generate-image MCP (auto-invoke)
Real photos, logos	/image-search (auto-invoke)

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.

Content pattern	Visual to add	Tool
Comparison grids, attribute tables	Styled table	Typst native
Callout boxes, styled layouts	rect() / block()	Typst native
Sequential steps, decision logic	Flowchart / decision tree	fletcher
Process with inputs/outputs	Workflow diagram	fletcher
System architecture, ER diagrams	Block / entity diagram	fletcher
Hierarchy or taxonomy	Tree diagram	fletcher or /mindmap
Topic overview, concept map	Mind map	/mindmap
Request-response, API flows	Sequence diagram	chronos
Project schedule, phases	Gantt chart	timeliney
Historical events, evolution	Timeline	herodot or timeliney
Simple data chart (< 3 series, < 20 pts)	Line/bar/scatter chart	cetz-plot (Typst native)
Statistical/complex chart	Violin/kde/heatmap/faceted chart	matplotlib+seaborn or plotnine
Company logo, brand mark	Logo image	/image-search --logo
Real-world photograph	Photo	/image-search
Concept with analogy, metaphor	AI illustration	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:

Content pattern	Use instead
Warning paragraph	warning[...]
Key point / takeaway	keypoint[...]
Tip or best practice	tip[...]
Common mistake / trap	trap[...]
Step-by-step procedure	step-box("Title", [...])
Key equation / formula	formula-box("Title", [...])
KPI or metric highlight	stat-card("value", "label")
Frequency indicator	freq-badge("HIGH") / freq-badge("MEDIUM") / freq-badge("LOW")
MCQ answer explanation	answerbox("A", "why", "trap", "concept")
Analogy / intuition	analogy[...]
"Why this matters"	whycare[...]

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

If this fails...	Try...
gemini-generate-image MCP	Placeholder #rect(width: 100%, height: 4cm, fill: luma(240))[Image placeholder]
/image-search	gemini-generate-image MCP with descriptive prompt
/mindmap	fletcher tree diagram
matplotlib	Check .venv → uv venv .venv.nosync && ln -s .venv.nosync .venv
typst compile	Isolate with /* ... */, compile incrementally

Reference File Index

When you need...	Read...
Syntax, errors, special chars	references/quick-ref.md
@local/qk:2.1.0 API	references/component-library.md
Visual tool details, examples, fallbacks	references/tool-routing.md
Document preambles	references/templates.md
Table patterns, show rules, large docs	references/common-patterns.md
Page layout, spacing, figures, curves	references/layout-patterns.md
Math mode traps	references/math-pitfalls.md
Package imports	references/packages.md
Touying presentations (themes, slides, speaker notes)	references/touying-guide.md
Visual verification (PNG rendering, spot-checks)	references/visual-verification.md
Quality gates, rubrics, dispatch table	references/quality-gates.md
Data-driven generation (JSON, CSV, batch, variants)	references/data-driven.md
sym.* symbols	references/symbols.md

Version Notes (0.13–0.14)

Feature	Ver	Description
Tagged PDFs, PDF/UA-1	0.14	Accessible PDFs by default
figure.alt / image(alt:)	0.14	Alt text for screen readers
pdf.attach	0.14	Attach files (replaces pdf.embed)
PDF as image format	0.14	image("file.pdf")
Multiple table headers	0.14	Hierarchical headers repeat across pages
curve function	0.13	Bezier drawing (replaces path)

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

Font	Style	Notes
New Computer Modern	Academic serif	Default; bundled with Typst
Georgia	Readable serif	Safe on macOS
Helvetica Neue	Clean sans-serif	macOS only

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