HTML to PDF: The Complete
Developer Guide (2026)

It starts simply enough. You need to generate a PDF — an invoice, a report, a contract. You find a library, write twenty lines of code, and it works. Then you push to production. The font is wrong. A table is split across two pages. The header is missing on page three. The whole thing looks like it was rendered on a computer from 2009.

Welcome to HTML to PDF conversion — one of the most deceptively hard problems in web development. This guide documents every major failure mode, why each one happens, and what actually fixes it — with working code in every major language.

1. Why HTML to PDF Is Fundamentally Hard

HTML was designed for infinite scroll. PDF was designed for fixed pages. This is not a minor implementation detail — it is a philosophical mismatch that causes almost every problem in this space.

A browser doesn't need to know where page 3 starts. A PDF renderer does. CSS properties like overflow: scroll, position: sticky, and viewport units (vw, vh) have no meaningful equivalent in a paginated document. Every HTML-to-PDF tool is, at its core, an attempt to bridge this gap — and each makes different tradeoffs about where to break down.

There are five fundamentally different approaches to converting HTML to PDF, each with different tradeoffs:

• Headless browser rendering (Puppeteer, Playwright, Gotenberg) — sends the HTML through a real browser engine and prints the result. Highest fidelity, highest resource cost.
• CSS Paged Media engines (PrinceXML, PDFreactor, WeasyPrint) — purpose-built renderers that interpret the W3C CSS Paged Media spec. Excellent for printed documents, but require PDF-specific CSS knowledge.
• Legacy WebKit wrappers (wkhtmltopdf) — frozen circa 2015. Do not use.
• Programmatic PDF builders (jsPDF, PDFKit, iTextSharp) — generate PDF structure directly rather than rendering HTML. Full control, but requires rewriting your templates in a PDF-specific API.
• Managed cloud APIs (ConvertStack, DocRaptor, Browserless) — offload the rendering infrastructure entirely. Trade cost per conversion for zero ops burden.

2. wkhtmltopdf Is Dead — Migrate Now

For years, wkhtmltopdf was the default answer to "how do I convert HTML to PDF." It was free, it worked, and it ran anywhere. Thousands of libraries were built on top of it — DinkToPdf, Rotativa, NReco.PdfGenerator in .NET; barryvdh/laravel-dompdf in PHP; WickedPDF in Ruby on Rails.

All of those wrappers are now wrappers around abandoned software. The rendering engine doesn't understand CSS Grid, CSS custom properties, modern flexbox behaviour, clamp(), min(), max(), or ES6+ JavaScript. If your design uses any of these — and modern designs all do — your PDFs will silently produce wrong output that's difficult to debug.

The migration path: replace wkhtmltopdf with Playwright or Puppeteer. Both ship an evergreen Chromium engine and produce PDFs that match what you see in Chrome. Playwright is faster and produces smaller files (see benchmarks); Puppeteer is a stable choice for existing Node.js codebases. Gotenberg wraps Chromium behind a Docker REST API for polyglot architectures.

3. CSS That Works in a Browser Breaks in a PDF

The most common CSS casualties in HTML to PDF conversion:

Background colors and images. Most renderers suppress backgrounds by default to save ink — a sensible printer default that's disastrous for designed documents. In headless Chrome, pass printBackground: true. In CSS, add -webkit-print-color-adjust: exact; print-color-adjust: exact; to every element that needs it, or globally.

Flexbox and Grid. Modern headless Chromium tools handle these correctly. wkhtmltopdf and other WebKit-frozen tools render them incorrectly or ignore them entirely.

Viewport units. 100vw in a PDF context is meaningless or resolves to the paper width — usually not what you want. Use fixed px or % widths relative to your page size instead.

Position: fixed / sticky. Fixed positioning may repeat on every page, or may not appear at all, depending on the renderer. Use headers/footers via the renderer API instead.

External stylesheets. Renderers running in sandboxed environments can't load external CSS via <link> tags. Inline your critical styles, or serve them from a URL the renderer can reach.

CSS variables. Fully supported in modern Chromium-based tools. Not supported in wkhtmltopdf.

/* ── Force backgrounds in PDF ── */
* {
  -webkit-print-color-adjust: exact;
  print-color-adjust: exact;
}

/* ── Target PDF output only ── */
@media print {
  .sidebar    { display: none; }
  .content    { width: 100%; }
  body        { font-size: 12pt; }

  /* Avoid viewport units in PDFs */
  .hero       { width: 100%; height: auto; }
}

4. Page Breaks Are a Nightmare

CSS provides page-break properties, but they are easy to get wrong. Use both the old and new forms for maximum compatibility:

/* ── Never break inside these elements ── */
tr, img, figure, .card, .invoice-line {
  page-break-inside: avoid;  /* old */
  break-inside: avoid;       /* new */
}

/* ── Force a new page before major sections ── */
.page-section {
  page-break-before: always;
  break-before: page;
}

/* ── Keep headings attached to their content ── */
h1, h2, h3 {
  page-break-after: avoid;
  break-after: avoid;
}

/* ── Prevent orphaned/widowed lines ── */
p {
  orphans: 3;
  widows: 3;
}

For large tables where break-inside: avoid is not feasible, split the data into multiple <table> elements — one per page worth of rows — and apply page-break-before: always to each after the first.

5. Fonts That Work Everywhere Else Don't Render

The solutions, in order of reliability:

1. Self-host fonts. Download the font files and serve them from the same origin as your HTML. No external network calls required.
2. Wait for network idle. Use waitUntil: 'networkidle0' in Puppeteer or wait_until='networkidle' in Playwright to ensure all font requests complete before rendering.
3. Base64-encode and embed. Convert font files to base64 and embed them directly in your @font-face declaration. Verbose but eliminates all network dependency.

/* Self-hosted font — works in sandboxed renderers */
@font-face {
  font-family: 'Inter';
  src: url('/fonts/Inter-Regular.woff2') format('woff2');
  font-weight: 400;
  font-display: block; /* avoid FOUT in renderer */
}

/* Base64 embed — no network dependency at all */
@font-face {
  font-family: 'Inter';
  src: url('data:font/woff2;base64,d09GMgABAA...') format('woff2');
}

6. Headers, Footers, and Page Numbers

In headless Chrome (Puppeteer/Playwright), headers and footers are separate HTML templates passed to the pdf() call. They run in a different execution context — your page's CSS and JavaScript do not apply. Inline all styles inside the template.

// Playwright / Puppeteer — header and footer with page numbers
const pdf = await page.pdf({
  format: 'A4',
  printBackground: true,
  displayHeaderFooter: true,
  headerTemplate: `
    <div style="font-family:sans-serif;font-size:9px;width:100%;
      padding:0 20px;display:flex;justify-content:space-between;
      color:#888;border-bottom:1px solid #eee;">
      <span>My Company — Confidential</span>
      <span>Generated <span class="date"></span></span>
    </div>`,
  footerTemplate: `
    <div style="font-family:sans-serif;font-size:9px;width:100%;
      padding:0 20px;display:flex;justify-content:space-between;
      color:#888;">
      <span>https://example.com</span>
      <span>
        Page <span class="pageNumber"></span>
        of <span class="totalPages"></span>
      </span>
    </div>`,
  margin: {
    top: '50px',    // must match header height
    bottom: '40px', // must match footer height
    left: '15mm',
    right: '15mm'
  }
});

Chromium automatically replaces .pageNumber, .totalPages, .title, .url, and .date spans. The margin values must equal or exceed the header/footer height — otherwise content overlaps.

7. JavaScript-Rendered Content Is Missing

Headless Chromium tools (Puppeteer, Playwright) execute JavaScript fully. Tell them to wait for your content:

// Wait for all network requests to finish (fonts, API calls, images)
await page.goto(url, { waitUntil: 'networkidle0' });

// OR wait for a specific element that signals content is ready
await page.waitForSelector('.invoice-total', { state: 'visible' });

// OR wait for a custom signal from your app
await page.waitForFunction(() => window.PDF_READY === true);

For server-rendered applications (Next.js, Nuxt, Astro), this is less of an issue since HTML is fully formed before JavaScript executes. Building PDF-heavy features with SSR is the most reliable architecture.

8. Scale Breaks Everything

A single Chromium instance handles roughly 5–10 parallel renders before performance degrades. Each process uses 150–400 MB of RAM. In a serverless environment (Lambda, Cloud Run), cold-starting Chromium adds 1–3 seconds to the first request in a new instance.

At scale you need: a pool of warm browser instances, a job queue with retry logic, health checks and restart policies, and careful memory management to prevent leaks across renders. This is real infrastructure work that has nothing to do with your product. It is why managed API services exist.

9. HTML to PDF in Node.js / JavaScript

Node.js has the best HTML to PDF tooling ecosystem. Playwright and Puppeteer both have first-class Node.js support.

With Playwright (recommended)

// npm install playwright && npx playwright install chromium
const { chromium } = require('playwright');

async function htmlToPdf(htmlString) {
  const browser = await chromium.launch();
  const page = await browser.newPage();

  await page.setContent(htmlString, {
    waitUntil: 'networkidle' // wait for fonts, images
  });

  const pdf = await page.pdf({
    format: 'A4',
    printBackground: true,
    margin: { top: '20mm', bottom: '20mm', left: '15mm', right: '15mm' }
  });

  await browser.close();
  return pdf; // Buffer
}

// Convert a live URL
async function urlToPdf(url) {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto(url, { waitUntil: 'networkidle' });
  const pdf = await page.pdf({ format: 'A4', printBackground: true });
  await browser.close();
  return pdf;
}

With Puppeteer

// npm install puppeteer
const puppeteer = require('puppeteer');

async function htmlToPdf(htmlString) {
  const browser = await puppeteer.launch({ args: ['--no-sandbox'] });
  const page = await browser.newPage();
  await page.setContent(htmlString, { waitUntil: 'networkidle0' });
  const pdf = await page.pdf({
    format: 'A4',
    printBackground: true,
    margin: { top: '20mm', bottom: '20mm', left: '15mm', right: '15mm' }
  });
  await browser.close();
  return pdf;
}

// Express.js route example
app.post('/generate-pdf', async (req, res) => {
  const pdf = await htmlToPdf(req.body.html);
  res.set({ 'Content-Type': 'application/pdf', 'Content-Length': pdf.length });
  res.send(pdf);
});

10. HTML to PDF in Python

Python has two strong options depending on your requirements: Playwright for full JavaScript support, and WeasyPrint for pure CSS Paged Media rendering without a browser dependency.

With Playwright (JavaScript support)

# pip install playwright && playwright install chromium
from playwright.sync_api import sync_playwright

def html_to_pdf(html_string: str) -> bytes:
    with sync_playwright() as p:
        browser = p.chromium.launch()
        page = browser.new_page()
        page.set_content(html_string, wait_until='networkidle')
        pdf = page.pdf(
            format='A4',
            print_background=True,
            margin={'top': '20mm', 'bottom': '20mm',
                    'left': '15mm', 'right': '15mm'}
        )
        browser.close()
        return pdf  # bytes

# Convert a URL
def url_to_pdf(url: str) -> bytes:
    with sync_playwright() as p:
        browser = p.chromium.launch()
        page = browser.new_page()
        page.goto(url, wait_until='networkidle')
        pdf = page.pdf(format='A4', print_background=True)
        browser.close()
        return pdf

# Django view example
def generate_invoice(request, invoice_id):
    invoice = Invoice.objects.get(pk=invoice_id)
    html = render_to_string('invoices/pdf.html', {'invoice': invoice})
    pdf = html_to_pdf(html)
    return HttpResponse(pdf, content_type='application/pdf')

With WeasyPrint (no browser required)

# pip install weasyprint
# No Chromium required — pure Python CSS renderer
from weasyprint import HTML, CSS

def html_to_pdf(html_string: str) -> bytes:
    return HTML(string=html_string).write_pdf()

# With external stylesheet
def html_to_pdf_with_styles(html_string: str, css_path: str) -> bytes:
    return HTML(string=html_string).write_pdf(
        stylesheets=[CSS(filename=css_path)]
    )

# WeasyPrint supports CSS Paged Media — running headers,
# footnotes, margin boxes. Playwright does not.
# WeasyPrint does NOT execute JavaScript.

11. HTML to PDF in PHP

PHP has historically relied on wkhtmltopdf wrappers (barryvdh/laravel-snappy, knplabs/knp-snappy). These should now be migrated. The best modern PHP approaches are Gotenberg (Docker REST API) or a managed API.

Via Gotenberg (Docker REST API)

# docker run --rm -p 3000:3000 gotenberg/gotenberg:8

// PHP — send HTML to Gotenberg and receive a PDF
function htmlToPdf(string $html): string {
    $boundary = uniqid();
    $body  = "--{$boundary}\r\n";
    $body .= 'Content-Disposition: form-data; name="files"; filename="index.html"' . "\r\n";
    $body .= "Content-Type: text/html\r\n\r\n";
    $body .= $html . "\r\n";
    $body .= "--{$boundary}--";

    $response = file_get_contents('http://localhost:3000/forms/chromium/convert/html', false, stream_context_create([
        'http' => [
            'method'  => 'POST',
            'header'  => "Content-Type: multipart/form-data; boundary={$boundary}\r\n",
            'content' => $body,
        ]
    ]));

    return $response; // PDF bytes
}

// Laravel — stream PDF to browser
public function invoice(Invoice $invoice) {
    $html = view('invoices.pdf', compact('invoice'))->render();
    return response(htmlToPdf($html), 200)
        ->header('Content-Type', 'application/pdf');
}

12. HTML to PDF in Ruby / Rails

Ruby on Rails historically used WickedPDF (wkhtmltopdf wrapper) or Prawn. WickedPDF should be migrated. The modern path is Playwright via a subprocess or a REST API.

Via Playwright (Node.js subprocess)

# Gemfile — no gem needed, call Node.js subprocess
# node_modules/playwright must be installed

# app/services/pdf_generator.rb
class PdfGenerator
  SCRIPT = Rails.root.join('lib/pdf/render.js')

  def self.from_html(html)
    result = Open3.capture2('node', SCRIPT.to_s, stdin_data: html, binmode: true)
    result[0] # PDF bytes
  end
end

# lib/pdf/render.js
const { chromium } = require('playwright');
let html = '';
process.stdin.on('data', d => html += d);
process.stdin.on('end', async () => {
  const b = await chromium.launch();
  const p = await b.newPage();
  await p.setContent(html, { waitUntil: 'networkidle' });
  const pdf = await p.pdf({ format: 'A4', printBackground: true });
  await b.close();
  process.stdout.write(pdf);
});

# Rails controller
def show
  html = render_to_string('invoices/pdf', layout: 'pdf')
  pdf  = PdfGenerator.from_html(html)
  send_data pdf, type: 'application/pdf', disposition: 'inline'
end

13. Performance Benchmarks

The numbers below are from PDF4.dev's 2026 HTML to PDF benchmark, generating a 5-page document with images, fonts, and CSS Grid on a 4-core VM. All headless browser tests used pre-warmed browser instances.

Playwright's warm-render speed (~3ms) reflects its optimized Chromium build and efficient IPC. Gotenberg's cold start is high because Docker container initialization includes Chromium startup — in a pre-warmed container it's competitive with Puppeteer.

14. Full Tool Comparison

15. Best Practices That Actually Help

Design for paper from the start. Don't try to make your web UI render as a PDF — build a separate template designed for fixed pages. Use @media print styles and fixed dimensions from the beginning.

Use a headless Chromium tool. It's the only category that correctly renders modern CSS and JavaScript. Playwright is the current performance leader; Puppeteer is a stable fallback.

Inline your styles and fonts. Any network dependency inside a PDF renderer is a potential failure. Self-host fonts, inline critical CSS, and test in a network-restricted environment to catch issues early.

Test page breaks explicitly. Generate test documents with content that spans multiple pages and verify nothing gets cut. Automate this in your CI pipeline with visual regression tools.

Set a fixed viewport width. PDF renderers default to a narrow viewport. Set an explicit width that matches your page size: await page.setViewportSize({ width: 794, height: 1123 }) for A4 at 96 DPI.

Treat scaling as infrastructure. If you're generating more than a few hundred PDFs per day, the operational cost of managing Chromium will exceed the cost of a managed API. Make that call deliberately rather than discovering it under load.

Add a PDF_READY signal. In complex apps with deferred rendering, set a flag (window.PDF_READY = true) when content is completely loaded, and wait for it with page.waitForFunction() before calling pdf().

16. Frequently Asked Questions