html-to-pdf
Builds polished PDF documents (one-pagers, reports, guides, proposals, briefs) as HTML and CSS with exact page layout, renders them with headless Chromium through Playwright, then checks every page as
SKILL.mdskills/dev/html-to-pdf/SKILL.md
GitHubHTML to PDF
Most converters give you a PDF but not control: a half-empty last page, a lone heading at the bottom, a table cut in half. This skill writes the document as HTML and CSS, prints it with headless Chromium, and looks at every page before calling it done.
What it does
- Turns content (notes, a draft, data, a brief) into a single self-contained HTML file laid out page by page.
- Renders it to PDF with headless Chromium. No window ever opens.
- Exports each page as a PNG, checks it by eye and by script, fixes problems and renders again.
- Hands over the PDF with its page count, size and the QA it passed.
What you need
- Python 3.9 or newer.
- Playwright and Chromium:
pip install playwright pypdf pypdfium2 python -m playwright install chromiumpypdfium2is only for PNG export. If it is missing, the script falls back topdftoppmfrom poppler. - The content, the audience, the paper size (A4 or Letter) and a target page count. If any are missing and cannot be inferred, ask once; otherwise default to A4 and the shortest length that fits.
- Puppeteer works too (same engine, same CSS).
Steps
- Plan the pages. Before writing HTML, write a one-line outline per page: what goes on page 1, page 2, and so on. A one-pager is one page. A report is usually a cover plus 2 to 6 pages. Decide the page count now, not after rendering.
- Copy the template. Start from
templates/document.html. It has a cover page, a content page, a key-number grid, two columns, a table, a callout and a footer, all in neutral styling with[placeholders]. Swap the colour and font tokens in:rootif the reader has a brand. - Fill one
.pageblock per planned page. Real content, not lorem ipsum. Lead with the point. - Render:
It prints the page count, file size and PNG paths, and warns about overflowing content, fonts that did not load, broken images, and a mismatch betweenpython scripts/render_pdf.py report.html out/report.pdf --png-dir qa/ --expect-pages 3.pageboxes and PDF pages. Add--strictto make any warning a failure. - Look at every PNG against the QA list below. The script catches overflow; only your eyes catch ugly.
- Fix and render again. Repeat steps 4 and 5 until every page passes. Old PNGs are cleared on each run so you never review a stale render.
Layout rules
Two ways to lay out pages. Pick one per document.
- Fixed pages (default, used by the template). Each
<div class="page">is exactly one sheet:widthandheightset to the paper size,overflow: hidden,break-after: page. You decide what goes on each page, so the page count is guaranteed. Best for one-pagers, covers, proposals and anything with a promised length. - Flowing text. For long prose (guides, manuals) let content flow and use
@page { size: A4; margin: 20mm; }with break rules. Page count is then an output, not an input, so check it every render.
Always:
- Set the paper size once, in
@page { size: A4; margin: 0; }(orLetter), and render withprefer_css_page_size=True. Letter is 8.5in by 11in, A4 is 210mm by 297mm. Never mix them. - Use print units (
mm,in,pt) for page boxes, margins and type. Body text 10 to 11pt, captions 8pt, nothing under 7.5pt. - Keep things whole:
break-inside: avoidon cards, metric grids, callouts, figures and table rows.break-after: avoidon headings so a heading never ends a page. orphans: 3; widows: 3;on paragraphs so a single line is never stranded.- Tables:
thead { display: table-header-group; }repeats the header if a long table must continue. Otherwise move the whole table to the next page or split it at a logical row. - Turn on
print-color-adjust: exactand render with print backgrounds, or tinted panels vanish. - Self-contained file: inline CSS, inline SVG charts, images as local files or data URIs. Every remote font or image is a chance to render with a fallback.
- Fonts: system font stacks are safest. If you load a web font, keep the fallback stack and check the script's font warnings.
- Pin footers with
margin-top: autoin a flex column, not absolute positioning, so overflow is detectable. - No empty pages, and the last page should not be mostly blank. Consolidate or cut copy.
QA
Run the script, then check each page image for:
- Overflow: text clipped at the bottom or right edge, or content hidden under the footer.
- Orphans: a heading at the foot of a page with its text on the next, or one stray line of a paragraph.
- Cut tables and cards: rows, metric grids or callouts split across pages.
- Fonts: the intended typeface, not a Times fallback. The script lists any font that failed to load.
- Images and charts: every image loaded, every SVG drawn, labels readable.
- Contrast: bold text, links and labels inside dark or tinted panels are still visible. A global text colour often hides nested
strongon dark cards. - Page count: matches the plan. Use
--expect-pages Nso the script fails if it drifts. - Folios and footers: page numbers correct ("2 / 3"), no stale totals left from an earlier draft.
- File size: a few MB at most for email (the script warns over 10 MB). Resize large photos before embedding.
- Text check (optional): extract the text (
pdftotext -layout) and search for leftover[placeholders], typos in names and figures that must match the source.
After any fix, even a one-line CSS change, re-render the PDF and regenerate every PNG before saying it passed. Screenshots from before a fix prove nothing.
Output
- The PDF, named in kebab-case for what it is:
q3-board-report.pdf,onboarding-guide.pdf. - The HTML source next to it, so the next edit is a re-render.
- A short note: page count, paper size, file size, and anything you could not verify.
- QA images stay out of the deliverable folder.
Honest limits
- Chromium print is not a typesetting engine. Hyphenation, footnotes and running headers that change by chapter are weak. For a book, use a dedicated tool.
- Fixed pages hide overflow by design (
overflow: hidden). That is why the script measures it; never skip the warnings. break-inside: avoidis a request. A block taller than a page will still split.- Remote fonts and images can fail silently on slow networks. Self-contain the file when it matters.
- Visual QA needs a model or person that can see images.
- It produces a print PDF, not an accessible tagged PDF or a fillable form.