Hermes Mini-Guide PDF Compilation

Compile "I WINS. Hermes Helps." mini-guide chapters into a polished PDF using WeasyPrint.

When to Use

User asks to "compile the PDF", "generate the next version", or "update the mini-guide PDF"
Chapters have been reviewed and are ready for final output

Working Directory

/opt/data/wiki/produce/hermes/books/hermes-mini-guide/

Folder Structure

hermes-mini-guide/
├── chapters/       ← source .md files (source of truth)
├── build/          ← scripts, generated PDFs, diagrams, venv
├── planning/       ← task management, progress, launch checklists
├── research/       ← reference notes, style guides
├── reviews/        ← editorial review notes
├── feedback/       ← reader feedback
├── social/         ← launch drafts + messages
├── scraps/         ← cut content
└── AGENTS.md       ← detailed build instructions

Quick Reference: Regenerate the PDF

# 1. Concatenate chapters → full book markdown
cd /opt/data/wiki/produce/hermes/books/hermes-mini-guide
(for f in chapters/00-intro.md chapters/01-wins-framework.md chapters/02-why-hermes.md \
    chapters/03-personal-agentic-os.md chapters/04-wealth.md chapters/05-insights.md \
    chapters/06-self.md chapters/08-getting-started.md chapters/09-what-trips-people-up.md \
    chapters/14-tips-for-starting.md chapters/about-the-author.md; do
  cat "$f"
  echo
  echo
done) > build/full-book-v5.md

2. Generate PDF
cd build
PYTHONPATH=pdf-venv/lib/python3.13/site-packages python3 generate-pdf-v5.py

Output: build/i-wins-hermes-helps-v5.pdf

Pipeline: Markdown → HTML → WeasyPrint → PDF

Step 1: Activate venv

cd /opt/data/wiki/produce/hermes/books/hermes-mini-guide/build
source pdf-venv/bin/activate

If venv is broken, recreate:

cd /opt/data/wiki/produce/hermes/books/hermes-mini-guide/build
uv venv pdf-venv
source pdf-venv/bin/activate
uv pip install weasyprint markdown pillow cairosvg

Note: If source pdf-venv/bin/activate doesn't set PATH correctly (known issue in some shells), use PYTHONPATH workaround:

PYTHONPATH=pdf-venv/lib/python3.13/site-packages python3 generate-pdf-v5.py

Step 2: Render cover image

The cover is build/diagrams/cover-diagram.html (SVG). Render to PNG:

from cairosvg import svg2png
import re
with open('build/diagrams/cover-diagram.html', 'r') as f:
    content = f.read()
svg_match = re.search(r'<svg.*?</svg>', content, re.DOTALL)
svg2png(bytestring=svg_match.group().encode(), write_to='build/diagrams/cover-v5.png', output_width=1080, output_height=1080)

Step 3: Concatenate chapters

CRITICAL: Use loop with echo between files (NOT bare cat — YAML frontmatter glues to previous text without newlines):

cd /opt/data/wiki/produce/hermes/books/hermes-mini-guide
(for f in chapters/00-intro.md chapters/01-wins-framework.md chapters/02-why-hermes.md \
    chapters/03-personal-agentic-os.md chapters/04-wealth.md chapters/05-insights.md \
    chapters/06-self.md chapters/08-getting-started.md chapters/09-what-trips-people-up.md \
    chapters/14-tips-for-starting.md chapters/about-the-author.md; do
  cat "$f"
  echo
  echo
done) > build/full-book-v5.md

Chapter 7 (chapters/07-principles-trump-tools.md) is EXCLUDED — moved to review.

Step 4: Run generation script

cd /opt/data/wiki/produce/hermes/books/hermes-mini-guide/build
PYTHONPATH=pdf-venv/lib/python3.13/site-packages python3 generate-pdf-v5.py

The script:

1. Reads full-book-v5.md (in same directory as script)

2. Strips ALL YAML frontmatter blocks (---...---) via regex

3. Converts markdown → HTML via Python markdown lib

4. Builds TOC from # headings

5. Injects: cover page, copyright page (Lemon Squeezy), TOC

6. Renders HTML → PDF via WeasyPrint

Output: build/i-wins-hermes-helps-v5.pdf

Step 5: Verify

No raw title: or --- in PDF text
Cover image renders (WINS diagram)
Copyright says "Lemon Squeezy" (NOT Gumroad)
Chapter 7 excluded
About the Author on last page

Key Design Decisions

WeasyPrint, NOT pandoc/LaTeX — server-friendly, no heavy deps
Cover: build/diagrams/cover-diagram.html rendered to PNG (NOT card-square.png)
Publisher: Lemon Squeezy (NOT Gumroad)
Chapter 7 excluded — "Principles Trump Tools" in review
Author: Joseph Jude
Title: "I WINS. Hermes Helps."
Fonts: Literata + Inter + Source Code Pro via Google Fonts CDN

Pitfalls

1. YAML frontmatter leaks — Each chapter has ---\ntitle: "..."\n---. Script strips ALL with regex. If raw title: appears in PDF, regex broke.

2. cat without newlines — --- markers glue to previous text. Use loop with echo.

3. Cover image — Use build/diagrams/cover-diagram.html (rendered to PNG), NOT card-square.png.

4. Publisher — "Lemon Squeezy", NOT "Gumroad".

5. Chapter 7 excluded — not in the book.

6. Venv activate quirk — source pdf-venv/bin/activate may not set PATH in some shells. Use PYTHONPATH=pdf-venv/lib/python3.13/site-packages python3 generate-pdf-v5.py as fallback.

7. Script paths resolve from build/ — all paths in generate-pdf scripts are relative to build/ where the scripts live.

hermes-mini-guide-pdf