pdf-generation

What this skill does

# PDF Book Generation

## Overview

Converts a directory of ordered markdown chapters into a single, styled PDF book with table of contents, page numbers, and resolved inter-chapter links.

**Core principle:** The markdown files are the source of truth. The PDF is a derived artifact -- never edit the PDF directly.

## When to Use

Automatically activates when:

- A request to generate a PDF from markdown chapters is made
- A `technical-overview` or similar multi-chapter doc set is ready for export
- A printable or shareable version of documentation is needed

## Prerequisites

Three tools must be installed before generation can proceed:

| Tool | Install command | Purpose |
|------|----------------|---------|
| `pandoc` | `brew install pandoc` | Markdown to HTML conversion |
| `weasyprint` | `uv tool install weasyprint` | HTML to PDF rendering |
| `pango` | `brew install pango` | Text layout (weasyprint dependency) |

Before running the script, verify availability:

```bash
command -v pandoc >/dev/null 2>&1 || echo "Missing: pandoc (brew install pandoc)"
command -v weasyprint >/dev/null 2>&1 || echo "Missing: weasyprint (uv tool install weasyprint)"
```

If either tool is missing, install it and retry. The script itself checks for dependencies and exits with a clear error message.

## How It Works

The generation pipeline has four stages:

1. **Collect** -- Gather markdown files in order: `README.md` first, then `00-*.md` through `99-*.md`, then `appendix-*.md`
2. **Convert** -- Pandoc stitches all files into a single HTML document with a generated table of contents
3. **Fix links** -- Inter-chapter `.md` links (e.g., `[architecture](01-architecture.md)`) are rewritten to internal `#anchor` links so they work within the single document
4. **Render** -- Weasyprint converts the styled HTML to PDF with print-optimized CSS

## Usage

Run the generation script using `$CLAUDE_PLUGIN_ROOT`:

```bash
${CLAUDE_PLUGIN_ROOT}/skills/pdf-generation/scripts/generate-pdf.sh <input-dir> [output.pdf]
```

- `input-dir` -- Directory containing the ordered markdown chapters
- `output.pdf` -- Optional output path (defaults to `<input-dir>/technical-overview.pdf`)

### Handling Missing CLAUDE_PLUGIN_ROOT

If `$CLAUDE_PLUGIN_ROOT` is not set (e.g., running outside a plugin context), locate the script manually:

```bash
# Fallback: find the script in the plugin installation directory
SCRIPT_PATH=$(find ~/.claude/plugins -path "*/pdf-generation/scripts/generate-pdf.sh" 2>/dev/null | head -1)
if [ -z "$SCRIPT_PATH" ]; then
  echo "Error: generate-pdf.sh not found. Ensure the technical-writer plugin is installed."
  exit 1
fi
"$SCRIPT_PATH" <input-dir> [output.pdf]
```

## Expected Directory Structure

The input directory must contain ordered markdown files following this naming convention:

```
docs/technical-overview/
├── README.md              # Title page and introduction (always first)
├── 00-getting-started.md  # Numbered chapters in sequence
├── 01-architecture.md
├── 02-data-model.md
├── 03-api-reference.md
├── 04-deployment.md
├── appendix-a-glossary.md # Appendices after numbered chapters
└── appendix-b-faq.md
```

**Expected output:**

```
docs/technical-overview/
├── ... (source files unchanged)
└── technical-overview.pdf  # Generated PDF (default output location)
```

The PDF includes:
- A title derived from the first `# ` heading in `README.md` (or the directory name as fallback)
- A generated table of contents with depth 2 (h1 and h2 headings)
- Page numbers centered at the bottom of each page
- Chapter breaks (each h1 starts on a new page)
- Resolved inter-chapter links as internal anchors

## Inter-Document Linking Requirements

For the PDF to have working internal links, the source markdown must follow these rules:

- Use relative links between chapters: `[architecture overview](01-architecture.md)`
- Section links with anchors work too: `[the store layer](03-data-layer.md#store)`
- Every chapter should have exactly one `# ` heading -- this is used to resolve link targets
- The script warns about any `.md` links it cannot resolve

**Common linking mistakes:**

| Mistake | Fix |
|---------|-----|
| Absolute paths (`/docs/01-arch.md`) | Use relative paths (`01-arch.md`) |
| Missing `# ` heading in chapter | Add exactly one h1 heading per chapter |
| Link to file not in input directory | Ensure all linked files are in the same directory |

## Styling and Customization

The script embeds a print-optimized CSS stylesheet with sensible defaults:

- **Page size:** US Letter with 1-inch top/bottom margins
- **Fonts:** System font stack (Apple system fonts, Segoe UI, Helvetica, Arial)
- **Code blocks:** Light gray background with monospace font at 9pt
- **Tables:** Bordered with alternating row colors
- **Chapter breaks:** Each h1 heading starts on a new page

For detailed CSS customization options (fonts, colors, page sizes, themes), see `./references/css-customization.md`.

## Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| "Error: 'pandoc' is not installed" | Missing dependency | `brew install pandoc` |
| "Error: 'weasyprint' is not installed" | Missing dependency | `uv tool install weasyprint && brew install pango` |
| Warning about unresolved `.md` links | Chapter heading does not match filename pattern | Ensure each chapter has a `# ` heading and the link target filename is correct |
| PDF renders but fonts look wrong | Missing system fonts | weasyprint uses system fonts; install desired fonts via Font Book |
| Empty PDF or no chapters found | Files not matching naming convention | Verify files follow `README.md`, `00-*.md` through `99-*.md`, `appendix-*.md` pattern |
| `CLAUDE_PLUGIN_ROOT` is empty | Running outside plugin context | Use the fallback script discovery method described above |
| Long code blocks overflow margins | Default CSS handles this | Verify `overflow-wrap: break-word` and `white-space: pre-wrap` in CSS |

## Additional Resources

- **`./references/css-customization.md`** -- Detailed CSS customization options for fonts, page sizes, colors, and themes
- **`./scripts/generate-pdf.sh`** -- The generation script (inspect for advanced modification)