Turn local HTML into a paginated, searchable document

HTML is how most documents are actually authored now — invoices generated by a billing system, reports from a dashboard, receipts, certificates, statements. All of them eventually need to become a PDF, because that is what people archive, print, and attach to emails.

The stylesheet does most of the work

The single biggest determinant of output quality is not the conversion tool. It is whether the HTML has sensible print rules.

A screen stylesheet is designed for a scrolling viewport of unknown height. A page is a fixed rectangle with margins. Rules inside a @media print block let you tell the renderer what to do about that difference:

• Page size and margins, so the content sits properly on A4 or Letter.
• Page break control, so headings do not strand at the foot of a page and tables do not split awkwardly.
• Hiding screen furniture — navigation bars, cookie banners, sidebars, share buttons, and footers that mean nothing on paper.
• Repeating table headers across pages, which browsers support natively for properly marked-up tables.
• Switching to print-friendly colours, since light grey on white that looks subtle on screen frequently disappears on paper.

If you control the HTML, half an hour spent on print rules improves every document that template ever produces. If you do not control it, expect to accept the output as it is.

Sanitisation is not optional

An HTML file is executable content. Loading arbitrary HTML to render it means loading whatever scripts, remote stylesheets, fonts, tracking pixels, and iframes it references.

The HTML conversion tool sanitises the input before rendering, which matters for two distinct reasons:

• Security. A document from an untrusted source should not be able to run code in your browser session.
• Privacy. Remote resources are network requests. A tracking pixel in an emailed invoice reports that you opened it, and a remote font tells a third party that a render happened, along with your address. Neither belongs in a local conversion.

The practical consequence is that content depending on remote resources may render differently from how it looks in a browser. Inline your CSS and embed your images if fidelity matters.

Pagination problems and their fixes

Symptom	Usual cause and fix
Content cut off at the right edge	Fixed pixel widths wider than the page; use relative widths in print rules
Headings stranded at page ends	Add break-after avoidance to heading rules
Tables split without headers	Mark up thead properly so the browser repeats it
Backgrounds missing	Print colour adjustment is off by default; enable it explicitly
Everything on one enormous page	The renderer found no page size; set it in the print stylesheet
Links unclickable	Expected on paper; write important URLs out in the text
Fonts substituted	The referenced font was remote and not loaded; embed or inline it

Text stays text

Worth stating because it is the main advantage over the alternative approach of screenshotting a page: a proper HTML render produces real text in the PDF. It is selectable, searchable, and accessible to screen readers. Vector graphics stay vector. Only actual images are raster.

That makes converted HTML far more useful than an image-based capture, and much smaller. If a converted document has no selectable text, something in the pipeline rasterised it, and that is worth fixing rather than accepting.

Choosing between the authoring routes

Three tools overlap here, and the distinction is about how much control you need:

• Markdown — structured text with no layout control. Best for documents that are mostly prose and change often, as described in the Markdown guide.
• HTML — full layout control through CSS. Best for templated documents generated by a system: invoices, statements, certificates.
• Direct document creation — writing with formatting in front of you, without authoring code at all. Best for one-off documents.

For data-driven output specifically, HTML is usually the right answer, because the same template can render a thousand invoices consistently. Just remember that each of those invoices contains customer details, which is a strong argument for rendering them in the browser rather than posting them to a conversion service.