HTML to PDF: Harder Than It Should Be

You have a nice web page. You need it as a PDF. Control+P, save as PDF. Done?

Sometimes. But often the result has broken layouts, missing images, weird page breaks, and headers that cut off mid-sentence.

HTML and PDF are fundamentally different. Making them work together takes effort.

Why It's Complicated

HTML is fluid. Content flows to fill available space. Responsive. Flexible.

PDF is fixed. Specific page dimensions. Exact positioning. Nothing flows.

Converting means taking something designed to adapt and forcing it onto rigid pages.

Page Breaks Are The Enemy

Your beautiful paragraph ends up split across two pages. The table header is on page 3, the data starts on page 4.

CSS has page-break-before, page-break-after, and page-break-inside properties. They're supposed to control this.

h2 {
  page-break-after: avoid;
}

table {
  page-break-inside: avoid;
}

"Supposed to" because browser support varies. Test thoroughly.

What Renders and What Doesn't

Web fonts: Sometimes work, sometimes don't. Test with actual fonts, not fallbacks.

Background colors: Often excluded by default (saves ink). Check "print backgrounds" settings.

Images: External images may not load. CORS issues appear at conversion time.

JavaScript-rendered content: If content loads via JS, it might not exist when the PDF captures the page.

Animations and transitions: Gone. PDF is static.

Print Stylesheets

CSS has a media type for print:

@media print {
  .no-print {
    display: none;
  }

  body {
    font-size: 12pt;
  }

  a::after {
    content: " (" attr(href) ")";
  }
}

Hide navigation, adjust fonts, show URLs for links. Design specifically for print output.

Different Conversion Methods

Browser print to PDF: Good for one-off conversions. Results vary by browser.

Headless browsers (Puppeteer, Playwright): Programmatic control. Consistent results. Requires setup.

PDF libraries (wkhtmltopdf, WeasyPrint): Dedicated tools. Better control over output.

Online services: Upload HTML, get PDF. Convenient for occasional use.

Each has trade-offs in quality, speed, and control.

Tips for Better Results

Use fixed widths. Responsive layouts cause unpredictable results. Set a specific width for PDF output.

Simplify layouts. Complex CSS grid and flexbox can break. Simpler layouts convert more reliably.

Embed fonts. Don't rely on system fonts being available.

Test early. Don't build the whole page and then try PDF conversion. Test as you build.

Set explicit page size. PDF thinks in pages. Tell it what size.

@page {
  size: A4;
  margin: 1cm;
}

When to Use Native PDF

If you need precise control—contracts, invoices, reports with exact formatting—consider generating PDF directly instead of converting HTML.

Libraries like PDFKit, ReportLab, or iText create PDF without the HTML conversion layer.

More work, more control, more predictable results.

---

HTML to PDF conversion works, but it requires attention to print styles, page breaks, and the differences between web and print mediums. Test thoroughly and set expectations accordingly.