Skill: pdf-paginated

Paginated document PDF via headless Chromium page.pdf({format, margin}). No .canvas targeting — the whole document flows across paper pages. A folio footer (title left, page X / Y right, JetBrains Mono) is rendered in the bottom margin.

When to use

• Long-form documents where the reader expects pages: an essay, a field guide, a spec, a report body, a letter.
• When the output should be Letter or A4 with real margins and page numbers, not a single tall canvas.

Skip if:

• The artifact is a fixed-size design canvas (social post, business card, blog hero, audit-report canvas). Use pdf-html — it sizes the PDF to the canvas.
• You want a PNG. Use screenshot-html.

The HTML it expects

Plain document-flow HTML, NOT the .canvas convention:

• Content flows normally (body → article). No fixed-width .canvas wrapper.
• Give the reading column a measure with max-width (e.g. 64ch) centered, and put the page surface color on body (it prints because printBackground is on).
• Do not set @page size/margins in CSS — the script owns paper size and margins via --format / --margin. A CSS @page margin would double up.
• Optional @media print rules to keep things tidy across page breaks: h2, li { break-inside: avoid; } and h2 { break-after: avoid; }.
• Set a clean <title> — it becomes the footer's running head.
• Self-contained styles (inline <style> or a resolvable @import); web fonts load fine (the script waits for document.fonts.ready).

How to run

node skills/pdf-paginated/scripts/pdf-paginated.mjs <dir> [--output <dir>] [--format Letter|A4] [--margin <css>] [--bleed <color>] [--no-footer]

Flags:

• <dir> (positional, default .): directory scanned recursively for *.html. screenshots/, pdfs/, and hidden dirs are skipped.
• --output <dir> (default <dir>/pdfs): where PDFs are written, one per HTML file.
• --format (default Letter): Letter or A4.
• --margin (default 0.9in): CSS length applied to all four sides. Ignored in bleed mode.
• --bleed <color>: full-bleed page surface. See below.
• --no-footer: drop the folio footer (in bleed mode the footer strip still paints).

Full-bleed backgrounds (--bleed <color>)

Default mode gives white paper margins. If the document has a committed background color (e.g. a cream editorial page), that background floats as a card on white — the margins show through. --bleed <color> fixes this: it zeroes the left/right margins so the HTML background reaches the side edges, and paints the top and bottom margin strips <color> so every page is that color edge-to-edge, with a per-page inset and no white bands. The folio still renders in the bottom strip.

In bleed mode the HTML owns only its side text insets (via body padding); the top/bottom insets are the painted strips. So the HTML should:

• set the surface color on html and body with print-color-adjust: exact,
• pad only the sides (e.g. padding: 0.1in 0.95in 0.3in), and
• keep the reading column measured (max-width) and centered.

# cream editorial essay, full-bleed
node skills/pdf-paginated/scripts/pdf-paginated.mjs . --output ./pdfs --bleed '#fbfaf9'

Prerequisites

None — self-bootstraps on first run, installing Playwright + Chromium into its own node_modules next to the script (shared pattern with pdf-html / screenshot-html). First run ~10–60s; subsequent runs are fast.

Relationship to pdf-html