Pagination Debugging

PDF Pagination Debugging

Use this page when PDF output has collapsed pages, duplicated or cropped text, bad list breaks, wrong recto/backmatter behavior, missing notes, or unexpected blank pages.

First Split The Path

  • Editor PDF preview: browser state in cdn/custom/toggleMarkdown.js.
  • CLI book export: scripts/export-site-book-pdf.js and scripts/book-pdf/*.
  • TeX output: .tex templates and TeX tooling, not Chromium pagination.

Do not debug all three at once.

Quick Commands

Editor smoke:

npm run browser:smoke:pdf

Capture page images and diagnostics from a running site:

npm run browser:capture:pdf-pages -- \
  --url http://127.0.0.1:1313/ \
  --output /tmp/nowtype-pages \
  --single \
  --page-builder

Full book export:

npm run browser:export:book-pdf -- \
  --site-root /path/to/site \
  --url http://127.0.0.1:1313/ \
  --output /tmp/book.pdf \
  --diagnostics

Fast book iteration:

npm run browser:export:book-pdf -- \
  --site-root /path/to/site \
  --url http://127.0.0.1:1313/ \
  --output /tmp/book.pdf \
  --fast

Artifacts To Inspect

  • editor capture directory: page PNGs, contact sheet when available, and JSON manifest/page-builder diagnostics;
  • exported PDF;
  • adjacent .build.json from the book exporter;
  • browser console output from Playwright runs;
  • __qlNowtypePdfSmoke.getPaginationState() in editor smoke contexts.

Symptom Map

  • Collapsed page count: check root-relative layout metrics and page-break state in toggleMarkdown.js.
  • Duplicated or cropped text: compare screenshot/contact-sheet output before changing break penalties.
  • Bad list break: inspect list no-break ranges, list item fragmentation, and CLI page-builder diagnostics.
  • Wrong recto/backmatter: inspect book manifest role classification and final PDF stamping.
  • Unexpected blank page: check probe/final page reconciliation and planned blank verso validation.
  • Table overflow: inspect table classes and book-export table diagnostics.
  • Missing footnotes/notes: inspect editor PDF note state or CLI footnote deck insertion, depending on path.

Owner Files

  • Editor preview: cdn/custom/toggleMarkdown.js, cdn/custom/nowtypePdfCore.js.
  • CLI export orchestration: scripts/export-site-book-pdf.js.
  • CLI page preparation: scripts/book-pdf/browser-page-builder.js.
  • CLI print CSS: scripts/book-pdf/browser-book.css.
  • Hugo print metadata: layouts/partials/print/object-attrs.html and render hooks under layouts/_default/_markup/.