2026-01-12 12:37:52 -05:00

6.6 KiB

Raw Permalink Blame History

name	description
typst	Compile Typst documents to PDF, PNG, SVG, and HTML. Watch files for changes and manage fonts. A modern alternative to LaTeX for typesetting.

Typst CLI

When to Use This Skill

Use this skill when you need to:

Compile Typst documents to PDF, PNG, SVG, or HTML
Watch files for changes and auto-recompile
List available fonts on the system
Help write Typst markup for documents, papers, or reports
Debug compilation errors in Typst source files
Set up custom font paths for document compilation

How It Works

The typst CLI compiles .typ source files into output documents. It supports incremental compilation for fast rebuilds and watch mode for development workflows.

Prerequisites

Verify Typst is installed:

typst --version

If not installed, see installation options:

macOS: brew install typst
Windows: winget install --id Typst.Typst
Linux: snap install typst or check your package manager
Cargo: cargo install --locked typst-cli

Common Operations

Compile Documents

Compile to PDF (default):

typst compile document.typ

Compile to specific format:

typst compile document.typ output.png
typst compile document.typ output.svg

Compile to specific output path:

typst compile document.typ output/document.pdf

Compile multi-page document to PNG:

typst compile document.typ 'pages/page-{n}.png'

Watch Mode

Watch and recompile on changes:

typst watch document.typ

Watch with custom output:

typst watch document.typ output.pdf

Watch with specific format:

typst watch document.typ output.png

Font Management

List available fonts:

typst fonts

Compile with custom font path:

typst compile --font-path ./fonts document.typ

Multiple font paths:

typst compile --font-path ./fonts --font-path ~/.fonts document.typ

Using environment variable:

export TYPST_FONT_PATHS=/path/to/fonts:/another/path
typst compile document.typ

Help and Documentation

General help:

typst help

Command-specific help:

typst compile --help
typst watch --help
typst fonts --help

Typst Markup Basics

Document Structure

// Set page and text defaults
#set page(paper: "a4", margin: 2cm)
#set text(font: "New Computer Modern", size: 11pt)

// Title
#align(center)[
  #text(size: 20pt, weight: "bold")[Document Title]
]

= Introduction

This is the first section.

== Subsection

Content with *bold* and _italic_ text.

- Bullet point
- Another point
  - Nested point

+ Numbered item
+ Another numbered item

Math Equations

Inline math:

The formula $E = m c^2$ describes mass-energy equivalence.

Display math:

$ integral_0^infinity e^(-x^2) dif x = sqrt(pi) / 2 $

Aligned equations:

$ x &= a + b \
  y &= c + d $

Tables

#table(
  columns: (1fr, 1fr, 1fr),
  align: center,
  table.header([Name], [Value], [Unit]),
  [Mass], [5.0], [kg],
  [Velocity], [10], [m/s],
  [Energy], [250], [J],
)

Figures and Images

#figure(
  image("diagram.png", width: 80%),
  caption: [System architecture diagram],
)

Code Blocks

```python
def hello():
    print("Hello, world!")
```

Bibliography

// At the end of document
#bibliography("refs.bib")

Output Formats

Extension	Format	Use Case
`.pdf`	PDF	Documents, papers (default)
`.png`	PNG	Images, thumbnails
`.svg`	SVG	Web, scalable graphics

Format-Specific Options

PNG resolution:

typst compile --ppi 300 document.typ output.png

Error Handling

Common Errors

File not found:

error: file not found
  ┌─ document.typ:5:1
  │
5 │ #include "missing.typ"
  │ ^^^^^^^^^^^^^^^^^^^^^^

Solution: Check file paths are correct and files exist.

Font not found:

error: unknown font family

Solution: Use typst fonts to list available fonts, or add --font-path.

Syntax error:

error: expected expression
  ┌─ document.typ:10:5
  │
10│     #let x =
  │             ^

Solution: Check Typst syntax at the indicated line/column.

Debugging Tips

Read error messages carefully - Typst provides file, line, and column
Check the Typst reference: https://typst.app/docs/reference/
Verify all included files exist
Use typst fonts to check font availability

Advanced Usage

Command-Line Options

Specify root directory:

typst compile --root /project document.typ

Add input variables:

typst compile --input version=1.0 document.typ

Diagnostic format:

typst compile --diagnostic-format short document.typ

Environment Variables

TYPST_FONT_PATHS - Additional font directories (colon-separated)
TYPST_ROOT - Root directory for file resolution

Scripting Integration

Check if compilation succeeds:

if typst compile document.typ; then
    echo "Compilation successful"
else
    echo "Compilation failed"
fi

Batch compilation:

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

Typical Workflows

Writing a Paper

Create paper.typ with document structure
Start watch mode: typst watch paper.typ
Edit source file - output updates automatically
Add bibliography: #bibliography("refs.bib")
Final compile: typst compile paper.typ

Creating Slides

#import "@preview/polylux:0.3.1": *

#set page(paper: "presentation-16-9")

#polylux-slide[
  = Slide Title

  Content here
]

Generating Images

# Single page to PNG
typst compile diagram.typ diagram.png

# High-resolution
typst compile --ppi 600 diagram.typ diagram.png

# Multiple pages
typst compile slides.typ 'slide-{n}.png'

Important Notes

File extension matters: Output format is inferred from the output filename
Incremental compilation: Typst caches intermediate results for speed
Watch mode: Ideal for development; use Ctrl+C to stop
Relative paths: Resolved from the source file's directory
Package system: Import packages with #import "@preview/package:version"

Getting Help

typst help              # General help
typst compile --help    # Compile command help
typst watch --help      # Watch command help
typst fonts --help      # Fonts command help

Resources

Reference: https://typst.app/docs/reference/
Tutorial: https://typst.app/docs/tutorial/
Packages: https://typst.app/universe/
GitHub: https://github.com/typst/typst

6.6 KiB Raw Permalink Blame History