Fix Incorrect Page Breaks When Converting HTML to PDF
Fix misplaced PDF page breaks by checking print CSS, applying break rules at the right elements, and accounting for renderer behavior and content size.
To fix incorrect page breaks when converting HTML to PDF, first identify the renderer and inspect the CSS it uses for print. Then put forced breaks at section boundaries that must begin on a new page, and use break-inside: avoid for compact blocks that should stay together. These rules guide pagination; they cannot keep content intact when it is taller than the printable page, and different renderers can behave differently.
The exact correction depends on your conversion engine, version, HTML structure, print styles, and PDF options. Start with the diagnostic steps below, make one small CSS change, regenerate the PDF, and inspect the affected pages.
1. Identify the renderer and print mode
Record the converter and version before changing styles. Common setups include Chromium through Puppeteer and the WeasyPrint library. Do not assume that a rule or layout feature behaves identically across engines.
Check whether conversion uses print styles. Puppeteer’s page.pdf() uses the print CSS media type by default. If your screen layout looks correct but the PDF does not, inspect @media print rules and styles that differ between screen and print. Puppeteer documents the print behavior and the option to emulate screen media in its PDF API reference.
2. Apply the smallest appropriate break rule
Use a forced break when a particular boundary must start a page. Use an avoidance rule when an element should preferably remain together if it fits. The modern properties are break-before, break-after, and break-inside. Legacy page-break-* properties are compatibility aliases in conforming implementations; check your renderer’s documentation if an older engine is involved. See the CSS Fragmentation specification.
@media print {
/* Start each major section on a fresh page. */
.new-section {
break-before: page;
page-break-before: always; /* legacy compatibility */
}
/* Keep a compact card, figure, or item together when it fits. */
.keep-together {
break-inside: avoid;
page-break-inside: avoid; /* legacy compatibility */
}
/* Avoid a single orphaned line at a page edge. */
p {
orphans: 3;
widows: 3;
}
}Use semantic boundaries such as chapter headings or report sections for forced breaks. Avoid applying break-before: page to every heading if some headings should continue on the same page. Put break-inside: avoid on the smallest meaningful component that should stay intact, rather than a large wrapper containing several pages of content.
What each property controls
| Property | Use it for | Example value |
|---|---|---|
break-before |
Force or discourage a break before an element | page, avoid-page, auto |
break-after |
Force or discourage a break after an element | page, avoid-page, auto |
break-inside |
Discourage splitting an element across pages | avoid, avoid-page, auto |
orphans |
Set a minimum number of paragraph lines at the bottom of a page | 3 |
widows |
Set a minimum number of paragraph lines at the top of a page | 3 |
For page boundaries, break-before: page is the direct modern form. The older page-break-before: always remains useful where compatibility with older stylesheets or renderers is needed. W3C’s CSS 2.2 paged media specification describes forced and avoided breaks, paragraph widows and orphans, and how the available break points affect pagination.
3. Check page size, margins, and content height
A keep-together rule is a preference in the fragmentation process, not a guarantee that an arbitrarily tall box will fit. If an element is taller than the printable area, the renderer must find a way to paginate or overflow it. CSS 2.2 explains that constraints can be relaxed when there are not enough break opportunities to prevent overflow. See the W3C paged media specification.
Check the page size and margins in both CSS and your converter options. Together, they determine the space available to content. A title, image, table, or card that nearly fills a page may be pushed to the next page by a small change in font metrics or margin. If a component is too tall, consider splitting it at a meaningful point, reducing its content or dimensions, or allowing it to span pages.
@page {
size: A4;
margin: 18mm;
}
@media print {
.report-section {
break-before: page;
}
.summary-card {
break-inside: avoid;
}
}The sample establishes a page size and margins, then applies a forced section boundary and a keep-together preference. Adapt it to the document and the actual renderer; it is not a tested fix for a particular PDF.
4. Render and inspect the affected pages
- Generate a PDF with the current styles and save a copy of the output.
- Inspect the page before and after the wrong break. Note whether the issue is a heading stranded at the bottom, a split component, an unexpected blank page, or a forced break that did not occur.
- Check the computed print styles for the elements around the boundary. Confirm the selector matches the rendered elements and look for a more specific rule overriding it.
- Change one rule at a time, regenerate the PDF, and compare the same pages.
- If the rule appears ignored, check support for that property and layout in the exact engine and version.
Puppeteer users can inspect the print output produced by page.pdf(); it uses print media by default. If you intentionally need screen media, Puppeteer documents calling page.emulateMediaType('screen') before PDF generation. This changes which styles apply, so use it only when screen styling is the intended output.
5. Check renderer support
Renderer support is feature-specific. WeasyPrint’s stable API reference documents page break properties and aliases as well as orphans and widows. It also records limitations in other areas, so support for page breaks does not imply identical behavior for every layout feature. Check the documentation for your installed version and the particular layout involved.
If the needed rules are unsupported or the renderer’s behavior does not suit the document, compare alternatives against the specific requirements: page-level break support, print media behavior, page size and margins, oversized elements and tables, and deployment constraints. The available evidence does not establish a universally best renderer or provide comparable speed and price benchmarks.
Common page-break problems and fixes
| Symptom | Likely cause | What to check or change |
|---|---|---|
| A section starts halfway down a page | No forced break is applied at its boundary | Add break-before: page to the section, inside print styles if appropriate. |
| A small card or figure is split | No avoidance rule applies, the selector misses, or the renderer does not support the layout as expected | Apply break-inside: avoid to the component and verify the matching print rule. |
A large block still splits despite avoid |
The block cannot fit in the available page area, so the renderer must relax constraints | Reduce or split the content, adjust page dimensions or margins, or allow a sensible internal break. |
| A heading is left at the bottom with no following content | The heading and following block are not kept together | Group them in a wrapper and try break-inside: avoid, or apply a suitable break rule to the following block. Verify the result in the target engine. |
| CSS works in the browser but not in the PDF | PDF generation uses print media, different options, or a different renderer/version | Inspect @media print, page settings, and the converter’s documentation. |
| A blank page appears after a forced break | Break rules may be applied at adjacent boundaries, or the content naturally filled the previous page | Inspect both neighboring elements for forced breaks and check whether a break is being applied twice. |
| Legacy rule seems ignored | The stylesheet relies on an alias or value with different support in the selected engine | Try the modern break-* property and verify support for the installed version. |
Performance, reliability, and cost considerations
Pagination is layout work: large documents and complex content can require more rendering effort, but the cited renderer and standards documentation does not provide a universal speed benchmark. Avoid repeated forced breaks and overly broad keep-together rules that create awkward gaps or push large sections forward. For reliable output, pin the renderer version in your deployment, keep a representative HTML document and PDF for visual review, and regenerate the PDF after changes to fonts, styles, content, or page settings.
Cost depends on the converter and hosting arrangement you choose; the research sources do not establish comparable prices. If changing renderers, compare the operational cost and deployment requirements alongside pagination support. For a hosted screenshot or PDF workflow, ScreenshotNeo’s product details and options are available at ScreenshotNeo and its API documentation.
Or skip the browser setup
ScreenshotNeo accepts a URL in one GET request and can return a screenshot or PDF. This is useful when the page is already hosted and you want a capture without maintaining browser setup. For an HTML-to-PDF document, first publish the HTML at a URL and configure the PDF options for the output you need.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.pdfSee the ScreenshotNeo API documentation for PDF options. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. Sign up for free.
FAQ
Will break-inside: avoid always keep an element on one page?
No. It discourages a break where possible, but an element that cannot fit in the printable area may still be split or overflow.
Should I use page-break-before or break-before?
Use the modern break-before property, and add the legacy alias if compatibility with an older renderer or stylesheet requires it. Verify behavior in the engine that generates the PDF.
Why does the PDF differ from the screen?
The converter may render print media and apply different print styles, page dimensions, margins, or font metrics. Inspect the actual print stylesheet and generation settings.
What information is needed to diagnose a specific bad break?
The renderer and version, the relevant HTML and CSS, PDF options, and a representative page showing the problem. Without those details, a general pagination rule cannot guarantee a specific correction.
