calligrapher/CLAUDE.md

# 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

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

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

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

### Font Management

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

```bash
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:**
```typst
#set page(paper: "a4")
#set text(font: "New Computer Modern", size: 11pt)

= Title

This is a paragraph.

== Section

More content here.
```

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

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