Configuration: widows, orphans and balancing

#Orphans, widows, runts, and keep-together rules

See Hyphenation & Justification for the mechanics behind these demerits. This section is the reference for the bodyText keys that drive them.

Beyond hyphenation and spacing bounds, the body-text configuration exposes the soft rules that prevent structurally awkward paragraph breaks. All of these are fed into the Knuth-Plass line-breaking algorithm as demerits — they bias the layout toward clean breaks without ever forcing a hard rule. Set the *Penalty values to 0 to effectively disable any one of them.

About runts. A runt is a paragraph whose last line is too short to feel like a proper line of text — typically one or two short words marooned at the end of a paragraph. Because the check is based on the pixel length of the line relative to the normal space width, runtMinCharacters adapts automatically to the current font size. A short word that is visually wider than runtMinCharacters × spaceWidth is fine; a word that is narrower than that (or truly alone) attracts the runt penalty. The threshold counts word spaces, which are about half as wide as letters: the default 20 is a last line of roughly 8 to 12 letters. Every runt costs the whole penalty, so among two endings under the threshold the breaker keeps the tighter lines above; gradedRuntPenalty prices each by its shortfall instead, and the longer ending wins. For the mathematically curious: at the default runtPenalty of 1000, avoiding a runt dominates any alternative break set requiring up to roughly r≈2.15 word-spacing stretch.

Soft, not hard. None of these rules can prevent a break — the engine will always produce a layout. They are demerits: the algorithm trades off badness, hyphenation cost, fitness-class smoothness, and these structural penalties in a single global optimisation and picks the break set with the lowest total cost. If you need a harder guarantee, raise the penalty; if a given document reads better with the penalty relaxed, lower it.

#Column balancing

Publishers expect every column to start at the top of the page and end flush with its bottom. Break rules (orphan/widow protection, headings kept with their text, unsplittable figures) naturally leave short columns — one or more empty baseline-grid lines at the bottom. When balancing is enabled, the engine does what a compositor would, applying its levers in editorial priority order:

1. A box closing the column — a callout that ends a short column is pushed down by the exact room under its foot, so its bottom edge lands on the last grid slot of the page, level with the last line of the column beside it. It takes that room even when it is less than a line, as long as nothing moves into another column. By default it runs before every other lever and takes the whole gap, so a box that annotates the paragraph above it can end up several lines below it; closingBox: 'last' lets the headings, the list ends and the other spacing levers take the whole lines first, and the box only what they leave, and closingBox: 'off' never moves it.
2. Pictures with a safe area — a picture with a safe area (Resource.safeArea, see Document format › Safe area) set inline in the short column, or floated at its head or its foot over that column alone, grows by whole grid lines, cropped within its safe area, until the column is full or the crop reaches the safe area. A taller picture leaves no hole on the page, so it runs before any space is added; a float at the head of a column on a page or band whose column heads stay level (see below) does not grow. Recorded as flexFigure. It has no setting of its own: only a picture whose resource marks a safe area can grow.
3. Headings — whole grid lines are added to the top margin of the headings inside the short column. When several lines are needed and the column holds several headings, the lines are distributed among them, always giving the largest share to the most important heading (an h2 receives more than an h3). Headings sitting at the very top of a column never receive extra space, so columns keep starting at the page top — except a heading right under a figure or table that heads its column on a page that flows on: the room goes above that heading, under the figure. A heading takes at most maxLinesBeforeLoose lines this way (two by default) before the levers below are tried, and its further lines, up to maxLinesPerHeading, only when they have nothing left to give.
4. List ends — when the headings cannot absorb the whole gap, a grid line is added where a list/enumeration ends (space after a list reads naturally), capped per list end.
5. Under formulas, boxes and figures — then one grid line goes under a display formula or a callout box the text resumes after (stretchAfterDisplays; it reads as the element's own margin), and under a figure or table that heads the column (stretchAfterFloats, capped by maxLinesAfterFloat).
6. Loose paragraphs — as a last resort, one paragraph of the column is re-broken one line longer (TeX's \looseness=+1), choosing the longest paragraph so the extra word spacing dilutes invisibly. The loose solution is only accepted when every line stays below bodyText.maxWordSpacing — type colour never exceeds the limit you already configured. Requires bodyText.optimalLineBreaking.

On a character grid (cjk.grid, see Chinese layout › The character grid) every character stands in a cell one em wide and every line on the grid's line pitch, which is also the baseline grid. Balancing is off there by default, as in vertical text: a page set line by line on a grid, the way GB/T 9704 counts 22 lines of 28 characters, leaves a short column short. A configuration that sets enabled: true gets levers that keep the grid: headings, list ends, displays and figures take whole grid lines, so the text below them moves by whole rows, and gridLines: 'off' keeps those out for a standard that has no empty row to give. A Chinese or Japanese paragraph runs a line long only when no gap between two of its characters spreads past maxTracking, and takes no tracking on its letters: a line a character short spreads an em over its gaps, far past the default 0.01 em, so on a grid of whole cells the loose lever usually finds nothing. The box closing a column and the pictures with a safe area are off the grid by design and work as anywhere.

The last column of a page is only balanced when the page flows naturally into the next one — a chapter's closing page legitimately ends short. Such a page, and a closing band cut level by trailing, also keeps its column heads level: no line is added under a figure or table heading one of its columns (the after-float lever), and a heading or a box that opens a column under such a figure stays at its head, whatever stretchAfterFloats says, as does the heading set right under a span: 'page' opener in the opener's own column, so a column never starts lower than the one beside it just to line the feet up.

#Which lever fired

The layout records every lever it applied, on the block it applied to: block.balancing in the VDT that buildDocument returns. A proof sheet, a test or a report can say why a column ends flush — and which columns no lever could close. Blocks the balancing left alone carry no balancing, and a document built with enabled: false has none.

On a character grid the document says why a column may end short: doc.gridBalancing is { off: true } when balancing is off because the page is on a grid and the configuration does not turn it on, and { gridLines: 'off' } when it runs without the whole-line levers; a column still short carries column.gridRefused, the levers the grid kept from it ('looseParagraph' when a paragraph could gain its line only by spreading its characters off their cells, the whole-line levers under gridLines: 'off'). Both are absent off the grid.

interface VDTBalancing {
  levers: BalanceLever[]; // usually one: a paragraph after a list can take the list-end line and run a line long too
  spaceAbove: number;     // px the spacing levers added above the block (0 when only looseParagraph or flexFigure fired)
  bodyGrowth?: number;    // flexFigure: px the picture grew, cropped within its safe area
  extraLines?: number;    // looseParagraph: lines the paragraph gained
  tracking?: number;      // looseParagraph: the tracking that gained them, in thousandths of an em (0 = word spacing alone)
}
type BalanceLever = 'trailingCallout' | 'flexFigure' | 'heading' | 'listEnd' | 'afterDisplay' | 'afterFloat' | 'looseParagraph';

The level cuts are recorded on the columns they cut: column.bandCapped is true on every column cut level (the band a page-span box leaves, a closing band), and column.trailingCap also marks the closing band of a chapter or of the document (trailing).

import { buildDocument } from 'postext';
 
const doc = buildDocument(content, config);
for (const page of doc.pages) {
  page.columns.forEach((column, i) => {
    const levers: string[] = column.blocks.flatMap((block) => block.balancing?.levers ?? []);
    if (column.trailingCap) levers.push('closing band cut level');
    else if (column.bandCapped) levers.push('band cut level');
    if (levers.length > 0) console.log(`page ${page.index + 1}, column ${i + 1}: ${levers.join(', ')}`);
  });
}
// page 3, column 1: heading, heading
// page 3, column 2: listEnd, looseParagraph