# Calligrapher

Claude Code skills for the [Typst](https://typst.app/) programming language and compiler CLI.

Typst is a markup-based typesetting system designed to be a modern alternative to LaTeX - powerful enough for scientific papers and technical documents, yet easy to learn and fast to compile.

## What is Typst?

[Typst](https://github.com/typst/typst) allows you to:

- Write documents using intuitive markup syntax
- Create beautiful PDFs, PNGs, SVGs, and HTML
- Use scripting for dynamic content generation
- Style documents with a flexible system
- Work with math equations, tables, figures, and citations
- Import data from JSON, CSV, YAML, TOML, and XML

## Installation

### Install Typst CLI

**macOS (Homebrew):**
```bash
brew install typst
```

**Windows (Winget):**
```powershell
winget install --id Typst.Typst
```

**Linux:**
```bash
# Via Snap
snap install typst

# Or check your distribution's package manager
# See: https://repology.org/project/typst/versions
```

**From source (Cargo):**
```bash
cargo install --locked typst-cli
```

**Pre-built binaries:**

Download from [GitHub Releases](https://github.com/typst/typst/releases/)

### Verify Installation

```bash
typst --version
```

## Claude Code Skills

This repository provides a comprehensive Claude Code skill for the Typst compiler CLI.

### Installing the Skill

The skill is located in the `skills/typst/` directory. To use it with Claude Code, you have two options:

#### Option 1: Symlink (Recommended)

Create a symbolic link to the skill directory:

```bash
# Create the skills directory if it doesn't exist
mkdir -p ~/.claude/skills

# Symlink the typst skill
ln -s /path/to/calligrapher/skills/typst ~/.claude/skills/typst
```

For example:
```bash
ln -s ~/repos/ajet-industries/calligrapher/skills/typst ~/.claude/skills/typst
```

#### Option 2: Copy Directory

Copy the skill directory to your Claude Code skills folder:

```bash
# Create the skills directory if it doesn't exist
mkdir -p ~/.claude/skills

# Copy the typst skill
cp -r /path/to/calligrapher/skills/typst ~/.claude/skills/typst
```

For example:
```bash
cp -r ~/repos/ajet-industries/calligrapher/skills/typst ~/.claude/skills/typst
```

### Using the Skill

Once installed, you can invoke the skill in Claude Code with:

```
/typst
```

Or simply ask Claude to perform Typst operations:

- "Compile my document to PDF"
- "Watch this file for changes"
- "List available fonts"
- "Create a new Typst document"

## Common Typst Commands

### Compilation

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

# Compile to PNG
typst compile document.typ document.png

# Compile to SVG
typst compile document.typ document.svg

# Specify output path
typst compile document.typ output/document.pdf
```

### Watch Mode

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

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

### Fonts

```bash
# List available fonts
typst fonts

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

### Help

```bash
# General help
typst help

# Command-specific help
typst compile --help
typst watch --help
```

## Documentation

- **Typst Reference**: https://typst.app/docs/reference/
- **Typst Tutorial**: https://typst.app/docs/tutorial/
- **GitHub Repository**: https://github.com/typst/typst
- **Skill Documentation**: See `skills/typst/SKILL.md` for Claude Code integration details
- **Examples**: See `skills/typst/examples.md` for usage examples

## Repository Structure

```
calligrapher/
├── skills/
│   └── typst/
│       ├── SKILL.md      # Claude Code skill definition
│       └── examples.md   # Usage examples
├── README.md             # This file
└── CLAUDE.md             # Instructions for Claude Code
```

## Why "Calligrapher"?

Calligraphy is the art of beautiful writing - the careful crafting of letterforms with skill and precision. Just as a calligrapher transforms simple text into visual art, Typst transforms markup into beautifully typeset documents.

This project aims to help you master the art of document creation with Typst through Claude Code, making the craft of typesetting accessible and efficient.

## License

MIT

## Contributing

Contributions welcome! Feel free to:
- Add new examples to the skill documentation
- Improve existing documentation
- Add new workflows
- Report issues

## Links

- [Typst](https://typst.app/)
- [Typst GitHub](https://github.com/typst/typst)
- [Typst Documentation](https://typst.app/docs/)
- [Claude Code](https://claude.ai/code)