The usual fix is structural, not another CSS declaration. wkhtmltopdf uses an old WebKit/Qt pagination engine with known edge cases. A valid page-break-before, page-break-after or page-break-inside rule can be defeated by a floated ancestor, an overflow constraint, print-media differences, a table row, or content that is taller than a page. Start with a small block-level test, remove those constraints, and place an explicit break marker between ordinary sections.
This guide shows a repeatable diagnostic sequence, working HTML/CSS patterns, command-line checks, failure recovery and the point at which changing renderers is more sensible than fighting wkhtmltopdf.
Why wkhtmltopdf ignores a rule that looks correct
wkhtmltopdf is not a modern browser. Its WebKit/Qt pagination code predates current CSS fragmentation behavior, so support is partial and context-sensitive. The Debian manual warns that WebKit can cut a line across pages and that patched Qt improves page-break-inside only “somewhat.” In practice, the CSS may parse correctly while the layout tree gives the paginator no usable boundary.
The most important diagnostic is the ancestor of the element carrying the rule. A 2014 wkhtmltopdf report (#1604) describes the symptom precisely: “Page-breaks do not happen when the parent div floats.” Another report (#2371) identifies overflow:auto as problematic and recommends overflow:visible on the affected parent. These are engine limitations, not evidence that the declaration is misspelled.
#1 Best Overall
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
Pagination also depends on which stylesheet is active. The --print-media-type option switches wkhtmltopdf to print media; report #5284 shows that this can change assets and other CSS, not merely page-break declarations. Test the complete print layout. Finally, table rows are a poor place to force a break: report #2997 records ignored breaks on large tr elements and rows splitting across pages.
Build a two-section test case first
Before changing a production template, reduce it to two or three normal block sections. Put the break on a separate marker between them, not on a complicated component. This tells you whether wkhtmltopdf can paginate the basic structure at all.
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<style>
@page { size: A4; margin: 18mm; }
body { font: 12pt/1.4 Arial, sans-serif; }
.chapter { min-height: 120mm; }
.pdf-break {
page-break-before: always;
break-before: page;
height: 0;
clear: both;
}
</style>
</head>
<body>
<section class="chapter">
<h1>First section</h1>
<p>Content that should appear on page one.</p>
</section>
<div class="pdf-break" aria-hidden="true"></div>
<section class="chapter">
<h1>Second section</h1>
<p>Content that should start on a new page.</p>
</section>
</body>
</html>Render this file with the same binary and options used in production. If the marker works here but not in the real document, reintroduce wrappers and components one at a time until the conflicting ancestor is found.
Fix the layout in diagnostic order
1. Remove floats around the break
Do not put a forced break inside a floated container. For PDF output, override the float on the relevant ancestor and clear preceding floats:
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minute.pdf-output .float-parent {
float: none !important;
}
.pdf-output .pdf-break {
clear: both;
}Keep the override scoped to the PDF template or a class on body; changing the screen layout globally can create new regressions. If removing the float restores the break, replace the float-based layout with ordinary block flow for print, or move the break outside the floated region.
2. Remove restrictive overflow
A scrolling or clipped ancestor can prevent the paginator from seeing a clean boundary. Temporarily apply:
.pdf-output .overflow-parent {
overflow: visible !important;
}Check every ancestor, not only the element with page-break-before. Values such as auto and hidden are especially suspicious. Once the PDF is correct, restore clipping only where it is genuinely required and verify that it does not reintroduce the failure.
3. Verify print-media selection
If your break is inside @media print, render with the intended media mode:
Rank #3
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
wkhtmltopdf --print-media-type input.html output.pdfWithout that option, a rule that exists only in the print block may not be selected. With it, other print-only assets and layout rules may also replace screen styles, so inspect the whole document rather than assuming the break declaration is the only difference. Keep essential structural styles outside the media block when both screen and PDF output need them, and use the print block for controlled overrides.
4. Move the break out of table rows
Do not rely on page-break-before or page-break-after on tr. Large rows may split, and wkhtmltopdf may ignore a break attached to the row altogether. Better choices are:
- Place a break marker immediately before the table.
- Split one long table into separate tables with a marker between them.
- Group related rows in separate block-level sections and break between groups.
- Accept row splitting when the table must remain continuous, then design headers and row content so a cut is readable.
A marker between two independent tables is more predictable than a declaration on a table-internal box.
5. Do not ask an oversized element to stay together
page-break-inside: avoid is a preference, not a way to create a page larger than the paper. If an element is taller than one page, wkhtmltopdf must split it or produce awkward output. Divide long chapters, lists, cards and code listings into smaller blocks that can be cut at sensible points:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
.pdf-card {
page-break-inside: avoid;
break-inside: avoid;
}
.pdf-card + .pdf-card {
margin-top: 8mm;
}Use this on moderate-sized blocks. Do not wrap an entire report in one “avoid” container and expect it to remain intact.
6. Test other layout contexts as hypotheses
The cited reports establish float and overflow failures. Positioned elements, transformed ancestors, flex layouts and table-containing blocks can also behave differently between WebKit builds, so treat them as diagnostic hypotheses rather than guaranteed causes. Temporarily simplify each context:
- Replace a flex or grid wrapper with ordinary block flow.
- Remove
positionandtransformfrom ancestors around the marker. - Move the marker outside nested tables and positioned overlays.
- Render after each change so the first change that restores pagination identifies the constraint.
Use a dedicated PDF break pattern
A reusable marker keeps pagination policy separate from content components. The legacy page-break-before property is the documented CSS 2.2 mechanism. Adding break-before: page is a useful progressive declaration, but support is not verified uniformly across wkhtmltopdf builds, so retain the legacy property.
.pdf-break {
display: block;
height: 0;
margin: 0;
padding: 0;
border: 0;
clear: both;
page-break-before: always;
break-before: page;
}
@media screen {
.pdf-break { display: none; }
}Place the marker between block-level siblings. Avoid inserting it inside a paragraph, a table row, or a floated component. If a heading must begin a new page, put the marker immediately before the heading’s containing section rather than applying the break to an inline heading inside a complex wrapper.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Best Value
Check the command and the generated PDF
- Confirm the input file opened successfully on its own and that all local assets use paths accessible to wkhtmltopdf.
- Run the minimal test without JavaScript or custom headers. This isolates pagination from loading problems.
- Add your production flags one at a time, including
--print-media-type, so a changed media mode or asset cannot be mistaken for a CSS failure. - Open the PDF at 100% zoom and check page boundaries, not only the first forced break. WebKit can cut a line across pages even when an explicit marker works.
- Record the exact wkhtmltopdf binary, Qt build, command and HTML revision. A different packaged build can paginate the same markup differently.
Troubleshooting common symptoms
| Symptom | Likely cause | Correction |
|---|---|---|
| The marker is ignored only inside one component | A floated ancestor or a nested overflow constraint | Set the PDF ancestor to float:none and overflow:visible; move the marker outside the component if necessary. |
| The rule works without print CSS but fails in production | Different media selection or a print rule overriding layout | Render with the intended --print-media-type setting and inspect the complete print stylesheet. |
A break on tr does nothing |
Table-row pagination is unreliable in wkhtmltopdf | Break before the table, between separate tables, or between block-level row groups. |
page-break-inside: avoid still splits content |
The element is taller than a page, or the engine can only honor the rule partially | Split the content into smaller blocks and choose clean cut points. |
| The first page is correct but later pages drift | Unbreakable content, floats, or line-height changes accumulating through the document | Remove layout constraints, shorten oversized blocks and inspect each page boundary in a reduced fixture. |
| Screen and PDF layouts disagree | Print-media rules or assets differ from screen rules | Keep shared structural CSS in the base stylesheet and make print-only changes explicit. |
When to stop tuning wkhtmltopdf
wkhtmltopdf’s GitHub repository is archived and read-only. That means a persistent pagination defect may be an engine limitation rather than a missing declaration. After you have removed floats and restrictive overflow, verified media selection, moved breaks out of table rows and divided oversized blocks, compare the document in a maintained renderer if stable pagination is a requirement.
Evaluate a replacement against the properties that matter to your document: CSS fragmentation, table and flex pagination, JavaScript compatibility, font and asset handling, reproducibility in CI, licensing and deployment footprint. No single alternative can be called a universal winner without testing your templates and fonts.
Or skip the browser setup
If your actual goal is a clean image or PDF of a URL rather than maintaining a local wkhtmltopdf pipeline, ScreenshotNeo provides a single HTTP request. It accepts cookie and consent banners like a visitor, removes more than 60 known consent platforms plus newsletter popups and chat widgets before capture, and lets you turn each cleanup step off. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed; the response identifies the result with X-Page-Verdict and X-Billed headers. It also offers an MCP server with take_screenshot, get_page_info and capture_pdf for Claude, Cursor and other MCP clients.
Use the API documentation at https://screenshotneo.com/docs/ for all options. The same endpoint supports full-page captures with lazy images loaded, CSS-selector element capture, dark mode, device presets or custom viewports, retina scale, PDF paper size and margins, custom CSS and JavaScript, clicks, selector or network-idle waits, request and resource blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, selectable cache TTLs, signed image links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage reporting and an OpenAPI specification.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpPython
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://example.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);Every feature is included on every plan. The Free plan includes 1,000 shots per month with no card; paid plans are Starter ($5 for 3,000), Growth ($15 for 15,000), Pro ($39 for 60,000), Scale ($99 for 250,000) and Business ($249 for 1,000,000). Yearly billing gives two months free. Create a free ScreenshotNeo account to start with 1,000 screenshots a month and no card.
Frequently Asked Questions
Should I use only break-before in new CSS?
Keep page-break-before in wkhtmltopdf styles and add break-before as a progressive companion. Builds differ, so verify the generated PDF rather than relying on the newer property alone.
Can a forced break repair a page that contains a very tall table row?
No. A break marker controls where the next block starts; it cannot make an oversized row fit. Split the table into smaller groups or accept a row split.
Why does the same HTML paginate differently on two machines?
The wkhtmltopdf binary, Qt build, fonts, command-line options and available assets all affect layout. Record and reproduce those inputs in CI.
Recommended Free Tools
Quick Recap
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.
