122 lines
2.4 KiB
Markdown
122 lines
2.4 KiB
Markdown
# 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 |