Almost every "generate a PDF" feature starts the same way.

You already have HTML. You already have CSS. So you reach for the obvious move: render the page, screenshot it to PDF, ship it. Puppeteer, Playwright, wkhtmltopdf, a hosted "HTML to PDF API" — pick your flavor. In an afternoon you have an invoice coming out the other end and it looks fine.

Then it goes to production. And "fine" slowly turns into a backlog of weird, hard-to-reproduce bugs.

This is not an argument that HTML-to-PDF is useless. For a one-off export or an internal report, it's great. The argument is narrower: the moment PDF generation becomes a real, automated, customer-facing part of your product, "screenshot a web page" is the wrong abstraction — and the failure modes are predictable enough to list in advance.

The core problem: a PDF is not a web page

A browser renders for an infinite, scrollable, single-width viewport. A PDF is a stack of fixed, finite, printable pages.

Those are different physics.

HTML-to-PDF works by rendering your page in a headless browser and then slicing that continuous render into page-sized pieces. Everything that's hard about it comes from that one mismatch: you designed for a stream, and now you're forcing it into pages.

Most of the bugs below are just that mismatch showing up in different costumes.

Failure mode 1: pagination

This is the big one.

A browser has no concept of "page 2." So when your content is taller than one page, the engine has to guess where to cut — and it cuts wherever the pixel ruler lands.

That means:

• a table row sliced in half across the page break
• a heading stranded alone at the bottom of a page, its content on the next
• a total row that floats away from the table it belongs to
• a signature block split from the line above it

CSS has break-inside: avoid, break-before, and friends — and they help. But support is uneven across engines, they interact badly with flex/grid, and you end up hand-tuning rules per document until it looks right for the data you tested with. Which leads directly to the next problem.

Failure mode 2: it passes review, then real data breaks it

You test with "Acme Inc." and a two-line invoice. It's perfect. You ship.

Then production sends:

• a customer name that's 90 characters long
• a line-item description that wraps to three lines
• an invoice with 47 items instead of 2
• a localized currency string twice as wide as $
• an address with a missing field, collapsing the layout

Now the logo overlaps the header. The table pushes the total onto a second page by itself. The footer rides up into the body. None of it reproduced locally, because the layout was implicitly tuned to your sample data, not to the full range of real data.

A layout that only holds for the data you happened to test with isn't a layout. It's a coincidence.

Failure mode 3: fonts and rendering drift

The PDF looked right on your machine. On the server it's Times New Roman, because the font you used isn't installed in the container.

Headless rendering inherits every environment-specific quirk of a real browser:

• missing fonts silently fall back to something ugly
• emoji and non-Latin scripts render as tofu boxes (□□□)
• print media queries behave differently than what you previewed on screen
• a Chrome version bump subtly shifts spacing, and last month's pixel-perfect invoice now wraps differently
• high-resolution images blow up the file size or come out blurry depending on the device scale factor

You don't control the renderer. You control a configuration of a renderer that changes underneath you.

Failure mode 4: the operational tax

Even when the output is correct, running a browser to make a PDF is a heavy way to make a PDF.

Each render spins up a headless Chrome process. In production that means:

• hundreds of MB of RAM per render, and CPU spikes under load
• a process that can hang, leak, or zombie — so now you need timeouts, restarts, and a watchdog
• slow cold starts that make this miserable in serverless/Lambda
• a fat, fragile dependency (the whole browser) baked into your container
• a brand-new scaling bottleneck: concurrent PDF requests now compete for browser processes

You set out to render a document and accidentally adopted a browser fleet to operate.

Failure mode 5: security surface

Headless browsers execute whatever they're told to render. The instant any user-controlled content reaches the template — a name, a note, a logo URL — you've opened the door to:

• SSRF via <img>/<link>/@import pointing at internal services or cloud metadata endpoints
• local file reads through file:// URLs
• JavaScript execution and resource exfiltration unless you've carefully locked the sandbox down

It's all manageable. But "I just wanted an invoice" turned into running a content-injection-capable browser engine on your infrastructure, and that's a real surface you now own.

Why these keep happening

Step back and the pattern is obvious: every one of these bugs comes from making the layout engine re-derive the document on every render.

The browser doesn't know it's making an invoice. It knows it's painting a box model. So it re-flows, re-paginates, and re-decides everything, every time, from whatever HTML and data you handed it — and any of those decisions can go sideways when the inputs change or the environment shifts.

The data changes every render. The layout almost never does. But HTML-to-PDF couples them, so a change in data can corrupt the layout.

What to use instead: structured templates

The alternative is to stop screenshotting a web page and instead render from a structured template — a real document definition (pages, blocks, tables, text frames) that's built to paginate and reflow as a document, not as a viewport.

The split looks like this:

HTML-to-PDF:   data + layout-as-HTML  →  browser  →  screenshot  →  slice into pages
Structured:    data  →  reusable template  →  document renderer  →  PDF

Concretely, you separate the two things that were tangled together:

• The template is designed once. It owns the layout: page size, margins, typography, where the logo goes, how the table behaves when it has 2 rows or 200.
• The data is all that changes per render. You send JSON; the template absorbs it.

Because the renderer understands documents instead of viewports, the failure modes above stop being your problem:

• Pagination is a first-class concept — tables break across pages with headers repeating, rows stay intact, totals stay attached.
• Long/variable data reflows inside the structure instead of overflowing it — a 90-character name wraps, a 200-row table paginates, the layout holds.
• Fonts are part of the template, embedded and deterministic — no server-environment roulette.
• No browser means no per-render Chrome process, no cold-start tax, no browser CVEs to babysit.
• No arbitrary HTML/JS execution, so the content-injection surface mostly evaporates.

Same template, every time. Same spacing, same fonts, same brand. Only the data is different.

What it looks like in practice

Instead of building an HTML string and handing it to a browser, you design the template once, then generate from data:

{
  "customer_name": "Acme Inc.",
  "invoice_number": "INV-1048",
  "due_date": "2026-07-24",
  "line_items": [
    { "description": "API usage",    "quantity": 1, "amount": "$480.00" },
    { "description": "Support plan",  "quantity": 1, "amount": "$199.00" }
  ],
  "total": "$679.00"
}

That's the entire per-render payload. No markup, no CSS, no print media queries, no break-inside incantations. Send the data, get back a finished PDF. Whether it's one document or ten thousand, the template already solved the layout — you're not re-solving it on every request.

This is the idea behind PDFMakerAPI: design a reusable PDF template in a visual editor, then generate PDFs from your data — by REST API, no-code workflows (Zapier/Make/n8n), or an AI agent over MCP. A PDF generation API for document automation, specifically so the layout stops being something every render has to rediscover.

When HTML-to-PDF is still the right call

To keep this honest: reach for headless Chrome when

• it's a genuine one-off or low-volume internal export,
• you're literally trying to archive a web page as it appears (that's the one case where "screenshot the page" is the actual requirement), or
• the layout is throwaway and consistency doesn't matter.

The problems start when the document is reused, branded, automated, generated in bulk, or sent to customers — because that's when consistency, determinism, and operational cost stop being optional.

The takeaway

HTML-to-PDF feels free because you already have the HTML. The cost shows up later, in production, as pagination bugs, layout breakage on real data, font drift, a browser fleet to operate, and a security surface you didn't mean to adopt.

If you're exporting a web page, screenshot the web page.

If you're generating a document — the same document, over and over, with different data — design the template once and render from structured data. Let the data change. Keep the layout fixed.

That's the difference between a PDF feature that works in the demo and one that survives production.