ajet/calligrapher
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
calligrapher/CLAUDE.md
Adam Jeniski 5f5bae8694 init commit
2026-01-12 12:37:52 -05:00

5.0 KiB
Raw 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:

  1. Note the current working directory
  2. Use absolute paths when needed
  3. 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

  1. Verify typst is installed before running commands: typst --version
  2. Use watch mode during development for rapid iteration
  3. Specify output paths to keep source and output organized
  4. Check font availability with typst fonts before using custom fonts
  5. 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:

  1. Test the commands manually first
  2. Add to the appropriate section in skills/typst/SKILL.md
  3. Include both basic and advanced examples
  4. Document any prerequisites or gotchas
  5. 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