Every contract, report and user guide we produce ends up as an A4 PDF printed on an office printer. For a long time the same small defects kept coming back: a section title alone at the bottom of a page, "The steps are:" on one page and the steps on the next, a list that leaves its first item behind. None of them is a bug in the usual sense. Together they make a document look careless. We now run every PDF through one shared engine, and, more importantly, we measure the result instead of trusting the CSS.
TL;DR
- Chromium honours
break-after: avoidon headings. In our test it removed every stranded heading on its own. - It cannot know that a paragraph ending in a colon introduces what follows. Those lead-in lines were left alone at the bottom of 52 pages across 10 documents, more than with no rules at all.
- A small script that runs in the page before printing wraps each heading, lead-in and first item into one unbreakable block, keeps runs of steps together at both ends, and redraws every image onto white. Result: 0 stranded headings or lead-ins.
- Do not check page breaks by matching heading text in the PDF. Arabic comes back from PDF text extraction in reversed presentation forms, and our first checker reported "0 problems" for documents it had never actually checked. Mark the headings with an invisible Latin token instead.
The problem
Our documents are long and structured: contracts with dozens of numbered clauses, hospital reports of hundreds of pages, user guides with numbered steps and screenshots. Most of them are in Arabic, many in both Arabic and English. They are produced as HTML and printed to PDF with headless Chromium, because HTML is where our templates, fonts and data already live.
The rules we hold every document to are simple to state:
- nothing is split across pages: a paragraph, a list item, a table row, a card, a signature block;
- a heading never ends a page, and neither does a line that introduces a list;
- a list never leaves a single item alone on either side of a break;
- table headers repeat on every page;
- no transparency anywhere, because office printers turn soft shadows and semi-transparent images into grey boxes.
Why CSS alone is not enough
CSS Fragmentation has the right vocabulary: break-inside: avoid, break-after: avoid, orphans, widows, thead { display: table-header-group }. We use all of them. To see what they actually achieve, we generated ten long English test documents with the same generator and seeds: 70 sections each, one to three paragraphs per section, and frequent sub-sections of the form "heading, then The steps are:, then a numbered list". We printed each one three ways and measured every page:
| Variant | Pages | Ends on heading | Ends on lead-in | Ends on first list item |
|---|---|---|---|---|
| A. No break rules | 327 | 59 | 21 | 14 |
| B. CSS rules only | 345 | 0 | 52 | 0 |
| C. CSS rules + in-page pass | 353 | 0 | 0 | 0 |
Two things stand out. First, the CSS rules do their job for headings: Chromium did not leave a single heading at the bottom of a page in variant B. Second, the stranded lead-ins went up, from 21 to 52. When the heading is kept with the paragraph after it, the break moves one element down, and the next weak point is the lead-in line, which CSS has no way to recognise. A paragraph that ends in a colon looks like any other paragraph.
This is a synthetic test in English, so the counts describe these ten documents, not every document. The pattern, though, is the one we kept seeing in real contracts and guides.
The fix: decide in the page, then print
The engine runs a short script inside the page after the content has loaded and before page.pdf(). It does three things.
1. Chain headings with what they introduce
Any paragraph whose text ends in a colon is marked data-keep-next. Then, for each heading or marked element, the script collects the chain that must stay together (heading, optional lead-in, the first block after them) and wraps it in a div with break-inside: avoid. Wrapping works where break-after does not, because the browser treats the whole chain as one box.
for (const el of document.querySelectorAll('p,.gt-lead'))
if (/[::]\s*$/.test(el.textContent)) el.setAttribute('data-keep-next', '');
for (const h of document.querySelectorAll('h1,h2,h3,h4,[data-keep-next]')) {
if (h.closest('.gt-keep')) continue;
const chain = [h]; let n = h.nextElementSibling;
while (n && n.matches('h1,h2,h3,h4,[data-keep-next]')) { chain.push(n); n = n.nextElementSibling; }
if (n) chain.push(n);
if (chain.reduce((t, e) => t + e.offsetHeight, 0) > PAGE_H * 0.45) continue; // too tall: leave it
const w = document.createElement('div'); w.className = 'gt-keep';
h.before(w); w.append(...chain);
}
The height limit matters. If a heading is followed by a very tall block, keeping them together would push the heading to a new page and leave most of the previous page empty. Above roughly 45% of a page we let it break normally.
2. Keep both ends of a list together
For a run of steps, the first two and the last two are wrapped together, so a single step is never alone at the bottom or the top of a page. Short runs of up to three steps are kept whole.
3. No transparency
Shadows, filters and opacity are switched off in the print stylesheet. Every image is redrawn onto a white canvas and embedded as an opaque JPEG, so the PDF contains no soft masks. After rendering, the engine scans the PDF for soft masks and partial alpha values and reports a transparency count that must be zero. All 30 PDFs in the test above reported zero.
Measuring it, and the mistake we made
Our first checker extracted the text of each page with pdf.js and compared the last line of the page with the list of headings. It printed a clean result for every contract we gave it. It was wrong. PDF text extraction returns Arabic as reversed presentation forms, so the text never matched any heading, and "no heading matched" was reported as "no page ends on a heading". The tool could not fail, which means it was not testing anything.
The checker we use now does not read the words at all. Before printing, it appends an invisible marker to every heading: a 1 px white Latin token such as HMK17. After printing, for each page it finds the lowest line of body text, ignoring the running header and footer. If that line carries a marker, the page ends on a heading and the check fails with exit code 1. Markers are plain ASCII, so the result is the same in Arabic and English.
We proved the checker with a control before trusting it: with the keep rules switched off, it catches the stranded heading. The ten-document test above is the same method applied to three variants.
node breaks.js contract.html --sel "h1,h2,.psec"
# prints { pages, marked, endsOnHeading: [...], transparency }; exit 1 if any page ends on a heading
The --sel option says what counts as a heading in that document. We find it by inspecting the rendered page, not by guessing, because a template that styles headings as divs would otherwise pass silently.
Results on real documents
We ran the checker on the documents we actually ship: our standard client contract (11 pages), a maintenance agreement (4 pages), a client annex (5 pages), and a set of hospital reports, the longest a 191-page register. Every one ended no page on a heading and contained no transparency.
The cost is pages. In the test, keeping chains together added 8% more pages than printing with no rules, and 2% more than CSS rules alone. For documents people sign and file, that is a price we pay gladly.
Checklist for print-ready PDFs from HTML
- Use
break-inside: avoidon paragraphs, list items, rows and boxes, andbreak-after: avoidon headings. It is necessary, not sufficient. - Before printing, wrap each heading, its lead-in line and the first following block into one unbreakable box, with a height limit.
- Keep the first two and last two items of every list together.
- Flatten images onto white and remove shadows and opacity. Then scan the PDF and fail the build if any transparency remains.
- Measure page breaks with invisible ASCII markers, not by matching text, and prove the checker fails on a known-bad document before you trust a pass.
- Run the check on the longest real document you have, not on a two-page sample.
Need this?
GeoTech PDF is the shared engine behind our contracts, reports, invoices and printed user guides: A4 layout, branded letterhead, Arabic and English, measured page breaks and print-safe output. If your system produces PDFs that look careless when printed, talk to us.