354 lines
6.6 KiB
Markdown
354 lines
6.6 KiB
Markdown
---
|
|
name: typst
|
|
description: Compile Typst documents to PDF, PNG, SVG, and HTML. Watch files for changes and manage fonts. A modern alternative to LaTeX for typesetting.
|
|
---
|
|
|
|
# Typst CLI
|
|
|
|
## When to Use This Skill
|
|
|
|
Use this skill when you need to:
|
|
- **Compile Typst documents** to PDF, PNG, SVG, or HTML
|
|
- **Watch files** for changes and auto-recompile
|
|
- **List available fonts** on the system
|
|
- **Help write Typst markup** for documents, papers, or reports
|
|
- **Debug compilation errors** in Typst source files
|
|
- **Set up custom font paths** for document compilation
|
|
|
|
## How It Works
|
|
|
|
The `typst` CLI compiles `.typ` source files into output documents. It supports incremental compilation for fast rebuilds and watch mode for development workflows.
|
|
|
|
## Prerequisites
|
|
|
|
**Verify Typst is installed:**
|
|
```bash
|
|
typst --version
|
|
```
|
|
|
|
If not installed, see installation options:
|
|
- macOS: `brew install typst`
|
|
- Windows: `winget install --id Typst.Typst`
|
|
- Linux: `snap install typst` or check your package manager
|
|
- Cargo: `cargo install --locked typst-cli`
|
|
|
|
## Common Operations
|
|
|
|
### Compile Documents
|
|
|
|
**Compile to PDF (default):**
|
|
```bash
|
|
typst compile document.typ
|
|
```
|
|
|
|
**Compile to specific format:**
|
|
```bash
|
|
typst compile document.typ output.png
|
|
typst compile document.typ output.svg
|
|
```
|
|
|
|
**Compile to specific output path:**
|
|
```bash
|
|
typst compile document.typ output/document.pdf
|
|
```
|
|
|
|
**Compile multi-page document to PNG:**
|
|
```bash
|
|
typst compile document.typ 'pages/page-{n}.png'
|
|
```
|
|
|
|
### Watch Mode
|
|
|
|
**Watch and recompile on changes:**
|
|
```bash
|
|
typst watch document.typ
|
|
```
|
|
|
|
**Watch with custom output:**
|
|
```bash
|
|
typst watch document.typ output.pdf
|
|
```
|
|
|
|
**Watch with specific format:**
|
|
```bash
|
|
typst watch document.typ output.png
|
|
```
|
|
|
|
### Font Management
|
|
|
|
**List available fonts:**
|
|
```bash
|
|
typst fonts
|
|
```
|
|
|
|
**Compile with custom font path:**
|
|
```bash
|
|
typst compile --font-path ./fonts document.typ
|
|
```
|
|
|
|
**Multiple font paths:**
|
|
```bash
|
|
typst compile --font-path ./fonts --font-path ~/.fonts document.typ
|
|
```
|
|
|
|
**Using environment variable:**
|
|
```bash
|
|
export TYPST_FONT_PATHS=/path/to/fonts:/another/path
|
|
typst compile document.typ
|
|
```
|
|
|
|
### Help and Documentation
|
|
|
|
**General help:**
|
|
```bash
|
|
typst help
|
|
```
|
|
|
|
**Command-specific help:**
|
|
```bash
|
|
typst compile --help
|
|
typst watch --help
|
|
typst fonts --help
|
|
```
|
|
|
|
## Typst Markup Basics
|
|
|
|
### Document Structure
|
|
|
|
```typst
|
|
// Set page and text defaults
|
|
#set page(paper: "a4", margin: 2cm)
|
|
#set text(font: "New Computer Modern", size: 11pt)
|
|
|
|
// Title
|
|
#align(center)[
|
|
#text(size: 20pt, weight: "bold")[Document Title]
|
|
]
|
|
|
|
= Introduction
|
|
|
|
This is the first section.
|
|
|
|
== Subsection
|
|
|
|
Content with *bold* and _italic_ text.
|
|
|
|
- Bullet point
|
|
- Another point
|
|
- Nested point
|
|
|
|
+ Numbered item
|
|
+ Another numbered item
|
|
```
|
|
|
|
### Math Equations
|
|
|
|
**Inline math:**
|
|
```typst
|
|
The formula $E = m c^2$ describes mass-energy equivalence.
|
|
```
|
|
|
|
**Display math:**
|
|
```typst
|
|
$ integral_0^infinity e^(-x^2) dif x = sqrt(pi) / 2 $
|
|
```
|
|
|
|
**Aligned equations:**
|
|
```typst
|
|
$ x &= a + b \
|
|
y &= c + d $
|
|
```
|
|
|
|
### Tables
|
|
|
|
```typst
|
|
#table(
|
|
columns: (1fr, 1fr, 1fr),
|
|
align: center,
|
|
table.header([Name], [Value], [Unit]),
|
|
[Mass], [5.0], [kg],
|
|
[Velocity], [10], [m/s],
|
|
[Energy], [250], [J],
|
|
)
|
|
```
|
|
|
|
### Figures and Images
|
|
|
|
```typst
|
|
#figure(
|
|
image("diagram.png", width: 80%),
|
|
caption: [System architecture diagram],
|
|
)
|
|
```
|
|
|
|
### Code Blocks
|
|
|
|
````typst
|
|
```python
|
|
def hello():
|
|
print("Hello, world!")
|
|
```
|
|
````
|
|
|
|
### Bibliography
|
|
|
|
```typst
|
|
// At the end of document
|
|
#bibliography("refs.bib")
|
|
```
|
|
|
|
## Output Formats
|
|
|
|
| Extension | Format | Use Case |
|
|
|-----------|--------|----------|
|
|
| `.pdf` | PDF | Documents, papers (default) |
|
|
| `.png` | PNG | Images, thumbnails |
|
|
| `.svg` | SVG | Web, scalable graphics |
|
|
|
|
### Format-Specific Options
|
|
|
|
**PNG resolution:**
|
|
```bash
|
|
typst compile --ppi 300 document.typ output.png
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
### Common Errors
|
|
|
|
**File not found:**
|
|
```
|
|
error: file not found
|
|
┌─ document.typ:5:1
|
|
│
|
|
5 │ #include "missing.typ"
|
|
│ ^^^^^^^^^^^^^^^^^^^^^^
|
|
```
|
|
Solution: Check file paths are correct and files exist.
|
|
|
|
**Font not found:**
|
|
```
|
|
error: unknown font family
|
|
```
|
|
Solution: Use `typst fonts` to list available fonts, or add `--font-path`.
|
|
|
|
**Syntax error:**
|
|
```
|
|
error: expected expression
|
|
┌─ document.typ:10:5
|
|
│
|
|
10│ #let x =
|
|
│ ^
|
|
```
|
|
Solution: Check Typst syntax at the indicated line/column.
|
|
|
|
### Debugging Tips
|
|
|
|
1. Read error messages carefully - Typst provides file, line, and column
|
|
2. Check the Typst reference: https://typst.app/docs/reference/
|
|
3. Verify all included files exist
|
|
4. Use `typst fonts` to check font availability
|
|
|
|
## Advanced Usage
|
|
|
|
### Command-Line Options
|
|
|
|
**Specify root directory:**
|
|
```bash
|
|
typst compile --root /project document.typ
|
|
```
|
|
|
|
**Add input variables:**
|
|
```bash
|
|
typst compile --input version=1.0 document.typ
|
|
```
|
|
|
|
**Diagnostic format:**
|
|
```bash
|
|
typst compile --diagnostic-format short document.typ
|
|
```
|
|
|
|
### Environment Variables
|
|
|
|
- `TYPST_FONT_PATHS` - Additional font directories (colon-separated)
|
|
- `TYPST_ROOT` - Root directory for file resolution
|
|
|
|
### Scripting Integration
|
|
|
|
**Check if compilation succeeds:**
|
|
```bash
|
|
if typst compile document.typ; then
|
|
echo "Compilation successful"
|
|
else
|
|
echo "Compilation failed"
|
|
fi
|
|
```
|
|
|
|
**Batch compilation:**
|
|
```bash
|
|
for f in *.typ; do
|
|
typst compile "$f"
|
|
done
|
|
```
|
|
|
|
## Typical Workflows
|
|
|
|
### Writing a Paper
|
|
|
|
1. Create `paper.typ` with document structure
|
|
2. Start watch mode: `typst watch paper.typ`
|
|
3. Edit source file - output updates automatically
|
|
4. Add bibliography: `#bibliography("refs.bib")`
|
|
5. Final compile: `typst compile paper.typ`
|
|
|
|
### Creating Slides
|
|
|
|
```typst
|
|
#import "@preview/polylux:0.3.1": *
|
|
|
|
#set page(paper: "presentation-16-9")
|
|
|
|
#polylux-slide[
|
|
= Slide Title
|
|
|
|
Content here
|
|
]
|
|
```
|
|
|
|
### Generating Images
|
|
|
|
```bash
|
|
# Single page to PNG
|
|
typst compile diagram.typ diagram.png
|
|
|
|
# High-resolution
|
|
typst compile --ppi 600 diagram.typ diagram.png
|
|
|
|
# Multiple pages
|
|
typst compile slides.typ 'slide-{n}.png'
|
|
```
|
|
|
|
## Important Notes
|
|
|
|
- **File extension matters**: Output format is inferred from the output filename
|
|
- **Incremental compilation**: Typst caches intermediate results for speed
|
|
- **Watch mode**: Ideal for development; use Ctrl+C to stop
|
|
- **Relative paths**: Resolved from the source file's directory
|
|
- **Package system**: Import packages with `#import "@preview/package:version"`
|
|
|
|
## Getting Help
|
|
|
|
```bash
|
|
typst help # General help
|
|
typst compile --help # Compile command help
|
|
typst watch --help # Watch command help
|
|
typst fonts --help # Fonts command help
|
|
```
|
|
|
|
## Resources
|
|
|
|
- **Reference**: https://typst.app/docs/reference/
|
|
- **Tutorial**: https://typst.app/docs/tutorial/
|
|
- **Packages**: https://typst.app/universe/
|
|
- **GitHub**: https://github.com/typst/typst
|