How to Prevent Page Breaks in a Website PDF for Client Documentation

Use print-specific CSS to ask the browser to keep compact content blocks together when it paginates a website for PDF. The key rule is break-inside: avoid, applied to the figure, card, or other logical unit that should stay intact. Add @page to set page size and margins when needed, then inspect the browser’s print preview or resulting PDF: break avoidance is a request, not a guarantee, especially when a block is taller than the available page area.

1. Add print CSS for the blocks that must stay together

Put the rules in a stylesheet loaded by the page, or in a <style> element. Replace the example class with selectors from your document. Keep the rule scoped to compact units, such as a figure and caption or a short documentation card.

<article class="client-doc">
  <h1>Integration overview</h1>
  <p>A short introduction to the integration.</p>

  <figure class="keep-together">
    <img src="/images/flow.png" alt="Request flow">
    <figcaption>Figure 1. Request flow</figcaption>
  </figure>

  <section class="client-documentation-card keep-together">
    <h2>Authentication</h2>
    <p>Send the API key in the authorization header.</p>
  </section>
</article>

@media print {
  figure,
  .client-documentation-card,
  .keep-together {
    break-inside: avoid;
    page-break-inside: avoid; /* legacy alias for older print styles */
  }

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

  nav,
  .screen-only,
  button {
    display: none !important;
  }
}

@page {
  size: auto;
  margin: 16mm;
}

The first declaration is the modern property. page-break-inside: avoid is a legacy alias for the common avoid value and can be retained when supporting older stylesheets or workflows. The heading rule asks the browser not to leave a heading stranded at the bottom of a page. Hiding navigation and controls removes screen-only elements from the printed version. [MDN: break-inside] [MDN: Printing with CSS]

2. Choose page geometry and print-only presentation

@media print lets you change the page’s presentation for printing or PDF output without changing its screen layout. Use it to adjust widths, spacing, colors, and visibility of elements that do not belong in client documentation. Use @page for page dimensions, orientation, and margins. For example, a landscape page can help with wide tables, while a larger margin can make room for notes or binding. Check how those choices affect available content area: narrower content or larger margins can cause blocks to move to the next page.

@media print {
  .client-doc {
    max-width: none;
    color: #111;
    background: white;
  }

  .sidebar,
  .toolbar,
  .screen-only {
    display: none !important;
  }
}

@page {
  size: A4 portrait;
  margin: 16mm;
}

Set the size and margins to match the target workflow rather than treating these values as universal. The browser’s print dialog may also offer paper and scaling settings that affect pagination. [MDN: CSS paged media]

3. Apply break rules to the right element

• Figure and caption: Put break-inside: avoid on the figure wrapper so the image and caption are treated as one unit.
• Short card or callout: Apply the rule to the card itself when its contents should stay together.
• Heading and following content: Avoid a break after headings, and structure the heading with its associated section. A heading rule alone does not keep an entire following section together.
• Long tables or code listings: Do not force an entire long table or listing to fit as one block. Let it fragment where sensible, or divide it into smaller semantic units.

break-inside affects breaks inside the element’s generated box. If the selector targets the wrong wrapper, or the element does not generate a box, the expected effect may not occur. Forced break rules at a break point take precedence over avoidance. [MDN: break-inside behavior and precedence]

4. Inspect the PDF and refine the layout

1. Open the page in the browser and use its print preview or save-to-PDF flow.
2. Check the specific page break you intended to prevent, along with headings, figures, tables, and footers.
3. Confirm the print stylesheet is loaded and the selector matches the actual block.
4. Check for more specific print rules or forced breaks that override the avoid rule.
5. Review page size, orientation, margins, and scaling; these change how much content fits.
6. If the block is taller than the available printable area, let it split or redesign it into smaller units.

Browsers control pagination, and fragmentation controls are suggestions when obeying them is feasible. An oversized block cannot be made to fit on one page merely by setting break-inside: avoid. [MDN: Handling content breaks]

5. Common problems and fixes

Symptom	Likely cause	What to check
A figure still splits from its caption	The rule is on a child or unrelated wrapper rather than the figure’s principal box, or a conflicting rule applies.	Put the rule on the figure wrapper, inspect the matching print selector, and look for forced breaks.
The rule has no visible effect	The element may not generate a box, the print stylesheet may not be active, or the selector may not match.	Check the element and stylesheet in print mode and confirm the declaration wins the cascade.
A heading is left at the bottom of a page	Avoidance was applied to the wrong boundary, or the heading is not grouped with the content it introduces.	Use break-after: avoid-page on headings and review the section structure.
A card moves but still overflows or splits	The card is taller than the printable area or page geometry leaves too little room.	Reduce its content, adjust margins or orientation, or split it into smaller blocks.
Screen layout looks right but PDF layout does not	Print styles intentionally change dimensions or visibility, or the print dialog uses different paper and scaling settings.	Inspect print preview with the target paper size, orientation, and scale.
A legacy stylesheet behaves differently	It may rely on the older property name or browser-specific print behavior.	Use modern break-inside for new rules and retain the legacy alias where older workflows need it; verify the target browser’s output.

6. Performance, reliability, and cost

These CSS rules do not require a screenshot or PDF service; they use the browser’s print and paged-media layout. The main reliability work is visual validation in the browser and PDF workflow your clients use, because page geometry and pagination can change the result. No single declaration guarantees that every block remains unbroken. Keep print rules focused so the browser can paginate long content sensibly.

7. Capture a screenshot of the page for client records

A screenshot can document the page’s appearance alongside its PDF. For a local browser-based capture, open the page in the browser, set the desired viewport, and use the browser’s screenshot or developer tools workflow. Screenshot is a visual record; use the print preview or saved PDF itself to verify pagination.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. A single GET request can return a screenshot as PNG, JPEG, or WebP, or a PDF. This example captures the reference page as a PDF; see the ScreenshotNeo API docs for request options and formats.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -d format=pdf -o client-reference.pdf

ScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before the shot; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots, and every feature is on every plan.

Sign up free for 1,000 screenshots a month, with no card required.

FAQ

Does break-inside: avoid guarantee no page break?

No. It asks the browser to avoid a break inside the box when possible. Pagination constraints can still require a split.

Should I use page-break-inside or break-inside?

Use break-inside for new CSS. The older page-break-inside name is a legacy alias for common values such as avoid.

Can I keep a whole long article on one page?

That is usually impractical if it exceeds the printable page area. Keep compact units together and allow long content to flow across pages.

Does a screenshot confirm the PDF has no splits?

No. A screenshot records a viewport. Inspect print preview or the generated PDF to check pagination.