sjungling/pdf-generation

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:

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:

${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:

# 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)