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

5.0 KiB

Raw Permalink Blame History

CLAUDE.md

This file provides guidance to Claude Code when working with the Calligrapher repository.

Repository Purpose

This repository provides Claude Code skills for working with Typst, a modern typesetting system. The skills enable seamless document compilation, watching, and management directly through Claude Code conversations.

Repository Structure

skills/typst/SKILL.md - Main Claude Code skill definition for Typst
skills/typst/examples.md - Usage examples
README.md - User-facing documentation
CLAUDE.md - This file (Claude Code instructions)

Typst Overview

Typst is a markup-based typesetting system that competes with LaTeX while being more approachable and faster. It supports:

Document Compilation: Generate PDF, PNG, SVG, or HTML from .typ files
Watch Mode: Auto-recompile on file changes
Scripting: Full programming capabilities for dynamic content
Styling: Powerful and flexible document styling
Math: LaTeX-like math equation support
Data Import: Load JSON, CSV, YAML, TOML, and XML

Key Commands

Compilation

# Compile to PDF (default output)
typst compile document.typ

# Compile to specific format
typst compile document.typ output.png
typst compile document.typ output.svg

# With explicit output path
typst compile document.typ output/document.pdf

# With custom font path
typst compile --font-path ./fonts document.typ

Watch Mode

# Watch and recompile on changes
typst watch document.typ

# Watch with custom output
typst watch document.typ output.pdf

Font Management

# List available fonts
typst fonts

# Custom font paths
typst compile --font-path ./fonts document.typ

# Or via environment variable
export TYPST_FONT_PATHS=/path/to/fonts
typst compile document.typ

Help

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

Important Notes for Claude Code

File Extensions

Typst source files use the .typ extension
Default output is PDF
Output format is inferred from the output filename extension

Working Directory

Typst resolves relative paths from the directory containing the source file. When helping users:

Note the current working directory
Use absolute paths when needed
Ensure output directories exist before compilation

Common Patterns

Basic Document Structure:

#set page(paper: "a4")
#set text(font: "New Computer Modern", size: 11pt)

= Title

This is a paragraph.

== Section

More content here.

Math Equations:

The quadratic formula is $x = (-b plus.minus sqrt(b^2 - 4 a c)) / (2 a)$.

Display equation:
$ sum_(k=0)^n k = (n(n+1)) / 2 $

Code Blocks:

```rust
fn main() {
    println!("Hello, world!");
}


**Tables:**
```typst
#table(
  columns: (auto, auto),
  [Name], [Age],
  [Alice], [30],
  [Bob], [25],
)

Error Handling

Common compilation errors:

File not found: Check paths are correct and files exist
Font not found: Use typst fonts to list available fonts, or specify --font-path
Syntax errors: Typst provides helpful error messages with line/column numbers
Package errors: Ensure required packages are available

Output Formats

Extension	Format	Notes
`.pdf`	PDF	Default, best for documents
`.png`	PNG	Rasterized, specify page with `{n}`
`.svg`	SVG	Vector, good for web

For multi-page documents to PNG:

typst compile document.typ 'output-{n}.png'

Best Practices

Verify typst is installed before running commands: typst --version
Use watch mode during development for rapid iteration
Specify output paths to keep source and output organized
Check font availability with typst fonts before using custom fonts
Use absolute paths when working directory might be ambiguous

Skill Usage

The /typst skill can be invoked explicitly, but Claude Code should also recognize Typst-related requests naturally:

"Compile this document"
"Watch my thesis.typ file"
"What fonts are available?"
"Convert to PNG"

Claude should automatically use the typst skill when appropriate for document operations.

Extending the Skills

When adding new examples or workflows:

Test the commands manually first
Add to the appropriate section in skills/typst/SKILL.md
Include both basic and advanced examples
Document any prerequisites or gotchas
Update this CLAUDE.md if needed

Common Pitfalls

Missing output directory: Typst won't create directories; ensure they exist
Font path issues: Use --font-path or TYPST_FONT_PATHS for custom fonts
Relative path confusion: Paths resolve from source file location
Format inference: Output format comes from filename extension, not content

Resources

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

5.0 KiB Raw Permalink Blame History