Typst Syntax & Ecosystem Guide

Use this skill when writing or editing Typst (.typ) files.

Current Typst version: 0.14.x (Dec 2025)

Documentation

• •Official Reference: https://typst.app/docs/reference/
• •Package Registry: https://typst.app/universe/
• •Tutorial: https://typst.app/docs/tutorial/
• •Changelog: https://typst.app/docs/changelog/

Reference Files

• •references/math-pitfalls.md - Currency in math, adjacent letters, commas, angle brackets
• •references/layout-patterns.md - Compact setup, spacing, nested boxes, color themes, curve function
• •references/symbols.md - sym.* arrows, common symbols, math/logic
• •references/packages.md - Popular packages with import syntax
• •references/common-patterns.md - Tables, templates, bibliography, safe patterns, quick reference

What's New in 0.13-0.14

Deprecated Functions

• •path -> use curve instead (see layout-patterns.md)
• •pdf.embed -> use pdf.attach instead
• •image.decode -> pass bytes directly to image
• •polylux:0.3.1 is incompatible with Typst 0.14 -> use touying instead

Core Syntax

Arrays and Dictionaries

Typst uses parentheses for both (not square brackets like Python/JS):

// Arrays - use ()
let colors = (red, green, blue)
let first = colors.at(0)        // NOT colors[0]
let length = colors.len()

// Dictionaries - use () with colons
let person = (name: "Alice", age: 30)
let name = person.name          // or person.at("name")

// WRONG - common mistakes
let arr = [1, 2, 3]             // This is a content block, not array!
let item = arr[0]               // Wrong access syntax

Content Blocks vs Code Blocks

// Content blocks [] - for markup/text
[This is *bold* and _italic_ text]

// Code blocks {} - for logic
{
  let x = 5
  if x > 3 { "big" } else { "small" }
}

// In markup mode, use # to switch to code
This is text. #let x = 5 Now x is #x.

The # Prefix

In markup context, # switches to code mode:

// Markup mode (default at start of file)
Hello world.
#let name = "Alice"           // # needed for code
My name is #name.             // # needed to evaluate

// In code block, # not needed
#{
  let x = 5                   // No # needed inside {}
  x + 3
}

Special Characters

Common Errors

See references/math-pitfalls.md for full math mode pitfalls.

CLI Commands

typst compile document.typ                     # Compile to PDF
typst watch document.typ                       # Watch and recompile
typst compile document.typ out.pdf --pages 1-5 # Specific pages
typst fonts                                    # List available fonts

Images & Visual Tools

When a Typst document needs an image, follow this priority order:

1. •Can Typst draw it natively (table, grid, box, simple flowchart)? → Typst native
2. •Is it a real photograph, logo, or existing graphic? → /image-search
3. •Is it a mind map or hierarchical overview? → /mindmap
4. •Is it a data-driven chart needing numerical precision? → matplotlib/Python
5. •Otherwise (conceptual illustration, metaphor, artistic visual) → /nano-banana

Full routing reference:

Auto-invoke rule: When the user requests a conceptual diagram, illustration, or visual that cannot be reasonably drawn with Typst native tools or packages, automatically run /nano-banana to generate it via Gemini. Pass --typst to get ready-to-paste #figure(image(...)) code. Do NOT ask the user whether to use /nano-banana — just use it.

Do NOT use /nano-banana when the image needs precise text labels (Gemini often misspells), or when the visual is a structured layout that Typst handles natively (boxes, tables, grids).

Accessibility (Typst 0.14+): Always add alt: to embedded images:

#figure(image("path.png", alt: "Description for screen readers"), caption: [...])

Example:

/nano-banana "three-legged stool analogy for risk parity" --dir images --width 80%

Mind Map Generation (/mindmap)

When a Typst document needs a mind map or concept overview:

Auto-invoke rule: When the user requests a mind map, concept map, topic tree, or overview diagram for a Typst document, automatically run /mindmap to generate it. Pass --typst to get ready-to-paste #figure(image(...)) code. Do NOT ask the user whether to use /mindmap — just use it.

Example:

/mindmap "Portfolio Theory" --typst --caption "Portfolio Theory Overview"

Default theme (academic) uses blue/orange colors matching the Typst study materials palette. Use --theme latte for a pastel alternative or --theme dark for dark backgrounds.

Web Image Search (/image-search)

When a Typst document needs real-world images — company logos, product photos, charts, or any existing graphic from the web:

Auto-invoke rule: When the user needs company logos, real-world photos, or web graphics for a Typst document, automatically run /image-search with --typst. Do NOT ask the user whether to use /image-search — just use it.

Do NOT use /image-search when the user needs AI-generated or conceptual images (use /nano-banana instead), or when the visual can be drawn natively in Typst.

Examples:

/image-search --logo "Goldman Sachs" --width 40%
/image-search "electric vehicle charging station" --size large
/image-search --stock "sustainable energy" -n 2

Debugging

1. •Compile incrementally — Don't write 200 lines then compile
2. •Check line numbers — Errors show exact location
3. •Watch mode — Auto-recompile on save:
   bash

   typst watch file.typ file.pdf
   

4. •Isolate problems — Comment out sections with /* ... */