# Installation Guide

## Quick Install (macOS)

```bash
# Using the Makefile
make install

# Then generate PDFs
make
```

## Manual Installation

### 1. Install Typst

Typst is the rendering engine that generates PDFs from templates.

#### Option A: Using Homebrew (Recommended)
```bash
brew install typst
```

#### Option B: Direct Download
1. Visit https://github.com/typst/typst/releases
2. Download the latest macOS binary
3. Extract and move to your PATH:
```bash
tar xzf typst-*.tar.gz
sudo mv typst /usr/local/bin/
```

#### Option C: Using Cargo (Rust)
```bash
cargo install typst-cli
```

### 2. Install qpdf (Optional but Recommended)

qpdf is used for PDF linearization and validation.

```bash
brew install qpdf
```

### 3. Install Python Dependencies

```bash
pip3 install -r requirements.txt
# Or directly:
pip3 install pyyaml
```

## Verify Installation

```bash
# Check all dependencies
which typst && echo "✓ Typst installed"
which qpdf && echo "✓ qpdf installed"
python3 -c "import yaml" && echo "✓ PyYAML installed"

# Run a test build
make test
```

## Troubleshooting

### "command not found: brew"

Install Homebrew first:
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

### "command not found: pip3"

Python 3 should be included with macOS. If not:
```bash
brew install python3
```

### "Permission denied" errors

Use sudo for system-wide installation:
```bash
sudo pip3 install pyyaml
```

Or use user installation:
```bash
pip3 install --user pyyaml
```

### Typst font errors

The bundled fonts should work automatically. If you see font errors:
1. Verify fonts exist: `ls fonts/*.ttf`
2. Explicitly specify font path: `python3 src/generate.py --font-path fonts/`

## Dependencies Summary

| Component | Required | Purpose | Size |
|-----------|----------|---------|------|
| Python 3 | Yes | Script execution | Included with macOS |
| Typst | Yes | PDF generation | ~30MB |
| PyYAML | Yes | Config file parsing | <1MB |
| qpdf | Optional | PDF optimization | ~5MB |

## Platform Support

This tool is designed for macOS but should work on:
- **macOS**: Full support (10.15+)
- **Linux**: Should work with same dependencies
- **Windows**: Requires WSL or manual adaptation

## Next Steps

After installation:
1. Run `make` to generate default flashcards
2. Check `out/flashcards.pdf` for output
3. Run `make samples` for more examples
4. Customize with your own configuration