HTML to PDF Generator Tool: A Complete Developer Guide

Use base_url when the document references relative images, stylesheets or fonts. For a file, pass HTML(filename='report.html').write_pdf('report.pdf'). Keep your WeasyPrint version pinned and compare representative PDFs after upgrades because its API reference warns that rendering can change between versions.

Generate a PDF with wkhtmltopdf

wkhtmltopdf describes a headless command-line HTML-to-PDF and image converter based on Qt WebKit. Existing deployments may still depend on it, but the surfaced project page is old, so verify supported operating systems, security posture and rendering compatibility before choosing it for a new system.

wkhtmltopdf --page-size A4 --margin-top 16mm --margin-right 14mm --margin-bottom 16mm --margin-left 14mm https://example.com report.pdf

HTML and CSS details that affect PDF output

Pagination

• Define @page size and margins explicitly.
• Use break-before, break-after and break-inside: avoid for sections, tables and cards.
• Keep headings with the following content using break-after: avoid.
• Test long words, overflowing code blocks and tables with many columns.

Fonts and assets

Make fonts and images reachable from the rendering process. Use absolute URLs or a correct base URL, wait for fonts in browser workflows, and check that private assets receive the required authentication headers. Missing fonts can change line wrapping and therefore every page break.

Colors and backgrounds

Browser printing commonly omits backgrounds unless you enable them. In Puppeteer, set printBackground: true. Also check whether your print stylesheet changes colors, shadows or visibility.

Links, outlines and attachments

WeasyPrint documents clickable links, bookmarks and embedded attachments. Browser-generated PDFs may need additional post-processing if you require a specific outline structure, metadata policy or attachment behavior.

Or skip the browser setup

ScreenshotNeo provides an HTML-to-PDF capture path through its API. See the ScreenshotNeo documentation for the current parameters. This one-call example captures a URL as a PDF:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -d format=pdf -o document.pdf

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com", "format": "pdf"},
    timeout=90,
)
r.raise_for_status()
open("document.pdf", "wb").write(r.content)

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://stripe.com',
  format: 'pdf'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
require('fs').writeFileSync('document.pdf', Buffer.from(await res.arrayBuffer()));

ScreenshotNeo removes cookie and consent banners, newsletter popups and chat widgets before the capture. Bot checks, blank pages and failed loads are never billed, and response headers identify the page verdict and whether it was billed. It also offers PDF paper size, margins, landscape mode and page ranges, plus custom CSS and JavaScript, waits, headers, cookies, user agents, authorization, timezone and geolocation. Its MCP server lets AI agents call take_screenshot, get_page_info and capture_pdf. The free plan includes 1,000 screenshots each month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.

Production checklist

1. Pin the renderer and browser versions.
2. Store a small fixture set containing long text, tables, images, non-Latin characters and authenticated content.
3. Compare rendered PDFs after dependency upgrades.
4. Wait for a real readiness selector, fonts and critical images.
5. Set navigation and conversion timeouts and cancel orphaned browser jobs.
6. Limit URL access to prevent server-side request forgery when users supply URLs.
7. Keep credentials out of generated PDFs, logs and query strings where possible.
8. Define retention and deletion rules for source HTML and generated files.
9. Measure queue time, render time, output size and failure reason by document type.

Performance, reliability and cost

Browser startup is expensive compared with reusing a controlled browser process, but long-lived processes must be isolated and recycled to avoid leaks. Reuse pages carefully, clear cookies and storage between jobs, and cap concurrency so CPU and memory pressure do not create timeouts.

Reduce output size by using appropriately sized images, avoiding unnecessary background assets and selecting the required page range. Cache deterministic documents when their inputs have not changed. For a hosted API, include network latency, transfer size, retry behavior, retention, geographic processing and per-document pricing in your cost model. ScreenshotNeo bills only clean shots; cache hits, bot checks, blank pages, timeouts and failed loads are not billed, and each response includes X-Page-Verdict and X-Billed headers.

Troubleshooting

FAQ

Which tool should I use for a React or Vue page?

Use a browser renderer such as Puppeteer when the final content is assembled by JavaScript. Wait for a deterministic ready signal before calling page.pdf().

Can WeasyPrint render JavaScript?

No. Its product documentation says it does not execute JavaScript.

How do I select only some pages?

Puppeteer’s pageRanges accepts ranges such as 1-5, 8, 11-13.

Why did an upgrade change the PDF?

Rendering engines, browser versions, fonts and pagination behavior can change. Pin versions and run visual comparisons on representative documents.

Can I generate a PDF without installing Chromium?

Yes. Use a document engine such as WeasyPrint for non-JavaScript HTML, a command-line converter already approved in your environment, or a hosted service such as ScreenshotNeo.