Controlling Page Breaks

Paged.js paginate your document. You do not. This is the correct division of labor — asking a designer to manually place page breaks through a hundred-page document would be neither efficient nor reliable — but it does not mean the designer is passive. The CSS Paged Media specification provides a rich set of properties for controlling where breaks happen: forcing them before certain elements, preventing them within others, ensuring that specific elements stay together on the same page, and controlling the minimum number of lines that must appear above or below a page break within a paragraph. Used well, these properties produce a document that feels as though its pagination was designed. Used carelessly or not at all, you get a document that feels as though the text fell onto pages at random, with headings at the bottom of pages and orphaned lines at the top.

This chapter covers the break properties in full, explains widows and orphans in precise terms, shows how to keep related elements together, and ends with a practical guide to debugging the pagination problems that appear when a real document is paginated for the first time.

· · ·

The break properties Forcing and preventing breaks

CSS provides three break properties that control how content interacts with page boundaries: break-before, break-after, and break-inside. Each accepts a set of keyword values that determine what the browser should do at that boundary.

break-before controls what happens immediately before an element. The most commonly used values are page (force a page break before this element), right (force a page break before, and ensure the new page is a recto), left (same, but verso), and avoid (avoid a page break immediately before this element if possible). The right and left values are essential for chapter management — every chapter opener in a well-produced book starts on a recto page, and break-before: right guarantees this without manual intervention.

break-after works identically to break-before but controls what happens immediately after the element. It is less commonly needed — most forced breaks are more naturally expressed as break-before on the following element — but it is useful when you want to ensure a specific element (a chapter summary, for instance) always ends on a page by itself.

break-inside controls what happens within an element, at any potential break point inside it. The most important value is avoid, which prevents the browser from placing a page break inside the element. This is the property you apply to figure-caption pairs, callout boxes, table rows, short reference entries, and any other element that must remain intact on a single page. The value avoid-page is more specific — it prevents page breaks but allows column breaks — useful in multi-column layouts where the same element should be able to break across columns but not across pages.

Property and value	What it does	When to use it
break-before: page	Forces a page break immediately before the element	New sections, parts, appendices that must begin on a new page but can be either recto or verso
break-before: right	Forces a break and ensures the new page is a recto (odd-numbered)	Chapter openers — always start on a right-hand page
break-before: left	Forces a break and ensures the new page is a verso (even-numbered)	Occasionally used for sections that conventionally open on a left page
break-before: avoid	Asks the browser to avoid a page break immediately before this element	Headings — avoid a heading at the bottom of a page without following text
break-after: page	Forces a page break immediately after the element	Prefaces, dedications, or sections that should occupy their own page
break-inside: avoid	Prevents any page break from occurring within the element	Figures with captions, callout boxes, table rows, short reference entries
break-inside: avoid-page	Prevents page breaks within the element but allows column breaks	Elements within multi-column layouts that should stay on one page but can span columns

· · ·

Widows and orphans The lines that should not be left alone

Widows and orphans are specific kinds of typographic accidents that occur when paragraphs are divided by page breaks in ways that leave very short remnants isolated on a page. The definitions are precise, and the terms are sometimes confused: an orphan is a single line at the bottom of a page — the opening line of a paragraph that has been separated from the rest of the paragraph, which continues on the next page. A widow is a single line at the top of a page — the final line of a paragraph that has been separated from the body of the paragraph, which ended on the previous page.

Both are undesirable, for slightly different reasons. An orphan at the bottom of a page is visually abrupt — the paragraph begins and is immediately cut off, leaving the reader with a sense of incompleteness at the point of turning the page. A widow at the top of a page looks stranded and lonely — a single short line, often very short if it contains the last few words of a sentence, floating in the upper portion of the page with no context. Both disrupt reading and both signal careless typography.

CSS controls widows and orphans with two properties of the same names. orphans specifies the minimum number of lines of a paragraph that must remain at the bottom of a page (i.e., the minimum number of lines that can be orphaned). widows specifies the minimum number of lines that must appear at the top of the next page (i.e., the minimum number that can be widowed). The values are integers.

The typographic standard is a minimum of two for both — no single orphaned or widowed line is acceptable. A more refined standard, used in fine book printing, is three: at least three lines must appear at both the bottom and top of any page break within a paragraph. For most document work, two is appropriate and three is a luxury. Setting both to two prevents the most visible problems without making the browser's pagination task so constrained that it struggles to satisfy all the requirements simultaneously:¹

/* ── Widow and orphan control ─────────────────── */
p {
  orphans: 2; /* min 2 lines at bottom of page */
  widows:  2; /* min 2 lines at top of page   */
}

/* More conservative for fine printing            */
p {
  orphans: 3;
  widows:  3;
}

· · ·

Keeping elements together Figures, captions, callouts, and headings

Beyond widow and orphan control — which applies to individual lines within paragraphs — there are whole elements that must stay together on a single page. The most common are figure-caption pairs, callout boxes, and headings with their following paragraphs. Each requires a slightly different approach.

A figure with its caption should almost always stay together. A figure at the bottom of one page and its caption at the top of the next is confusing and unprofessional. The correct solution is to wrap the figure and caption in a single container element — a <figure> element, typically — and apply break-inside: avoid to it. If the figure-caption pair is too tall to fit on the remaining space of the current page, Paged.js will move the entire unit to the next page, leaving a gap at the bottom of the current page. This gap is preferable to a split figure-caption pair. If the gap is large and visually awkward, it may be worth restructuring the content so the figure appears at a more natural break point, or redesigning the figure to be shorter.

A callout or sidebar box should similarly never split across a page. The visual enclosure of a box — its border, its background tint — loses its meaning if it appears at the top of one page and the bottom of the next. Apply break-inside: avoid to the callout container. If the callout is very tall, the gap it creates may be visible, but this is still preferable to the alternative.

A heading and its following paragraph present a subtler problem. The heading itself should not be at the bottom of a page — that is the job of break-before: avoid. But even with break-before: avoid in place, the heading could appear at the top of a page followed immediately by a page break, leaving only the heading and one orphaned line. A more robust solution is to use a combination of break-before: avoid on the heading and orphans: 3 on the paragraph — ensuring the heading is always followed by at least three lines before any break. Alternatively, the heading and its first paragraph can be wrapped in a container with break-inside: avoid, though this requires additional markup.

/* ── Keeping elements together ─────────────────── */

/* Figure + caption always on same page            */
figure {
  break-inside: avoid;
  margin:       var(--space-lg) 0;
}

/* Callout box never splits                        */
.callout {
  break-inside: avoid;
}

/* Headings never strand at page bottom            */
h2, h3 {
  break-before: avoid;
  break-after:  avoid;
}

/* Tables: rows never split                        */
tr {
  break-inside: avoid;
}

/* Reference entries (bibliography, index)         */
.bib-entry, .index-entry {
  break-inside: avoid;
}

/* Chapter openers: always start on recto          */
.chapter-opener {
  break-before: right;
}

/* Widow and orphan minimum for all paragraphs     */
p {
  widows:  2;
  orphans: 2;
}

· · ·

Debugging pagination Finding and fixing break problems

When a Paged.js document is first paginated, it almost always has at least a few break problems — headings at the bottom of pages, awkward gaps left by large break-inside: avoid elements, orphaned lines that the widow/orphan settings did not catch, or chapter openers that landed on verso pages despite break-before: right. Debugging these problems is part of the workflow, and there are reliable strategies for approaching it.

The first tool is the Paged.js browser preview itself. Open the document in Chrome or Chromium (Paged.js produces the most consistent output in Chromium-based browsers) and zoom to a comfortable reading scale. Read through the pages looking for the following specific problems in order of severity: chapter openers on wrong-hand pages; headings at the bottom of pages; figures or callouts split across pages; isolated lines at the top or bottom of pages; large unexplained gaps.

When you find a problem, identify its cause before applying a fix. A heading at the bottom of a page is likely a missing break-before: avoid on that heading level. A split figure is likely a missing break-inside: avoid on the figure container. A large gap is likely a break-inside: avoid element that was too large to fit on the remaining space of its page — the fix may require either reducing the element's height or accepting the gap.

One class of problem deserves special attention: the case where the browser satisfies break-inside: avoid on a large element by pushing the entire element to the next page, leaving a very large gap on the current page. This often happens with tall callout boxes or large figures. The gap is formally correct — the break-inside constraint is satisfied — but visually it looks like a mistake. The practical remedies are: reduce the element's height, move it earlier in the text so it falls higher on the page, or split it into two smaller elements. In a pinch, adding a targeted break-inside: auto override for that specific element allows it to split across the page, which may look better than a large gap.²

A useful debugging technique is to add a temporary CSS rule that highlights all page break points:

/* ── Debug: show page boundaries ────────────────
   Add temporarily, remove before final output   */
.pagedjs_page {
  outline: 2px solid rgba(255, 0, 0, 0.15);
}

/* Show content areas within pages               */
.pagedjs_page_content {
  outline: 1px solid rgba(0, 100, 200, 0.15);
}

/* Highlight margin boxes                        */
.pagedjs_margin {
  background: rgba(107, 79, 44, 0.04);
}

Paged.js adds these classes to its generated DOM — each page is a .pagedjs_page element containing a .pagedjs_page_content div and margin box divs — so these selectors work reliably for visualising the page structure during development. Remove the debug rules before generating the final PDF.

/* ════════════════════════════════════════════
   Break controls — The Compositor's Garden
   ════════════════════════════════════════════ */

/* Widow and orphan minimum                     */
p {
  widows:  2;
  orphans: 2;
}

/* Headings: never at page bottom               */
h2 {
  break-before: avoid;
  break-after:  avoid;
}

/* Chapter openers: always recto                */
.chapter-opener {
  break-before: right;
}

/* Figures: image + caption together            */
figure {
  break-inside: avoid;
}

/* Callout boxes: never split                   */
.callout {
  break-inside: avoid;
}

/* Planting calendar entries (Ch. 3 two-column) */
.plant-entry {
  break-inside: avoid;
}

/* Blockquotes: avoid splitting mid-quote       */
blockquote {
  break-inside: avoid;
}

/* Section separators (· · ·): never orphaned  */
.sep {
  break-before: avoid;
  break-after:  avoid;
}

/* Back matter sections start on new page       */
.notes-section,
.bibliography,
.colophon {
  break-before: page;
}

· · ·

Break control is where the mechanical process of pagination meets the craft of typography. The CSS properties exist to make the browser's pagination agree with what an experienced typographer would have done by hand — moving a heading to the next page here, holding a figure together there, ensuring that no line is left to stand alone at the top or bottom of a page. The goal, as always, is a document that reads without friction, where the reader is never jarred by a structural accident that the designer could have prevented.

With the break controls in place, the pagination layer of the project is complete. Chapter 19 covers what comes next: generating the final PDF, understanding what Paged.js produces versus what professional pre-press requires, and making the output ready for print or for distribution.