HTML to PDF: CSS for Multiple-Page Reports with wkhtmltopdf

Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.

To create a reliable multi-page PDF with wkhtmltopdf, combine semantic HTML with print CSS, reserve physical space for headers and footers, and invoke the converter with --print-media-type. Use legacy page-break-* properties for the broadest compatibility, keep tables and figures together where practical, and validate a long representative report because breaks remain subject to the renderer’s layout heuristics.

How wkhtmltopdf paginates an HTML report

wkhtmltopdf is a command-line converter that turns one or more HTML pages into a PDF using patched Qt. It lays out the document in a browser-like rendering engine, then fragments the result into physical pages. Your HTML establishes structure; CSS and command-line options establish page geometry and break opportunities.

#	Preview	Product	Price
1		Epson EcoTank ET-2800 Wireless Color All-in-One Supertank Printer - Black	$239.99	Buy on Amazon
2		Epson EcoTank Photo ET-8550 Wireless Wide-Format All-in-One Tank Printer	$689.90	Buy on Amazon
3		HP Smart Tank 5000 Wireless All-in-One Ink Tank Printer, Scanner, Copier with 2 Years of Ink...	$180.49	Buy on Amazon
4		NDYIN Portable Printers Wireless for Travel, N80 Bluetooth Thermal Printer	$41.99	Buy on Amazon

A CSS rule such as page-break-before: always is a request for a forced break. page-break-inside: avoid asks the engine not to split an element, but a very large element still has to be divided if it cannot fit on one page. Orphans, widows, images, and table rows can also constrain where a break is possible. Treat pagination as a set of constraints rather than a guarantee that every element will remain intact.

Use semantic structure first

Give the report one h1, then a stable h2/h3 hierarchy. Group each major section in a block element such as section. This improves print styling and supplies the hierarchy used by wkhtmltopdf’s outline feature.

#1 Best Overall

Epson EcoTank ET-2800 Wireless Color All-in-One Supertank Printer - Black

• INNOVATIVE CARTRIDGE-FREE PRINTING — No more dealing with lots of tiny ink cartridges; With this wireless document and photo printer each ink bottle set is equivalent to about 90 individual cartridges²
• LESS FREQUENT INK REPLACEMENT — Replacement ink bottles don't have to be changed nearly as often as ink cartridges¹; When you choose this combination printer, scanner and copier you can print up to 4,500 pages black/7,500 color³
• COLOR PRINTING — Up to 2 years of ink in the box4 (and with every replacement ink set) for fewer out-of-ink frustrations
• ZERO CARTRIDGE WASTE — By using an Epson EcoTank printer you can help reduce the amount of cartridge waste ending up in landfills
• HOME PRINTER DESIGNED FOR RELIABILITY — The Epson EcoTank ET-2800 All-in-One Supertank Color Printer creates vivid, detailed prints and documents thanks to Micro Piezo Heat-Free Technology; Fire off 10 ISO pages per minute1 to easily finish large jobs

$239.99

Buy on Amazon

Build the report HTML and print CSS

The following document is a complete starting point. It defines A4 geometry, reserves margins, starts major sections on new pages, repeats table headings, and keeps ordinary figures together when the engine can do so.

<!doctype html>
<html lang='en'>
<head>
  <meta charset='utf-8'>
  <title>Quarterly Operations Report</title>
  <style>
    @media print {
      @page {
        size: A4 portrait;
        margin: 22mm 16mm 20mm;
      }

      body {
        font: 10.5pt/1.45 Arial, sans-serif;
        color: #111;
      }

      .report-section {
        page-break-before: always;
      }

      .report > .report-section:first-child {
        page-break-before: auto;
      }

      .keep-together,
      table,
      figure {
        page-break-inside: avoid;
      }

      thead {
        display: table-header-group;
      }

      tfoot {
        display: table-footer-group;
      }

      h1, h2, h3 {
        page-break-after: avoid;
      }

      p, li {
        orphans: 3;
        widows: 3;
      }
    }

    table {
      width: 100%;
      border-collapse: collapse;
    }

    th, td {
      border: 0.2mm solid #999;
      padding: 2mm;
      vertical-align: top;
    }

    figure { margin: 4mm 0; }
    img { max-width: 100%; height: auto; }
  </style>
</head>
<body>
  <main class='report'>
    <section class='report-section'>
      <h1>Quarterly Operations Report</h1>
      <p>Prepared 29 September 2026</p>
    </section>
    <section class='report-section'>
      <h2>Executive summary</h2>
      <p class='keep-together'>Summary text goes here.</p>
    </section>
    <section class='report-section'>
      <h2>Results</h2>
      <table>
        <thead>
          <tr><th>Month</th><th>Requests</th><th>Failure rate</th></tr>
        </thead>
        <tbody>
          <tr><td>July</td><td>12,430</td><td>0.8%</td></tr>
          <tr><td>August</td><td>13,102</td><td>0.6%</td></tr>
        </tbody>
      </table>
    </section>
  </main>
</body>
</html>

What each print rule does

• @page sets the physical page size and margins. The top and bottom values must include room for any repeating header or footer.
• page-break-before: always gives each major report section a new page. The first-section override prevents an unwanted blank first page.
• page-break-inside: avoid protects compact sections, tables, and figures from ordinary splits. It cannot make an oversized object fit.
• thead { display: table-header-group; } asks the renderer to repeat column headings when a table continues on another page; verify this with your wkhtmltopdf build.
• orphans and widows request a minimum number of lines at the bottom and top of a page, reducing isolated lines.

Invoke wkhtmltopdf with the right page settings

Save the document as report.html, then run:

wkhtmltopdf 
  --print-media-type 
  --page-size A4 
  --margin-top 22mm 
  --margin-bottom 20mm 
  --header-right "Page [page] of [topage]" 
  --header-spacing 4 
  --outline 
  report.html report.pdf

--print-media-type switches media evaluation so rules inside @media print can replace screen styling. Without it, a layout that looks correct in a browser’s print preview may retain screen rules in the PDF.

Add repeating headers, footers, and page numbers

For simple text, use the command-line substitutions shown above. The manual also supports HTML header and footer documents through --header-html and --footer-html. Those files can contain branding, rules, or additional metadata. Keep their height predictable and leave matching space in --margin-top or --margin-bottom; otherwise the body can overlap the repeating material or appear vertically cramped.

A header such as Page [page] of [topage] is evaluated for every output page. If you use a footer instead, configure --footer-right or an HTML footer and reserve bottom margin. Do not rely solely on CSS page-margin boxes for wkhtmltopdf-specific numbering: CSS Paged Media defines that standards model, while wkhtmltopdf’s substitution variables are the practical interface exposed by the converter.

Rank #2

Sale

Epson EcoTank Photo ET-8550 Wireless Wide-Format All-in-One Tank Printer

• CARTRIDGE-FREE PRINTING — Print lab-quality photos, graphics and creative projects; Get vibrant colors and sharp text with Epson's high-accuracy printhead and Claria ET Premium 6-color inks
• INK BOTTLES — Save on photos1 and creative projects with affordable in-house printing; All-in-one printer allows you to print 4" x 6" photos for about 4 cents each vs. 40 cents with traditional ink cartridges1
• LESS FREQUENT INK REPLACEMENT — Replacement ink bottles don't have to be changed nearly as often as ink cartridges¹; Printer, scanner and copier lets you print up to 6,200 color pages³
• PRINT FOR LONGER — Up to 2 years of ink in the box² (and with every replacement ink set) for fewer out-of-ink frustrations with this wireless printer
• ZERO CARTRIDGE WASTE — Epson EcoTank printer helps reduce the amount of cartridge waste ending up in landfills; Cartridge-free printer uses high-yield ink bottles; Each replacement ink bottle set is equivalent to about 100 individual ink cartridges⁴

$689.90

Buy on Amazon

Generate an outline or a table of contents

Enable --outline when readers need the PDF navigation pane. The outline is derived from heading tags, so avoid using styled paragraphs as fake headings. If you need a visible generated table of contents, add a toc object to the wkhtmltopdf command and keep heading levels meaningful. A visible contents page and the navigation outline serve different purposes: one is printed content, the other is PDF navigation.

Control section breaks without making pages brittle

Start major sections deliberately

Apply page-break-before: always to report sections, not to every heading. Breaking every small subsection wastes paper and can create nearly empty pages. Use the first-section exception shown in the sample so the cover or opening section begins on page one.

Keep related content together

Wrap a heading and its short introductory paragraph in a block with page-break-inside: avoid, or apply page-break-after: avoid to headings. Keep the block small enough to fit. A table, image, or code sample taller than the remaining page must still split or move.

Prefer legacy properties for compatibility

Modern CSS uses break-before, break-after, and break-inside. They are the current fragmentation vocabulary, but support varies with the wkhtmltopdf binary and its Qt build. Include the widely recognized page-break-before, page-break-after, and page-break-inside rules when a predictable result matters, and test the exact binary used in production.

Rank #3

HP Smart Tank 5000 Wireless All-in-One Ink Tank Printer, Scanner, Copier with 2 Years of Ink Included, Best-for-Home, Cartridge-Free, Refillable and AI-Enabled. (5D1B6A)

• SET IT UP ONCE AND PRINT WITH CONFIDENCE. No complicated maintenance. Just easy, reliable printing you can count on.
• INK FOR YEARS. NOT MONTHS. Up to 2 years of ink included. Get thousands of pages of cartridge-free printing. More pages, less hassle
• KEEPS PRINTING WELL AFTER COMPETITORS HAVE QUIT. No complex maintenance. Sharper text, richer colors.[2] Only with HP Smart Tank
• PREMIUM SUPPORT - Strong technical expertise to solve issues faster
• THE LAST PRINTER YOU'LL EVER NEED. Enjoy years of refillable, cartridge-free printing.

$180.49

Buy on Amazon

Make long tables, images, and assets survive pagination

Tables

Use a real thead so repeated column labels have a chance to work. Avoid placing an entire very long table inside a blanket page-break-inside: avoid rule: the engine cannot keep a multi-page table on one page. Keep cell content concise, set widths that fit the paper, and test rows containing long unbroken strings. A table that is wider than the printable area may be clipped or trigger unexpected wrapping.

Images and replaced elements

Set max-width: 100% and preserve the intrinsic aspect ratio. Large charts can consume the remaining page and force a break despite an avoid rule. If a figure must begin on a fresh page, put the break on the figure’s wrapper rather than on the image itself. Check that every external image is reachable by the converter and that its dimensions are stable.

Fonts and external resources

PDF output depends on the fonts, binary build, operating system, and resource-loading behavior available to wkhtmltopdf. Bundle or reliably serve the assets needed for the report, then run the conversion in the same environment used for deployment. A browser on your workstation and a headless build in a container can produce different line wrapping, which changes page breaks.

When print CSS looks different from the browser

First compare media rules: invoke --print-media-type and ensure selectors inside @media print are not overridden by later screen rules. Then check page geometry. Browser print preview may use a different paper size, scaling setting, margin interpretation, or font set than wkhtmltopdf. Explicitly set the page size and margins in the command, and avoid relying on a user’s printer scaling.

Rank #4

NDYIN Portable Printers Wireless for Travel, N80 Bluetooth Thermal Printer

• Wireless Bluetooth Printer: Portable thermal printer compatible with iPhone, Android phones, iPad and tablet computers via Bluetooth. For smartphones, please download the "Nada Print" App. You can also connect to laptops and computers for printing using a USB-C cable. (Note: Laptops and computers can only be connected via USB and require the installation of a driver first. Bluetooth connection is not supported.)
• No-ink printing: Only supports US Letter and A4 size thermal paper.(Doesn't support regular paper) The no-ink portable thermal printer uses direct thermal technology, requiring no ink, toner or ribbons, making it environmentally friendly, cost-effective and time-saving. The thermal printer package comes with a roll of US Letter thermal printing paper. Note: When installing the paper, remember to switch the paper size switch on APP
• Clear Print: NDYIN N80 portable thermal printer adopts high-definition printing technology, with a 203DPI resolution to provide you with clear printing results. This mobile printer is compatible with roll paper, folded paper and tattoo transfer paper, supporting printing from your mobile phone PDF, Word, pictures and web pages anytime and anywhere. It is recommended to use our NDYIN thermal paper to achieve good printing quality
• Portable wireless printer for travel: The thermal printer is equipped with a built-in 1500mAh rechargeable battery, which can print 160 sheets of 8.5" x 11" thermal paper after being fully charged. It weighs only 1.5 pounds and is compact in size. This ink-free portable printer can be easily carried in a backpack or briefcase! It is perfect for business travel, cars, small offices, construction sites, schools and homes. You can print documents, contracts, invoices and boarding passes anytime and anywhere
• The N80 thermal printer has a wide range of uses. The package includes the N80 printer, a roll of US Letter paper(7m/roll), a user manual, a guide card, a type-C soft cable and a type C adapter. Note: The charging adapter is not included. Special thermal paper is required for use; ordinary paper cannot be used. This ink-free portable thermal printer is suitable for various scenarios such as home, school, travel, office, and outdoor, meeting the printing needs of different groups of people. This tattoo template printer is also compatible with tattoo transfer paper, making it an ideal choice for tattoo art

$41.99

Buy on Amazon

JavaScript-driven content needs special care. Ensure the page has finished rendering before conversion, and use the loading and delay options available in your installed wkhtmltopdf build when content arrives asynchronously. If a resource fails, determine whether the failure is caused by authentication, a blocked local file, a network dependency, or a timeout rather than changing break rules blindly.

Performance and repeatability

• Reuse a stable HTML template and deterministic data so changes in content, not incidental layout, explain page-count changes.
• Keep images at the resolution needed for print; oversized assets increase load time and memory without improving the PDF.
• Run representative samples: a short report, a report with a table spanning several pages, a report with a large figure, and one with the longest headings and paragraphs.
• Record the wkhtmltopdf binary and operating-system environment used for releases. Renderer versions, patched-Qt builds, fonts, and network responses all affect pagination.
• Inspect the resulting PDF visually and, where possible, extract text to confirm that headings, repeated table headers, page numbers, and links are present.

Troubleshooting common failures

A practical validation checklist

1. Open the source HTML and confirm the heading hierarchy and section wrappers.
2. Run the exact production command with --print-media-type, explicit paper size, and margins.
3. Check the first page for an accidental blank page.
4. Inspect every page containing a section start, a long table, a large image, and a heading near the bottom.
5. Confirm repeating headers, footer spacing, page counters, and outline entries.
6. Repeat the conversion in the deployment environment and compare page count and critical breaks.

Or skip the browser setup

ScreenshotNeo is a hosted screenshot API and MCP server. Its endpoint can return a screenshot or PDF without you installing a browser or maintaining a wkhtmltopdf runtime. A single request looks like this (replace the URL with a publicly reachable report page):

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com/report -o report.webp

See the ScreenshotNeo documentation for PDF output and the available capture options. The same request in Python is:

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://example.com/report"}, timeout=90)
r.raise_for_status()
open("report.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com/report' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('report.webp', Buffer.from(await res.arrayBuffer()));

• Cookie banners, newsletter popups, and chat widgets are removed before the shot; each cleanup step can be turned off.
• Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed as clean shots, and response headers identify the page verdict and billing result.
• An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
• The Free plan includes 1,000 screenshots a month with no card. Paid plans start at $5 for 3,000 screenshots; every feature is on every plan.

Create a free ScreenshotNeo account to start with 1,000 screenshots a month and no card.

Frequently Asked Questions

Can one wkhtmltopdf command convert more than one HTML input?

Yes. wkhtmltopdf accepts one or more HTML pages as inputs and writes them into a single PDF, so you can use separate source pages when that better matches your report architecture.

What is the difference between a PDF outline and a visible table of contents?

An outline is the navigable hierarchy shown by a PDF viewer and is generated from headings with --outline. A visible table of contents is printed content generated through a toc object or authored HTML; enabling one does not automatically create the other.

Quick Recap

Bestseller No. 1

Epson EcoTank ET-2800 Wireless Color All-in-One Supertank Printer - Black

$239.99

SaleBestseller No. 2

Epson EcoTank Photo ET-8550 Wireless Wide-Format All-in-One Tank Printer

$689.90

Bestseller No. 3

HP Smart Tank 5000 Wireless All-in-One Ink Tank Printer, Scanner, Copier with 2 Years of Ink Included, Best-for-Home, Cartridge-Free, Refillable and AI-Enabled. (5D1B6A)

PREMIUM SUPPORT - Strong technical expertise to solve issues faster; THE LAST PRINTER YOU'LL EVER NEED. Enjoy years of refillable, cartridge-free printing.

$180.49

Bestseller No. 4

NDYIN Portable Printers Wireless for Travel, N80 Bluetooth Thermal Printer

$41.99

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.