# Typst > 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. Use when this capability is needed. - Skill: `tomevault-io/typst-2` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/typst-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/typst-2/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/typst-2 --- # 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/.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 `