init commit

2026-01-12 12:37:52 -05:00
commit 5f5bae8694
5 changed files with 1386 additions and 0 deletions
@@ -0,0 +1,353 @@
+---
+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
@@ -0,0 +1,607 @@
+# Typst CLI Examples
+
+Quick reference for common `typst` commands and markup patterns.
+
+## Installation Verification
+
+```bash
+# Check version
+typst --version
+
+# Get help
+typst help
+```
+
+## Compilation
+
+### Basic Compilation
+
+```bash
+# Compile to PDF (default)
+typst compile document.typ
+
+# Explicit output file
+typst compile document.typ output.pdf
+
+# Compile to PNG
+typst compile document.typ document.png
+
+# Compile to SVG
+typst compile document.typ document.svg
+```
+
+### Output Options
+
+```bash
+# High-resolution PNG (300 PPI)
+typst compile --ppi 300 document.typ output.png
+
+# Multi-page to numbered PNGs
+typst compile document.typ 'output-{n}.png'
+
+# Custom output directory
+typst compile document.typ build/output.pdf
+```
+
+### Root and Input
+
+```bash
+# Set root directory for imports
+typst compile --root /project/src document.typ
+
+# Pass input variables
+typst compile --input version=2.0 document.typ
+typst compile --input author="John Doe" --input date=2024-01-15 document.typ
+```
+
+## Watch Mode
+
+```bash
+# Watch and recompile on changes
+typst watch document.typ
+
+# Watch with specific output
+typst watch document.typ output.pdf
+
+# Watch with PNG output
+typst watch thesis.typ thesis.png
+```
+
+## Font Management
+
+```bash
+# List all available fonts
+typst fonts
+
+# Filter fonts by name
+typst fonts | grep -i "computer modern"
+
+# Compile with custom font path
+typst compile --font-path ./fonts document.typ
+
+# Multiple font paths
+typst compile --font-path ./fonts --font-path ~/Library/Fonts document.typ
+```
+
+## Document Templates
+
+### Basic Document
+
+```typst
+// document.typ
+#set page(paper: "a4", margin: 2.5cm)
+#set text(font: "New Computer Modern", size: 11pt)
+#set par(justify: true)
+
+= Document Title
+
+#lorem(50)
+
+== First Section
+
+#lorem(100)
+
+=== Subsection
+
+#lorem(75)
+```
+
+### Academic Paper
+
+```typst
+// paper.typ
+#set document(title: "Research Paper", author: "Author Name")
+#set page(paper: "us-letter", margin: 1in)
+#set text(font: "Times New Roman", size: 12pt)
+#set par(justify: true, leading: 2em)
+#set heading(numbering: "1.1")
+
+#align(center)[
+  #text(size: 16pt, weight: "bold")[Paper Title]
+
+  #v(1em)
+
+  Author Name \
+  Institution \
+  #link("mailto:email@example.com")
+
+  #v(1em)
+
+  #datetime.today().display("[month repr:long] [day], [year]")
+]
+
+#v(2em)
+
+*Abstract.* #lorem(80)
+
+#v(1em)
+
+= Introduction
+
+#lorem(100)
+
+= Methods
+
+#lorem(100)
+
+= Results
+
+#lorem(100)
+
+= Discussion
+
+#lorem(100)
+
+#bibliography("references.bib")
+```
+
+### Letter
+
+```typst
+// letter.typ
+#set page(paper: "us-letter", margin: 1in)
+#set text(font: "Georgia", size: 11pt)
+
+#align(right)[
+  Your Name \
+  123 Main Street \
+  City, State 12345 \
+  #datetime.today().display()
+]
+
+#v(2em)
+
+Recipient Name \
+456 Other Street \
+City, State 67890
+
+#v(1em)
+
+Dear Recipient,
+
+#lorem(150)
+
+Sincerely,
+
+#v(3em)
+
+Your Name
+```
+
+### Resume/CV
+
+```typst
+// resume.typ
+#set page(paper: "us-letter", margin: 0.5in)
+#set text(font: "Helvetica", size: 10pt)
+
+#align(center)[
+  #text(size: 20pt, weight: "bold")[Your Name]
+
+  email\@example.com | (555) 123-4567 | linkedin.com/in/yourname
+]
+
+#line(length: 100%)
+
+== Experience
+
+*Senior Developer* | Company Name | 2020 - Present
+- Led team of 5 developers on major product launch
+- Implemented CI/CD pipeline reducing deployment time by 50%
+
+*Developer* | Other Company | 2018 - 2020
+- Built REST APIs serving 1M+ requests daily
+- Mentored junior developers
+
+#line(length: 100%)
+
+== Education
+
+*Master of Science, Computer Science* | University Name | 2018
+
+*Bachelor of Science, Computer Science* | University Name | 2016
+
+#line(length: 100%)
+
+== Skills
+
+*Languages:* Python, JavaScript, Rust, Go \
+*Frameworks:* React, Django, FastAPI \
+*Tools:* Docker, Kubernetes, AWS
+```
+
+## Math Examples
+
+### Inline Math
+
+```typst
+The quadratic formula is $x = (-b plus.minus sqrt(b^2 - 4a c)) / (2a)$.
+
+Einstein's equation $E = m c^2$ relates mass and energy.
+
+The sum $sum_(i=1)^n i = (n(n+1))/2$ is well known.
+```
+
+### Display Equations
+
+```typst
+The Gaussian integral:
+$ integral_(-infinity)^infinity e^(-x^2) dif x = sqrt(pi) $
+
+Maxwell's equations:
+$ nabla dot bold(E) &= rho / epsilon_0 \
+  nabla dot bold(B) &= 0 \
+  nabla times bold(E) &= -pdv(bold(B), t) \
+  nabla times bold(B) &= mu_0 bold(J) + mu_0 epsilon_0 pdv(bold(E), t) $
+```
+
+### Matrices
+
+```typst
+$ mat(
+  1, 2, 3;
+  4, 5, 6;
+  7, 8, 9;
+) $
+
+$ mat(delim: "[",
+  a, b;
+  c, d;
+) $
+```
+
+### Cases
+
+```typst
+$ f(x) = cases(
+  x^2 &"if" x >= 0,
+  -x^2 &"if" x < 0,
+) $
+```
+
+## Tables
+
+### Basic Table
+
+```typst
+#table(
+  columns: 3,
+  [Header 1], [Header 2], [Header 3],
+  [Cell 1], [Cell 2], [Cell 3],
+  [Cell 4], [Cell 5], [Cell 6],
+)
+```
+
+### Styled Table
+
+```typst
+#table(
+  columns: (1fr, 2fr, 1fr),
+  align: (left, center, right),
+  stroke: 0.5pt,
+  inset: 8pt,
+  table.header(
+    [*Name*], [*Description*], [*Value*],
+  ),
+  [Alpha], [First item], [100],
+  [Beta], [Second item], [200],
+  [Gamma], [Third item], [300],
+)
+```
+
+### Data Table
+
+```typst
+#let data = csv("data.csv")
+
+#table(
+  columns: data.first().len(),
+  ..data.flatten()
+)
+```
+
+## Figures and Images
+
+### Basic Image
+
+```typst
+#image("photo.jpg", width: 50%)
+```
+
+### Figure with Caption
+
+```typst
+#figure(
+  image("diagram.png", width: 80%),
+  caption: [System architecture overview],
+) <fig:architecture>
+
+As shown in @fig:architecture, the system consists of three layers.
+```
+
+### Side-by-Side Figures
+
+```typst
+#grid(
+  columns: 2,
+  gutter: 1em,
+  figure(
+    image("before.png"),
+    caption: [Before optimization],
+  ),
+  figure(
+    image("after.png"),
+    caption: [After optimization],
+  ),
+)
+```
+
+## Code Blocks
+
+### Inline Code
+
+```typst
+Use the `print()` function to output text.
+```
+
+### Code Block
+
+````typst
+```python
+def fibonacci(n):
+    if n <= 1:
+        return n
+    return fibonacci(n-1) + fibonacci(n-2)
+```
+````
+
+### Code with Caption
+
+````typst
+#figure(
+  ```rust
+  fn main() {
+      println!("Hello, world!");
+  }
+  ```,
+  caption: [A simple Rust program],
+)
+````
+
+## Lists
+
+### Bullet List
+
+```typst
+- First item
+- Second item
+  - Nested item
+  - Another nested item
+- Third item
+```
+
+### Numbered List
+
+```typst
+ First step
+ Second step
+ Third step
+```
+
+### Definition List
+
+```typst
+/ Term: Definition of the term
+/ Another term: Its definition
+```
+
+## Layout
+
+### Columns
+
+```typst
+#columns(2)[
+  #lorem(50)
+
+  #colbreak()
+
+  #lorem(50)
+]
+```
+
+### Grid
+
+```typst
+#grid(
+  columns: (1fr, 1fr),
+  rows: (auto, auto),
+  gutter: 1em,
+  [Cell 1], [Cell 2],
+  [Cell 3], [Cell 4],
+)
+```
+
+### Alignment
+
+```typst
+#align(center)[Centered text]
+#align(right)[Right-aligned text]
+#align(left + bottom)[Bottom-left aligned]
+```
+
+### Spacing
+
+```typst
+Text before
+#v(2em)  // Vertical space
+Text after
+
+Word #h(1cm) spaced #h(1cm) out
+```
+
+## References and Citations
+
+### Labels and References
+
+```typst
+= Introduction <intro>
+
+See @intro for more details.
+
+#figure(
+  image("fig.png"),
+  caption: [A figure],
+) <fig:example>
+
+As shown in @fig:example...
+```
+
+### Bibliography
+
+```typst
+According to @smith2020, this is important.
+
+Multiple citations @smith2020 @jones2021.
+
+#bibliography("refs.bib", style: "ieee")
+```
+
+## Data Import
+
+### JSON
+
+```typst
+#let data = json("data.json")
+#data.name // Access fields
+```
+
+### CSV
+
+```typst
+#let rows = csv("data.csv")
+#for row in rows [
+  #row.at(0), #row.at(1)
+]
+```
+
+### YAML
+
+```typst
+#let config = yaml("config.yaml")
+Title: #config.title
+```
+
+## Scripting
+
+### Variables
+
+```typst
+#let title = "My Document"
+#let author = "John Doe"
+
+#title by #author
+```
+
+### Functions
+
+```typst
+#let highlight(body) = {
+  box(fill: yellow, inset: 3pt, body)
+}
+
+This is #highlight[important] text.
+```
+
+### Conditionals
+
+```typst
+#let draft = true
+
+#if draft [
+  *DRAFT - DO NOT DISTRIBUTE*
+]
+```
+
+### Loops
+
+```typst
+#for i in range(1, 6) [
+  - Item #i
+]
+```
+
+## Advanced CLI
+
+### Batch Processing
+
+```bash
+# Compile all .typ files in directory
+for f in *.typ; do
+    typst compile "$f"
+done
+
+# Compile with common settings
+for f in chapters/*.typ; do
+    typst compile --font-path ./fonts "$f" "output/$(basename $f .typ).pdf"
+done
+```
+
+### CI/CD Integration
+
+```bash
+# Check compilation succeeds
+typst compile document.typ && echo "Success" || echo "Failed"
+
+# Compile and verify output exists
+typst compile thesis.typ thesis.pdf
+if [ -f thesis.pdf ]; then
+    echo "PDF generated successfully"
+fi
+```
+
+### Environment Setup
+
+```bash
+# Set font paths for session
+export TYPST_FONT_PATHS="$HOME/fonts:/usr/share/fonts"
+
+# Compile with custom root
+export TYPST_ROOT="/project"
+typst compile src/main.typ
+```
+
+## Troubleshooting Commands
+
+```bash
+# Verbose output for debugging
+typst compile document.typ 2>&1 | head -50
+
+# Check available fonts
+typst fonts | wc -l  # Count fonts
+
+# Find specific font
+typst fonts | grep -i "fira"
+
+# Test minimal document
+echo '= Test' | typst compile - test.pdf
+```