Paged Reports
Markdown in, print-ready document out. The pipeline is: markdown → HTML template with
brand tokens → paged.js pagination → PDF (or a browser preview, or a magazine-mode URL).
This skill owns the mechanics only. Which font, which color, which size — that is
the project's brand, not this skill's business. Read the tokens first, then render.
Where the tokens come from
Look in this order and stop at the first hit:
- The project's
DESIGN.md — frontmatter tokens are normative.
- A brand skill in the project. For Focus.AI work that is
focus-ai-brand, whose
design-system reference carries the paged type scale under "Output-Format Tokens".
- Ask. Do not invent a palette — a report in the wrong colors is worse than one that
waited a minute for an answer.
Process
- Read the source markdown and decide the mode — standard (browser preview),
paged (PDF deliverable), or magazine (shareable scroll URL). The table in
references/paged-system.md maps intent to mode.
- Pick a template from
templates/. Focus.AI ships four: client and labs, each in
standard and paged form. A project with its own brand copies one and swaps the token
block at the top — the paged.js scaffolding underneath is identical.
- Structure the content to the page-break conventions:
.section wrappers,
.no-break-before on the first section after the cover, break-inside: avoid on
anything that must stay whole. This is the part that separates a professional PDF
from a wall of text — read the "Smart Page Break System" section before writing HTML.
- Render. Write the HTML to a temp path, then either open it for a Cmd+P preview or
drive headless Chrome for a direct PDF.
- Look at the output. Open the PDF, or convert its pages to images and inspect
them. Page breaks fail in ways that are invisible in the HTML — an orphaned heading
at a page bottom, a table split across a spread, a blank page after the cover.
Shipping an unopened PDF is how those reach the client.
PDF generation
The browser-automation skill (chrome-driver) provides the pdf binary:
PDF_BIN=$(ls -d ~/.claude/plugins/cache/focus-marketplace/chrome-driver/*/bin/pdf | sort -V | tail -1)
$PDF_BIN "file:///tmp/report-$(date +%s).html" ./output.pdf
If chrome-driver is not installed, fall back to the browser print path rather than
silently producing HTML and calling it a PDF.
Reference
| Topic |
Where |
Modes, /report arguments, template selection |
references/paged-system.md |
Smart page breaks, .section, widows/orphans |
references/paged-system.md |
Running headers, page numbers, @page rules |
references/paged-system.md |
| Cover pages, cards, stats, callouts, pull quotes |
references/paged-system.md |
| Magazine mode: spreads, keyboard nav, print fallback |
references/paged-system.md |
| paged.js init, print color preservation |
references/paged-system.md |
| Focus.AI report templates (client/labs × standard/paged) |
templates/ |
Pitfalls
- Fonts must load before pagination. paged.js chunks content on the fonts it has at
init. Initialize with
PagedConfig = { auto: false } and call preview() inside
document.fonts.ready — otherwise the layout shifts after the page boundaries are set.
print-color-adjust: exact or the background disappears. Browsers strip
backgrounds in print by default. A warm paper ground is a brand decision; losing it in
the PDF is a rendering bug, not a preference.- Never pure white, never pure black — if the brand says paper and ink, that applies
to print output too.
- A blank page after the cover means the first section inherited
break-before: page.
That is what .no-break-before is for.
- Magazine mode is screen-first. It has a print fallback, but if the deliverable is a
PDF, generate paged mode directly rather than printing the magazine.
1---2name: paged-reports3description: Turn a markdown document into a styled, print-ready HTML report — running headers, page numbers, smart page breaks, cover page — and render it to PDF via headless Chrome. Also produces horizontal-scroll magazine spreads for shareable URLs. Brand-agnostic: reads its tokens from the project's DESIGN.md or brand skill. Use when asked for a PDF, a printable report, a client-ready document, a one-pager, or a shareable read-through of a markdown file. Triggers on: "make a PDF", "print this", "report", "one-pager", "deliverable", "paged", "page breaks", "cover page", "magazine spread", "/report".4---56# Paged Reports78Markdown in, print-ready document out. The pipeline is: markdown → HTML template with9brand tokens → paged.js pagination → PDF (or a browser preview, or a magazine-mode URL).1011**This skill owns the mechanics only.** Which font, which color, which size — that is12the project's brand, not this skill's business. Read the tokens first, then render.1314## Where the tokens come from1516Look in this order and stop at the first hit:17181. The project's `DESIGN.md` — frontmatter tokens are normative.192. A brand skill in the project. For Focus.AI work that is `focus-ai-brand`, whose20 design-system reference carries the paged type scale under "Output-Format Tokens".213. Ask. Do not invent a palette — a report in the wrong colors is worse than one that22 waited a minute for an answer.2324## Process25261. **Read the source markdown** and decide the mode — standard (browser preview),27 paged (PDF deliverable), or magazine (shareable scroll URL). The table in28 `references/paged-system.md` maps intent to mode.292. **Pick a template** from `templates/`. Focus.AI ships four: client and labs, each in30 standard and paged form. A project with its own brand copies one and swaps the token31 block at the top — the paged.js scaffolding underneath is identical.323. **Structure the content** to the page-break conventions: `.section` wrappers,33 `.no-break-before` on the first section after the cover, `break-inside: avoid` on34 anything that must stay whole. This is the part that separates a professional PDF35 from a wall of text — read the "Smart Page Break System" section before writing HTML.364. **Render.** Write the HTML to a temp path, then either open it for a Cmd+P preview or37 drive headless Chrome for a direct PDF.385. **Look at the output.** Open the PDF, or convert its pages to images and inspect39 them. Page breaks fail in ways that are invisible in the HTML — an orphaned heading40 at a page bottom, a table split across a spread, a blank page after the cover.41 Shipping an unopened PDF is how those reach the client.4243## PDF generation4445The `browser-automation` skill (chrome-driver) provides the `pdf` binary:4647```bash48PDF_BIN=$(ls -d ~/.claude/plugins/cache/focus-marketplace/chrome-driver/*/bin/pdf | sort -V | tail -1)49$PDF_BIN "file:///tmp/report-$(date +%s).html" ./output.pdf50```5152If chrome-driver is not installed, fall back to the browser print path rather than53silently producing HTML and calling it a PDF.5455## Reference5657| Topic | Where |58| --- | --- |59| Modes, `/report` arguments, template selection | `references/paged-system.md` |60| Smart page breaks, `.section`, widows/orphans | `references/paged-system.md` |61| Running headers, page numbers, `@page` rules | `references/paged-system.md` |62| Cover pages, cards, stats, callouts, pull quotes | `references/paged-system.md` |63| Magazine mode: spreads, keyboard nav, print fallback | `references/paged-system.md` |64| paged.js init, print color preservation | `references/paged-system.md` |65| Focus.AI report templates (client/labs × standard/paged) | `templates/` |6667## Pitfalls6869- **Fonts must load before pagination.** paged.js chunks content on the fonts it has at70 init. Initialize with `PagedConfig = { auto: false }` and call `preview()` inside71 `document.fonts.ready` — otherwise the layout shifts after the page boundaries are set.72- **`print-color-adjust: exact` or the background disappears.** Browsers strip73 backgrounds in print by default. A warm paper ground is a brand decision; losing it in74 the PDF is a rendering bug, not a preference.75- **Never pure white, never pure black** — if the brand says paper and ink, that applies76 to print output too.77- **A blank page after the cover** means the first section inherited `break-before: page`.78 That is what `.no-break-before` is for.79- **Magazine mode is screen-first.** It has a print fallback, but if the deliverable is a80 PDF, generate paged mode directly rather than printing the magazine.
The-Focus-AI