What is a headless Chromium PDF rendering?

Headless Chromium PDF rendering is the process of using the Chromium browser engine, run without a visible UI ("headless"), to load a page — its HTML, CSS, fonts, and JavaScript — and export the fully rendered result as a PDF file, the same way a real browser's "Print to PDF" would.

Expanding on the concept

Chromium is the open-source browser engine behind Google Chrome, Microsoft Edge, and several other browsers. In "headless" mode, it runs as a background process with no window, mouse, or keyboard — it's driven entirely by code. That makes it useful as a general-purpose rendering engine on a server: give it HTML or a URL, let it lay out and paint the page exactly as it would on a screen, and instead of displaying the result, capture it as a screenshot or, in this case, a paginated PDF document. Because it's the real browser engine, it supports the full web platform — modern CSS (flexbox, grid, `@page` rules), web fonts, and JavaScript that runs before the page is captured.

How it works

A typical headless Chromium PDF pipeline follows the same few steps regardless of which tool or library drives it:

1. Launch a headless Chromium process (no visible window).
2. Navigate it to a URL, or load raw HTML directly into the page context.
3. Wait for the page to finish loading — including any client-side JavaScript rendering.
4. Call Chromium's print pipeline (the DevTools Protocol's Page.printToPDF command) with options like page format and margins.
5. Receive back a PDF file and return or store it.

Docweave's own API follows exactly this shape:

curl https://docweave.dev/api/v1/pdf \
  -H "Authorization: Bearer dw_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/pdf" \
  -d '{
    "source": { "type": "url", "url": "https://example.com/invoice/1024" },
    "options": { "format": "A4", "margin": "20mm" }
  }' \
  --output invoice.pdf

How Docweave relates to this

Docweave is a document-generation API built directly on headless Chromium rendering. A single call to POST /api/v1/pdf accepts a source — raw HTML, a URL, or a stored template combined with JSON data — renders it with Chromium, and returns the PDF, billed per document rather than per page. Requests can carry an idempotencyKey so retries never generate the same document twice. The same rendering path is also exposed as an open-source MCP tool — run npx @docweave/mcp — so an AI agent can call generate_pdf directly instead of writing HTTP plumbing.

FAQ