Book Export

PDF Book Export

The browser book exporter builds a complete book PDF from a Hugo site. It assembles a book manifest, loads Hugo-rendered chapter bodies in Chromium, composes pages, writes the PDF, and records diagnostics.

Canonical Commands

Final two-pass export:

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

Fast iteration:

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

Watch mode with a local Hugo server:

npm run browser:watch:book-pdf -- \
  --site-root /path/to/site \
  --output /tmp/book.pdf \
  --start-hugo

Export Modes

  • --document-kind thesis keeps formal title/frontmatter/recto behavior.
  • --document-kind article keeps the same rendering and pagination machinery but uses compact article-style first-page flow.
  • --template and --latex-mode are accepted aliases for document kind. article and journal normalize to article behavior; other values use thesis behavior.
  • --fast skips slower finalization passes and is for iteration, not final output.

The exporter writes a PDF plus adjacent build/diagnostic data so an export can be reproduced and audited.

If --output is omitted, the default output is build/pdf/browser/phd-double-spread.pdf.

Common Options

  • --paper a4|a3 and --landscape choose page geometry.
  • --headed opens a visible browser.
  • --profile enables profiling output.
  • --diagnostics writes diagnostics alongside the PDF.
  • --generated-index on|off controls the simple generated index.
  • --page-plan is the current default book-export preparation path.
  • --legacy-pagination falls back to the older pagination path.
  • --hugo-host, --hugo-port, and --drafts control the local Hugo server when the exporter starts it.

The final path requests tagged PDF and outline output from Chromium, then stamps page labels, metadata, headers, and footers. The adjacent .build.json records command, Git/runtime details, and summary diagnostics.

Watch mode keeps one live preview page and one export page, with separate preview/export queues and debounce behavior so long PDF writes do not block the headed preview.

Inputs

The exporter expects a normal Hugo site structure. Root front matter supplies book metadata and options; section and page front matter control order and semantic roles. Hugo render hooks supply print metadata before the browser pass runs.

Files To Read

  • scripts/export-site-book-pdf.js
  • scripts/book-pdf/browser-page-builder.js
  • scripts/book-pdf/browser-book.css
  • docs/pdf-book-authoring-contract.md