[recrwplay]

Summary

Prompted by comparing a real build (docs-java-reference) against the legacy pipeline's own published PDF (neo4j-java-reference-2026.09.pdf):

• Chapter titles more prominent: bumped h2 (every merged page's own top-level heading) from 18pt to 26pt - it read as barely more prominent than body text next to the legacy pipeline's much larger chapter titles. Tested locally.
• Full h2-h6 heading scale, not just h2-h4: a page nested two levels deep in its component's nav has its own internal headings shifted down by that same nav depth once merged into this book - a heading the source HTML renders as h3/h4 can land as h5/h6 here. Confirmed directly on docs-java-reference's "Set up a Maven project" (HTML h3, merged-book h5) and "DatabaseSeedProvider" (HTML h4, merged-book h6, Asciidoctor's deepest possible level) - both were completely unstyled before this and fell back to the renderer's tiny default sizes, barely legible next to 10.5pt body text. Now: h3 18pt, h4 14pt, h5 12pt, h6 11pt italic (no more room to shrink into at h6, so it's differentiated by style instead of size).
• Labels always below the title, never inline to the right: a role-based header label (e.g. label:new[]) used to sit inline to the right of its heading via CSS copied from the real site, where responsive JS adds a .wrapped class to drop it below the title when there's no room. That JS never runs in this static PDF render, so it always took the "plenty of room" layout regardless of the page's actual fixed, narrow content width. Now always renders below the title.
• A heading's labels can no longer split onto the next page on their own: .header-label-container is always the heading element itself, with its labels div appended as a child, not a sibling - without break-inside: avoid, a heading whose title text just barely fit at the bottom of a page could have its labels div alone pushed onto the next page, split from the title it belongs to. Reported directly after the "labels below title" change above made this visible.
• TOC nesting/indentation actually works now: this was a complete no-op bug - the CSS targeted sectlevel0/sectlevel1, but Asciidoctor's own TOC markup is 1-indexed (sectlevel1/sectlevel2/sectlevel3, there is no sectlevel0) - so every PDF this pipeline has ever shipped had a flat, unindented TOC regardless of the toclevels setting. Fixed the selectors and bumped toclevels from 2 to 3 to go one level deeper, matching the legacy PDFs' own TOC depth. (Checked the TOC-length impact on Operations Manual specifically, since it's one of the biggest docsets: 153 entries at toclevels 2 vs 256 at toclevels 3 - a real jump, but still well under half the length of that docset's current ~20-page published TOC, so not a regression risk. A per-docset toclevels override is a reasonable future addition if a particular docset wants to dial it back down.)
• Closing License page: every PDF now gets a CC BY-NC-SA 4.0 license page appended at the end, matching the old Gradle pipeline's own unconditional pdfNav append of the same page. Vendored into this package rather than read from a consuming docset's own content tree - a couple of repos (docs-aura, docs-ops-manager) still carry a copy of this exact page left over from the old pipeline, but it's an orphan page absent from their nav, so this pipeline never saw it either way. [discrete] keeps it out of the TOC, like a real book's colophon page.
• Copyright/trademark colophon page: every PDF also now gets a one-time Neo4j copyright/trademark notice right after the cover page and before the TOC - distinct from the closing License page above (that's CC BY-NC-SA licensing terms; this is Neo4j's own trademark notice). An alternative to running @neo4j-antora/mark-terms in this pipeline, which marks a term's first use per page - a notion this pipeline's single merged document has no equivalent of.
• Opt-in MathJax/stem support: patches @djencks/asciidoctor-mathjax's pre-4.x Opal-bridge API calls to work against the 4.x Asciidoctor.js engine this pipeline vendors (same class of fix as the existing macros/remote-include adapters). Registered only when the docset being built actually has that dependency installed, so every other docset's PDF build is unaffected by its absence. Currently unexercised - no docset in the org declares that dependency yet, even ones using stem:: blocks (docs-operations, docs-glossary), which presumably rely on MathJax loaded client-side for HTML - that can't help a static PDF render.
• Fixed broken cross-manual/javadoc links: every docset's neo4j-docs-base-uri (and the per-manual *-base-uri attributes built from it - javadocs, operations-manual, cypher-manual, ...) is deliberately root-relative (/docs/...) for the live website - correct in a browser, but a standalone PDF opened via file:// has no origin to resolve that against, so the link silently does nothing when clicked (reported directly: a "ding" sound in Preview, no navigation, on the Javadocs link and "Operations Manual -> Securing extensions"). The old Gradle pipeline hardcoded its own base-uri attributes to always be absolute, by name, for every manual - not practical here (no equivalent master list, and it would miss a genuine Antora cross-component xref resolving the same way), so absolute-links-postprocessor.js rewrites every root-relative <a href="/..."> to an absolute URL after rendering instead, catching any cause with one general fix.
• That origin now reflects the actual publish environment: reusable-docs-pdf-build.yml gained a publish-env input, passed to Antora as --url exactly like reusable-docs-build.yml's own DOCS_PUBLISH_URL already does for HTML - it cascades into the docset's own site-url, which convert.js reads back out to resolve the postprocessor's rewrite origin above. Without this, a PDF built for dev would still link to the real prod site rather than the dev sandbox. Verified directly: passing a sentinel --url through a real build correctly rewrote every cross-manual/javadoc link to that origin. The three repos that call this workflow need their own small follow-up PR to actually pass the new input through from their own resolve-env job - filed and included below.

The colophon and MathJax support were ported fresh from an orphaned pdf-generator-package branch (not cherry-picked - that branch predates several fixes already shipped on dev, e.g. the docdir/-B image fix and the image max-width CSS).

Bumped pdf-generator to 0.1.6.

Dependent PRs (pass publish-env through from each repo's own docs-generate-pdf.yml)

• neo4j/docs-template#69
• Pass publish-env through to the PDF build, same as the HTML build docs-getting-started#544
• Pass publish-env through to the PDF build, same as the HTML build docs-java-reference#386

Test plan

• Rebuilt docs-java-reference's real PDF locally against each change and visually inspected: cover/chapter title size, a labeled heading ("Reload procedures and functions") rendering labels below the title and staying together across page boundaries, the TOC's indentation and bold top-level entries, the closing License page and the new Copyright & Trademarks colophon page each landing on their own page and excluded from the TOC, and the full heading scale down to h6.
• Confirmed the MathJax adapter is skipped cleanly (no error) when a docset doesn't have @djencks/asciidoctor-mathjax installed, as is currently true for every docset checked.
• docs-java-reference's own content doesn't have real third-level nav nesting, so the sectlevel3 CSS rule and toclevels: 3 bump are verified correct by inspecting Asciidoctor's own emitted TOC markup directly (sectlevel1/sectlevel2/sectlevel3), and separately by a live three-deep example on docs-getting-started once rebuilt locally.
• Verified via pikepdf: all 128 link annotations in a real docs-java-reference build now resolve to absolute URLs, zero file:// links remain, including the two originally-reported links.
• Also tried a build against docs-operations (bigger docset) to stress-test further, but it hit the existing 180s Puppeteer render timeout on a later attempt - a separate, pre-existing issue unrelated to this PR's changes.

[neo4j-docops-agent]

Thanks for the documentation updates.

The preview documentation has now been torn down - reopening this PR will republish it.