---
name: typst
description: 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:**
```bash
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):**
```bash
typst compile document.typ
```

**Compile to specific format:**
```bash
typst compile document.typ output.png
typst compile document.typ output.svg
```

**Compile to specific output path:**
```bash
typst compile document.typ output/document.pdf
```

**Compile multi-page document to PNG:**
```bash
typst compile document.typ 'pages/page-{n}.png'
```

### Watch Mode

**Watch and recompile on changes:**
```bash
typst watch document.typ
```

**Watch with custom output:**
```bash
typst watch document.typ output.pdf
```

**Watch with specific format:**
```bash
typst watch document.typ output.png
```

### Font Management

**List available fonts:**
```bash
typst fonts
```

**Compile with custom font path:**
```bash
typst compile --font-path ./fonts document.typ
```

**Multiple font paths:**
```bash
typst compile --font-path ./fonts --font-path ~/.fonts document.typ
```

**Using environment variable:**
```bash
export TYPST_FONT_PATHS=/path/to/fonts:/another/path
typst compile document.typ
```

### Help and Documentation

**General help:**
```bash
typst help
```

**Command-specific help:**
```bash
typst compile --help
typst watch --help
typst fonts --help
```

## Typst Markup Basics

### Document Structure

```typst
// 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:**
```typst
The formula $E = m c^2$ describes mass-energy equivalence.
```

**Display math:**
```typst
$ integral_0^infinity e^(-x^2) dif x = sqrt(pi) / 2 $
```

**Aligned equations:**
```typst
$ x &= a + b \
  y &= c + d $
```

### Tables

```typst
#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

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

### Code Blocks

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

### Bibliography

```typst
// 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:**
```bash
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

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

## Advanced Usage

### Command-Line Options

**Specify root directory:**
```bash
typst compile --root /project document.typ
```

**Add input variables:**
```bash
typst compile --input version=1.0 document.typ
```

**Diagnostic format:**
```bash
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:**
```bash
if typst compile document.typ; then
    echo "Compilation successful"
else
    echo "Compilation failed"
fi
```

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

## Typical Workflows

### Writing a Paper

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

### Creating Slides

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

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

#polylux-slide[
  = Slide Title

  Content here
]
```

### Generating Images

```bash
# 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

```bash
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