202 lines
5.0 KiB
Markdown
202 lines
5.0 KiB
Markdown
# 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/
|