snapshot of https://github.com/mattermost/mattermost.git (master, 2026-09-16; blobs > 131072B omitted)

docs/pdf/README.md

@@ -0,0 +1,124 @@
+# Phase 2 — PDF pipeline
+
+Builds brand-aligned PDF books from the docs site using headless Chromium + a print-only stylesheet.
+
+## What's here
+
+```
+pdf/
+├── books/                    # Spine config: ordered list of URLs per book
+│   └── api.json
+├── scripts/
+│   ├── build-page-pdf.mjs    # Capture a single page → PDF (the on-demand primitive)
+│   └── build-book-pdf.mjs    # Concatenate a section's pages → branded book PDF
+├── styles/
+│   └── print.css             # Brand-aligned print stylesheet (cover, headers, page numbers)
+├── build/                    # Output (gitignored)
+└── package.json              # Puppeteer
+```
+
+## Pipeline
+
+```
+docs site (npm start | npm run serve)
+        │
+        │ HTTP fetches per spine entry
+        ▼
+build-book-pdf.mjs
+        │
+        ├── fetches each <article> via Puppeteer page navigation
+        ├── prepends a brand-aligned cover (denim + marigold + Mission in Motion)
+        ├── composes static HTML, includes Google Fonts + the docs site's bundled CSS
+        ├── overrides everything for paper via styles/print.css (only thing the print pass cares about)
+        ▼
+Puppeteer page.pdf({ format: 'A4', preferCSSPageSize: true })
+        │
+        ▼
+build/mattermost-api.pdf
+```
+
+The print stylesheet does:
+- `@page` rules for A4 size, margins, and running headers/footers
+- `string-set: chapter content()` on h1 → fed into `@top-right` for chapter names
+- `counter(page) " / " counter(pages)` in `@bottom-right` for page numbers
+- Hides every site-chrome element (navbar, sidebar, footer, breadcrumbs, edit-this-page, OpenAPI right panel)
+- Brand-aligned typography (Archivo Black headlines, Inter body, JetBrains Mono code)
+- Page-break controls (`page-break-before: always` on h1, `page-break-inside: avoid` on figures/code/tables)
+- Print-mode treatments for every branded MDX component (Hero flattens, Callouts get a thin denim left bar, StatStrip becomes a 4-up grid, CardGrid becomes a list)
+
+## Usage
+
+### Single-page (on-demand) PDF
+
+```bash
+# Pre-req: docs site is running on port 3000 (npm start in docs-site/)
+node pdf/scripts/build-page-pdf.mjs http://localhost:3000/api pdf/build/api-overview.pdf
+```
+
+Suitable as the unit primitive for the eventual "Download PDF" button on every page (CF Worker calls this against the production URL).
+
+### Multi-page book
+
+```bash
+node pdf/scripts/build-book-pdf.mjs --book api
+# → pdf/build/mattermost-api.pdf
+```
+
+Spine controlled by `pdf/books/api.json` — add/remove URL paths to change what's in the book. Future work auto-generates the spine from the OpenAPI tag list.
+
+## Current state
+
+| Capability | Status |
+| --- | --- |
+| Single-page PDF capture | ✓ Working |
+| Multi-page book with cover | ✓ Working |
+| Brand-aligned cover (denim + marigold + Mission in Motion + version + date) | ✓ Working |
+| Running header (chapter name on right) | ✓ Working |
+| Running footer (page X / N) | ✓ Working |
+| Page-break-before on each chapter (h1) | ✓ Working |
+| Branded typography (Archivo Black headlines) | ✓ Working |
+| Branded MDX components in print mode | ✓ Working |
+
+| Coming in v1.1 / future | |
+| --- | --- |
+| Auto-generated TOC with page numbers | Needs Paged.js (target-counter) — see §below |
+| Cross-reference page numbers ("see chapter X on page N") | Needs Paged.js |
+| Watermarked customer PDFs (per-buyer "Provided to …") | CF Worker injecting watermark via page.evaluate before page.pdf |
+| Auto-generated index | Needs Paged.js + index plugin |
+| All sections, all versions (per PLAN.md §6.1) | Needs spine generators per OpenAPI / per RST tree |
+
+## Paged.js — when to add
+
+Puppeteer's native `page.pdf()` covers the basic book layout (cover, headers, footers, page breaks) using just `@page` rules. We use that today.
+
+Paged.js adds:
+- TOC generation via `target-counter()` (the printed page number a heading lands on)
+- "Continued on page N" bridges
+- Automatic figure / table cross-references
+- Better break-balancing across columns
+
+Add Paged.js when we hit a real need for any of those — likely Phase 5 (main docs migration, where the admin guide is 100+ pages and a good TOC matters more). For now, the cover + chapter breaks + page numbers are sufficient.
+
+To add: load `pagedjs` from npm or CDN, mount it via `Paged.Previewer().preview(content, stylesheets, container)` before calling `page.pdf`.
+
+## On-demand Worker (deferred)
+
+The on-demand per-page "Download PDF" button (PLAN.md §6.2) is the same `build-page-pdf.mjs` primitive, hosted on a Cloudflare Worker:
+
+```
+User clicks "Download PDF" on /docs/11.0/admin/saml-config
+                ▼
+CF Worker /api/pdf?url=…
+                ▼
+Browser Rendering API loads the URL, applies print.css, returns PDF stream
+                ▼
+Worker streams PDF back with Content-Disposition: attachment
+```
+
+This is straightforward to add once production is up (Browser Rendering API needs a domain). Defer to Phase 6 (cut first release branch) or later.
+
+## Costs
+
+Local: free. Headless Chromium runs on your machine.
+
+Production (CF Browser Rendering API): ~$0.001–0.005 per render. At 1000 PDFs/day (per PLAN.md §6.2), ~$50–150/mo.