---
name: pdf-generator
description: "Generate a designed, print-quality PDF (guide, report, whitepaper, multi-part book) from HTML using a browser the machine already has. Use when asked to produce, export, or design a PDF, or to turn markdown, docs, or research into a polished downloadable document. HTML-first: reads the print rulebook, authors print-first HTML from a branded template, renders via headless Chrome or Edge --print-to-pdf, stamps page numbers in post, and verifies objectively (a shrink-to-fit scan) plus page by page. Ships beginner-friendly components and a split-render-and-merge pipeline for books with full-bleed part dividers."
---

# PDF Generator

Author print-first HTML from a branded template, render it with the browser already on the machine, stamp page numbers, and verify with a shrink-scan plus a page-by-page read. Design rules first, no cheap-looking output.

## Phases

Work through these in order.

### 1. Rules

Read the print rulebook before writing any HTML: page geometry, break discipline, the shrink-to-fit trap (nothing may exceed the printable width), print typography, ink, and what Chrome's print pipeline cannot do.

Read: [design-tokens](https://selwynuy.dev/d/design-tokens.md)

### 2. Author

Copy the branded template and write the document to the rules: declared @page size, flowing sections, break-protected components, a plain-words explainer opening every section, diagrams over prose, and a tiered action plan closing the guide.

Read: [branding-overview](https://selwynuy.dev/d/branding-overview.md), [writing-without-ai-slop](https://selwynuy.dev/d/writing-without-ai-slop.md)

### 3. Render

Run the bundled renderer (finds an installed Chrome, Edge, or Chromium), then stamp page numbers with the paginate script; for books, render dividers as their own single-page documents and merge the pieces in order.

### 4. Verify

Run the check script first (page count, page size, per-page shrink detection), then open the PDF and walk every page: full-bleed cover, no stranded headings or split components, display font actually loaded. Fix in the HTML and re-render until the pages pass.

Read: [working-with-me](https://selwynuy.dev/d/working-with-me.md)

## Bundled files

- `scripts/build-pdf.mjs` (script): Cross-platform renderer: finds an installed Chrome, Edge, or Chromium and prints each HTML input to PDF, reporting size and page count. Zero dependencies.
- `scripts/paginate-pdf.mjs` (script): Stamps a centered page number in the bottom margin of every page except the cover, in post, from the real page count.
- `scripts/merge-pdfs.mjs` (script): Concatenates piece PDFs into one book in argument order, enabling full-bleed interior part dividers via split-render-and-merge.
- `scripts/check-pdf.mjs` (script): Objective verification: page count, page size, and per-page shrink-to-fit detection read from the PDF's own drawing instructions.
- `templates/guide.html` (template): The branded print document: full-bleed dark cover, light interior, flowing sections, and example markup for every break-protected component, from plain-words boxes to checklists and playbooks.
- `references/print-design.md` (reference): The print rulebook: page geometry, break discipline, the shrink-to-fit trap, bleed mechanics, split-render-and-merge, typography, ink, verification checklist, troubleshooting table.

---

Part of PDF Generator from Selwyn Uy's Next.js Handbook. Full page: https://selwynuy.dev/skills/pdf-generator