GeoTech

Engineering / Case study

A4 PDFs that never split a heading from its paragraph, measured page by page

GeoTech Engineering · · 8 min read

PDFCSSChromiumPrinting

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.

94 → 0pages ending on a heading or lead-in, 10 test documents
52stranded lead-ins left by CSS rules alone
191pages in the longest real report checked: 0 failures
+8%pages, the price of keeping things together

TL;DR

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:

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:

VariantPagesEnds on headingEnds on lead-inEnds on first list item
A. No break rules327592114
B. CSS rules only3450520
C. CSS rules + in-page pass353000

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

  1. Use break-inside: avoid on paragraphs, list items, rows and boxes, and break-after: avoid on headings. It is necessary, not sufficient.
  2. Before printing, wrap each heading, its lead-in line and the first following block into one unbreakable box, with a height limit.
  3. Keep the first two and last two items of every list together.
  4. Flatten images onto white and remove shadows and opacity. Then scan the PDF and fail the build if any transparency remains.
  5. 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.
  6. 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.