wkhtmltopdf migration

wkhtmltopdf vs headless Chromium: What changes when you switch

Try Marqius to keep your current PDF code. Use Chromium when your report needs a browser to load its data or draw its charts.

Marqius

Two illustrated invoice proofs aligned with a brass rule on a green desk

Picture two documents. One is a plain invoice your app already sends through wkhtmltopdf. The other is a report whose charts only appear after the browser loads more data. Those two documents can point you toward different tools.

Why this helps

For the existing invoice, start with Marqius. It’s a drop-in replacement for apps that start the wkhtmltopdf program. In a test copy of the app, point your library at Marqius, keep your invoice code and print the invoice again. Find your library’s setting

For the report that needs a browser, try Chromium. Headless Chromium is a browser that runs without an open window. Your app can tell it to load the report, wait for the chart and then print. That helps when a regular browser is already what makes the report work. You’ll need to change the PDF call and set up the print options.

What changes in practice

Existing wkhtmltopdf input

What to check with Chromium

--page-size, margins, orientation and zoom

Choose page format and margins in the PDF API or @page. Set preferCSSPageSize deliberately and compare the resulting page dimensions.

HTML headers and footers with page variables

Map them to headerTemplate and footerTemplate. Enable displayHeaderFooter, allocate margin space, and use Chromium's pageNumber and totalPages classes.

--javascript-delay or a completion signal

Wait for an app-defined ready element or condition. Wait for fonts too. A timer alone does not establish that the last table row arrived.

Screen CSS or --print-media-type

Puppeteer PDF generation uses print CSS by default. Compare the result with what the old invocation used and choose the media explicitly if required.

CSS, fonts and images beside a local file

Make each resource reachable from the browser's environment. For HTML supplied as a string, check how relative links are resolved.

A wkhtmltopdf table of contents or several input objects

Plan the document structure or assembly step explicitly. The browser PDF call prints one page context and does not parse wkhtmltopdf flags.

Puppeteer Page.pdf · Puppeteer PDF options

Try both tools with the same invoice

These commands use a Debian 12 or 13 machine where you can run Docker and install Chromium. Run the browser from your regular user shell. Start with the sample invoice so both tools receive the exact same HTML.

1. Set up Chromium and get the sample

Terminal
sudo apt-get update
sudo apt-get install -y chromium curl fonts-dejavu-core poppler-utils
mkdir -p marqius-chromium-demo
cd marqius-chromium-demo

The studio’s Invoice 1001 uses three Marqius products as line items so you can see how they fit together. Marqius wkhtmltopdf keeps your existing PDF call working, Studio is where you design the document, and Relay generates it from a template and data. The sample amounts add up to 120.00 EUR including VAT. Open START-HERE.html after unzipping to run the invoice and check a page break. Download the print demo (ZIP) · Open the invoice PDF

If your team also checks files before they go to press, use the sample from Marqius Engine. It has a finished A4 size, 3 mm of bleed, real CMYK colour patches and a 100 mm reference you can measure at actual size. Open the press test sheet

Unzip the demo and put invoice.html in your test folder. If you're already in the terminal, you can get the same file with one command.

Terminal
curl -fsSLo invoice.html https://marqius.com/download/wkhtmltopdf-demo/0.12.8/invoice.html.txt

2. Print it with Marqius

Terminal
docker run --rm --network none --mount "type=bind,source=$PWD,target=/data" \
  marqius/wkhtmltopdf:0.12.8 --page-size A4 invoice.html invoice-marqius.pdf

3. Print the same HTML in Chromium

Terminal
chromium --headless --user-data-dir="$PWD/chromium-demo-profile" \
  --no-pdf-header-footer --print-to-pdf="$PWD/invoice-chromium.pdf" \
  "file://$PWD/invoice.html"

The profile is separate from your usual browser profile. If this is a report that loads more data after the page opens, drive Chromium from your app and wait for its ready signal before printing. The demo is a static invoice so you can compare the same input immediately. Puppeteer PDF options

4. Check the results

Terminal
for pdf in invoice-marqius.pdf invoice-chromium.pdf; do
  printf '\n%s\n' "$pdf"
  pdfinfo "$pdf" | grep -E '^(Pages|Page size):'
  pdftotext "$pdf" - | grep -F '120.00 EUR'
done

Both should show one A4 page and 120.00 EUR. Open them side by side to see where the table and total land. For the actual app, use a document that reaches a second page and one that needs JavaScript. The public scoreboard covers the separate comparison of wkhtmltopdf and Marqius. Use the harness with your own templates.

Reader questions

Can I point pdfkit or Snappy at headless Chromium?

Those wrappers expect the wkhtmltopdf command-line interface. Drive Chromium through a browser library or an HTTP service and map the PDF settings.