@neo4j-antora/pdf-generator 0.1.0-rc.1

package/README.adoc

@@ -0,0 +1,131 @@
+= PDF generation
+
+Generates a PDF export from any Antora docset, via `@antora/assembler` +
+`@antora/pdf-extension` and `asciidoctor-web-pdf` (a Chrome/Puppeteer + CSS
+renderer) instead of the legacy Gradle + AsciidoctorJ mono-merge pipeline.
+See `reusable-pdf-build.yml` in `.github/workflows/` for the CI entry point
+that uses this package.
+
+Published as a normal npm dependency - a docset adds it as a devDependency
+and gets a real, versioned copy in its own `node_modules`, the same way it
+already depends on `@neo4j-antora/roles-labels` or `@neo4j-antora/tabbed-nav`.
+There's nothing to check out, symlink, or hand-configure: `@antora/pdf-
+extension` is this package's own dependency (not something a docset lists
+itself), so `npm install @neo4j-antora/pdf-generator` is the entire setup.
+
+== Usage
+
+A docset needs its own small playbook (like `preview.yml`/`publish.yml`,
+since content sources/attributes differ per docset - not shared here) that
+registers `@antora/pdf-extension` with this package's assembler config:
+
+[source,yaml]
+----
+antora:
+  extensions:
+   - require: '@antora/pdf-extension'
+     config_file: './node_modules/@neo4j-antora/pdf-generator/antora-assembler-pdf.yml'
+----
+
+and a `package.json` script to run it, e.g. `"pdf": "antora pdf.yml"`.
+
+== Layout
+
+- `antora-assembler-pdf.yml` - Assembler config, pointed at from a docset's
+  own playbook (see above).
+- `scripts/convert.js` - wraps the real `asciidoctor-web-pdf` binary as the
+  assembler's `build.command`. Resolves the renderer binary (via
+  `require.resolve` against its own `asciidoctor-pdf` dependency, regardless
+  of how npm hoists it) and the stylesheet/extension paths (via `__dirname`)
+  at runtime, so nothing here is hardcoded to a particular install layout.
+  Also works around a real bug (`ifndef::backend-pdf[]` not evaluating
+  correctly under this pipeline) for docsets using that idiom - a no-op for
+  any docset that doesn't.
+- `pdf-theme/print.css` - print stylesheet targeting Asciidoctor's standard
+  HTML5 backend class names (`sect1`, `admonitionblock`, `listingblock`,
+  `tableblock`, `label`, ...), using colour/font tokens copied from
+  `docs-ui`'s `src/css/vars.css` (itself resolving to raw Needle design
+  system tokens in `@neo4j-ndl/base`'s `tokens/css/tokens.css`) and
+  `docs-ui`'s `src/css/labels.css`. Not a fork of the real site CSS wholesale
+  - Asciidoctor's default HTML5 output doesn't have Antora's `.doc` wrapper
+    markup most of the site CSS's selectors are written against, so most of
+    it wouldn't match anything here anyway. Fonts are vendored into
+    `pdf-theme/assets/fonts/` rather than read from a docset's own HTML
+    build output, so this theme has no dependency on that build having
+    already run.
+- `extensions/` - `roles-labels-postprocessor.js` and
+  `table-footnotes-postprocessor.js` port the essential parts of the Antora
+  extensions of the same name (see "Known limitations" below);
+  `macros-adapter.js` and `remote-include-adapter.js` wrap the real
+  `@neo4j-documentation/macros`/`remote-include` packages, fixing a
+  pre-4.x-Asciidoctor.js API incompatibility in each at runtime (see their
+  own comments) rather than patching the installed packages - a nested
+  dependency's own `postinstall` isn't guaranteed to run once this package
+  is itself installed as a docset's dependency, so `patch-package` isn't a
+  reliable option here the way it is for a top-level project.
+- `@asciidoctor/core` 4.x (needed by `asciidoctor-pdf`) vs. Antora's own 2.x:
+  no longer needs the isolated sibling npm project the git-checkout-based
+  version of this pipeline required - both land in the same install
+  correctly because npm nests conflicting versions of the same dependency
+  automatically; this package simply declares its own real dependencies and
+  lets normal npm resolution do the isolation.
+
+== Known limitations
+
+- **No footnotes render at all, anywhere in the PDF, because of the TOC.**
+  Isolated by direct testing against `asciidoctor-web-pdf` outside this whole
+  pipeline: passing `-a toc` alone (nothing else - no tables, no our own
+  extensions) is enough to break native Asciidoctor `footnote:[...]`
+  conversion entirely - no superscript reference, no `#footnotes` div, just
+  the footnote text dropped in-line as if the macro had never been
+  processed. Since the print theme enables `toc` for every docset, this
+  currently affects every PDF this pipeline produces, not just docsets using
+  footnotes inside tables. `extensions/table-footnotes-postprocessor.js`
+  (see above) is correctly written and wired in, but has nothing to do while
+  this is broken - there's no `#footnotes` div for it to move content out of.
+  Not yet root-caused further (asciidoctor-web-pdf itself, or its Vivliostyle
+  dependency) or fixed.
+- `@neo4j-antora/roles-labels` and `@neo4j-antora/table-footnotes` are Antora
+  extensions (hook `pagesComposed`, operate on an Antora `ContentCatalog`) -
+  neither can run against this pipeline at all, structurally: the assembler
+  hands the merged `.adoc` to a completely separate, isolated Asciidoctor
+  conversion with no Antora generator context. `table-footnotes` is ported
+  as a plain Asciidoctor `Postprocessor` instead
+  (`extensions/table-footnotes-postprocessor.js`) - pure HTML restructuring,
+  no Antora-specific data needed, so the port is a straight copy.
+  `roles-labels-postprocessor.js` reuses `@neo4j-antora/roles-labels`'s own
+  shared `lib/process-labels.js` core directly (same synonym resolution,
+  version/product-suffix stripping, dataset attributes as the real HTML
+  site - not a hand-ported subset), with one deliberate behavioural
+  difference: it passes `skipDiscrete: false`, because `@antora/assembler`
+  marks *every* merged page's heading `discrete` to flatten section nesting
+  across the book, which isn't the authorial signal `discrete` is on a real
+  Antora HTML page (see `process-labels.js`'s own comment on that option).
+- Classification of `reusable-docs-build.yml`'s default `antora-extensions`
+  list, checked against their actual registration mechanism:
+  `aliases-redirects`, `antora-modify-sitemaps`, `antora-page-list` all hook
+  Antora-only lifecycle events (site redirects, sitemap.xml, the HTML
+  page-list artifact) - inherently HTML/site-only, correctly and harmlessly
+  absent from PDF output, nothing to do. `antora-unlisted-pages`/
+  `selector-labels` not individually confirmed but almost certainly the same
+  (nav/site-UI concerns). `xref-hash-validator` hooks `contentClassified`/
+  `documentsConverted` but only validates/warns - doesn't transform content,
+  so its absence from PDF just means xrefs aren't validated in that context,
+  not a rendering gap.
+- **TODO, not yet decided**: `@neo4j-antora/mark-terms` *is* a plain
+  Asciidoctor extension (`module.exports = function (registry) {...}`, no
+  Antora event hook) - structurally it'd just need `--extension`
+  registration, the same easy fix as `macros`/`remote-include`. Not done
+  yet, because it's a product decision, not just a technical one: mark-terms
+  adds a trademark/copyright mark on a term's *first use per page* (e.g. the
+  first "Neo4j" on each HTML page) - a PDF has no equivalent notion of "page"
+  the way a docset's HTML pages do, so "first use" would need redefining
+  (per PDF? per chapter? just once, ever?), or the whole approach swapped for
+  a single boilerplate copyright/trademark statement somewhere in the PDF
+  (e.g. the cover or a colophon page) instead of inline marks. Needs a call
+  on the right behaviour before doing the (otherwise straightforward)
+  registration work.
+- This package's `print.css` label colours are hand-resolved from
+  `docs-ui`'s source files, not read from them live - if the Needle tokens or
+  `docs-ui`'s `vars.css`/`labels.css` change, this drifts until someone
+  notices and re-syncs it by hand.

package/antora-assembler-pdf.yml

@@ -0,0 +1,23 @@
+component_version_filter:
+  names: '**'
+assembly:
+  attributes:
+    allow-uri-read: ''
+    toc: ''
+    toc-title: Table of Contents
+    toclevels: 2
+build:
+  # build.cwd (what a relative command resolves against) defaults to the
+  # *playbook's* directory (docs-dir) - the same directory `npm install` is
+  # run from for that docset, since that's where its own package.json lives.
+  # node_modules is therefore always right here, at a fixed, predictable
+  # depth, regardless of how deeply nested docs-dir is within the docset
+  # repo - unlike the old git-checkout-into-.pdf-tools convention this
+  # package replaces, no per-consumer path rewriting is needed. Once
+  # convert.js itself is running, it resolves everything else (the
+  # renderer, the stylesheet, the extensions) from its own location or via
+  # require.resolve against its own dependencies instead - see this
+  # package's own README.
+  command: node ./node_modules/@neo4j-antora/pdf-generator/scripts/convert.js --trace
+  keep_source: true
+  qualify_exports: true

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@neo4j-antora/pdf-generator",
+  "version": "0.1.0-rc.1",
+  "description": "Generates a PDF export from an Antora docset, styled to match the real Neo4j docs site, via @antora/assembler + @antora/pdf-extension and asciidoctor-web-pdf",
+  "main": "scripts/convert.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "postinstall": "node scripts/setup-vendor.js"
+  },
+  "keywords": [
+    "antora",
+    "pdf"
+  ],
+  "author": "Neo4j",
+  "license": "MIT",
+  "dependencies": {
+    "@antora/pdf-extension": "1.0.0",
+    "@neo4j-antora/roles-labels": "0.1.14-rc.1",
+    "@neo4j-documentation/macros": "1.0.4",
+    "@neo4j-documentation/remote-include": "1.0.0",
+    "node-html-parser": "9.0.4"
+  }
+}

package/pdf-theme/assets/neo4j-logo.svg

@@ -0,0 +1 @@
+<svg data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 75"><path d="M39.23 19c-10.58 0-17.68 6.16-17.68 18.11v8.52a8 8 0 013.45-.82 7.89 7.89 0 013.46.8v-8.54c0-7.75 4.28-11.73 10.8-11.73S50 29.32 50 37.07v18.62h6.89V37.07C56.91 25.05 49.81 19 39.23 19zm21.43 18.8c0-10.87 8-18.84 19.27-18.84s19.13 8 19.13 18.84v2.53H67.9c1 6.38 5.8 9.93 12 9.93 4.64 0 7.9-1.45 10-4.56h7.6c-2.75 6.66-9.27 10.94-17.6 10.94-11.27 0-19.24-7.97-19.24-18.84zm31.15-3.62c-1.38-5.73-6.08-8.84-11.88-8.84s-10.43 3.19-11.81 8.84zm10.93 3.62c0-10.86 8-18.83 19.27-18.83s19.27 8 19.27 18.83-8 18.84-19.27 18.84-19.27-7.97-19.27-18.84zm31.59 0c0-7.24-4.93-12.46-12.32-12.46S109.7 30.56 109.7 37.8s4.92 12.46 12.3 12.46 12.33-5.21 12.33-12.46zm46.31 25.02h.8c4.42 0 6.08-2 6.08-7V20.16h6.89v35.2c0 8.84-3.48 13.4-12.32 13.4h-1.45zm-3.44-3.68h-6.89v-8.49h-17.45A8.64 8.64 0 01145 46.2a7.72 7.72 0 01.94-8.16l15.66-20.55a8.65 8.65 0 0115.6 5.13v21.92h5.17v6.11h-5.17zM151.67 41.8a1.76 1.76 0 00-.32 1 1.72 1.72 0 001.73 1.73h17.23V22.45a1.7 1.7 0 00-1.19-1.68 2.36 2.36 0 00-.63-.09 1.63 1.63 0 00-1.36.73L151.67 41.8z"/><path d="M191 5.53a5.9 5.9 0 105.89 5.9 5.9 5.9 0 00-5.89-5.9zM24.7 47a5.84 5.84 0 00-3.54 1.2l-6.48-4.43a6 6 0 00.22-1.59A5.89 5.89 0 109 48a5.81 5.81 0 003.54-1.2L19 51.26a5.89 5.89 0 000 3.19l-6.48 4.43A5.81 5.81 0 009 57.68a5.9 5.9 0 105.89 5.89 6 6 0 00-.21-1.57l6.48-4.43a5.84 5.84 0 003.54 1.2 5.9 5.9 0 000-11.77z" fill="#018bff"/></svg>

package/pdf-theme/print.css

@@ -0,0 +1,422 @@
+/* Print-specific stylesheet shared by every docset's PDF export (see
+   docs-tools/pdf/README - checked out into each repo's build by
+   reusable-pdf-build.yml). Reuses brand tokens read from the real site.css
+   (build/site/assets/css/site.css) rather than forking that file, since
+   Asciidoctor's HTML5 backend (used by asciidoctor-web-pdf) does not produce
+   Antora's `.doc` wrapper markup.
+
+   Every asset path below is relative to this file's own location, not to
+   whatever repo/cwd the build runs in - a browser resolves CSS url()s
+   against the stylesheet's own file:// location, so this stays correct
+   wherever docs-tools gets checked out. Font files are vendored into
+   assets/fonts/ here (not read from a docset's own build output) so this
+   theme has no dependency on that docset's HTML build having already run. */
+@font-face {
+  font-family: 'Roboto Mono';
+  font-weight: 400;
+  src: url('assets/fonts/roboto-mono-latin-400.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'Roboto Mono';
+  font-weight: 500;
+  src: url('assets/fonts/roboto-mono-latin-500.woff2') format('woff2');
+}
+
+:root {
+  --brand-primary: #0a6190;
+  --brand-primary-strong: #02507b;
+  --brand-primary-weak: #e7fafb;
+  --brand-text: #1a1b1d;
+  --brand-text-weak: #4d5157;
+  --brand-text-weaker: #5e636a;
+  --brand-border: #e2e3e5;
+  --brand-border-strong: #bbbec3;
+  --brand-bg-weak: #fff;
+  --brand-bg-strong: #f5f6f6;
+  --brand-danger: #a6291f;
+  --brand-danger-bg: #fdf1ef;
+  --brand-warning: #8a5a00;
+  --brand-warning-bg: #fdf6e8;
+  --font-body: 'Public Sans', 'Nunito Sans', 'Helvetica Neue', Helvetica, Arial, sans-serif;
+  --font-mono: 'Roboto Mono', Menlo, Monaco, Consolas, 'Courier New', monospace;
+}
+
+@page {
+  size: A4;
+  margin: 25mm 18mm 20mm 18mm;
+}
+/* Verso (even/left) pages: page number on the outer (left) edge */
+@page :left {
+  @bottom-left {
+    content: counter(page);
+    font-family: var(--font-body);
+    font-size: 9pt;
+    color: var(--brand-text-weaker);
+  }
+  @bottom-right {
+    content: string(doc-title) " " string(doc-version);
+    font-family: var(--font-body);
+    font-size: 9pt;
+    color: var(--brand-text-weaker);
+  }
+}
+/* Recto (odd/right) pages: page number on the outer (right) edge */
+@page :right {
+  @bottom-left {
+    content: string(doc-title) " " string(doc-version);
+    font-family: var(--font-body);
+    font-size: 9pt;
+    color: var(--brand-text-weaker);
+  }
+  @bottom-right {
+    content: counter(page);
+    font-family: var(--font-body);
+    font-size: 9pt;
+    color: var(--brand-text-weaker);
+  }
+}
+@page :first {
+  @bottom-left {
+    content: normal;
+  }
+  @bottom-right {
+    content: normal;
+  }
+}
+
+#cover.title-page h1 {
+  string-set: doc-title content();
+}
+#cover .details #revnumber {
+  string-set: doc-version content();
+}
+
+body.book {
+  font-family: var(--font-body);
+  color: var(--brand-text);
+  font-size: 10.5pt;
+  line-height: 1.5;
+}
+
+#cover.title-page {
+  text-align: left;
+  page-break-after: always;
+}
+#cover.title-page::before {
+  content: url('assets/neo4j-logo.svg');
+  display: block;
+  width: 110pt;
+}
+#cover.title-page h1 {
+  font-size: 32pt;
+  font-weight: 700;
+  color: var(--brand-primary-strong);
+  margin-top: 30%;
+  border-bottom: 2pt solid var(--brand-primary);
+  padding-bottom: 12pt;
+}
+#cover .details {
+  color: var(--brand-text-weak);
+  font-size: 11pt;
+  margin-top: 8pt;
+}
+#cover #revdate {
+  display: none;
+}
+
+/* Table of contents */
+#toc {
+  page-break-after: always;
+}
+#toctitle {
+  font-family: var(--font-body);
+  color: var(--brand-primary-strong);
+  font-size: 22pt;
+  font-weight: 700;
+  border-bottom: 2pt solid var(--brand-primary);
+  padding-bottom: 10pt;
+  margin-bottom: 18pt;
+}
+#toc ul {
+  font-family: var(--font-body);
+  list-style-type: none;
+  margin-left: 0;
+  padding-left: 0;
+}
+#toc ul.sectlevel0 {
+  margin-left: 0;
+}
+#toc ul ul.sectlevel1 {
+  margin-left: 14pt;
+}
+#toc li {
+  margin-top: 6pt;
+  line-height: 1.4;
+}
+#toc a {
+  display: flex;
+  color: var(--brand-text);
+  text-decoration: none;
+  font-size: 10.5pt;
+}
+#toc ul.sectlevel0 > li > a {
+  font-weight: 600;
+  font-style: normal;
+  color: var(--brand-primary-strong);
+}
+#toc a::after {
+  content: leader('.') target-counter(attr(href), page);
+  color: var(--brand-text-weaker);
+  font-weight: 400;
+}
+
+.sect1 { break-before: page; }
+.sect1:first-child { break-before: avoid; }
+
+h1, h2, h3, h4, h5, h6 {
+  font-family: var(--font-body);
+  color: var(--brand-primary-strong);
+  font-weight: 700;
+  break-after: avoid;
+}
+h2 { font-size: 18pt; border-bottom: 1pt solid var(--brand-border); padding-bottom: 4pt; }
+h3 { font-size: 14pt; }
+h4 { font-size: 12pt; }
+
+a { color: var(--brand-primary); text-decoration: none; }
+
+/* code */
+pre, code, kbd, tt {
+  font-family: var(--font-mono);
+}
+.listingblock {
+  break-inside: avoid-page;
+  margin: 1em 0;
+}
+.listingblock pre {
+  background: var(--brand-bg-strong);
+  border: 0.5pt solid var(--brand-border);
+  border-radius: 3pt;
+  padding: 8pt 10pt;
+  font-size: 9pt;
+  line-height: 1.4;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+.listingblock .title {
+  font-weight: 600;
+  color: var(--brand-text-weak);
+  font-size: 9.5pt;
+  margin-bottom: 4pt;
+}
+
+/* tables */
+table.tableblock {
+  border-collapse: collapse;
+  width: 100%;
+  break-inside: auto;
+  font-size: 9.5pt;
+}
+table.tableblock th, table.tableblock td {
+  border: 0.5pt solid var(--brand-border);
+  padding: 5pt 7pt;
+  vertical-align: top;
+}
+table.tableblock thead th {
+  background: var(--brand-bg-strong);
+  color: var(--brand-text);
+  font-weight: 600;
+}
+tr { break-inside: avoid; }
+
+/* admonitions */
+.admonitionblock { break-inside: avoid-page; margin: 1em 0; }
+.admonitionblock table { width: 100%; border: none; }
+.admonitionblock td.icon { display: none; }
+.admonitionblock td.content {
+  border-left: 3pt solid var(--brand-border-strong);
+  padding: 6pt 10pt;
+  background: var(--brand-bg-strong);
+}
+.admonitionblock .title {
+  font-weight: 700;
+  text-transform: uppercase;
+  font-size: 8.5pt;
+  letter-spacing: 0.03em;
+  color: var(--brand-text-weak);
+  display: block;
+  margin-bottom: 3pt;
+}
+.admonitionblock.warning td.content,
+.admonitionblock.caution td.content {
+  border-left-color: var(--brand-warning);
+  background: var(--brand-warning-bg);
+}
+.admonitionblock.warning .title,
+.admonitionblock.caution .title { color: var(--brand-warning); }
+.admonitionblock.important td.content {
+  border-left-color: var(--brand-danger);
+  background: var(--brand-danger-bg);
+}
+.admonitionblock.important .title { color: var(--brand-danger); }
+.admonitionblock.note td.content,
+.admonitionblock.tip td.content {
+  border-left-color: var(--brand-primary);
+  background: var(--brand-primary-weak);
+}
+.admonitionblock.note .title,
+.admonitionblock.tip .title { color: var(--brand-primary-strong); }
+
+/* lists */
+.ulist, .olist, .dlist { margin: 0.5em 0; }
+
+/* role labels (badges added by @neo4j-antora/roles-labels for label:x[] macros
+   and :page-role:/[role=label--x] roles).
+
+   This is `docs-ui/src/css/labels.css` (the *source* file the real site.css is
+   built from - github.com/neo4j-documentation/docs-ui) copied rule-for-rule,
+   minus the handful of selectors scoped under Antora's `.doc` wrapper (which
+   plain Asciidoctor HTML5 output, used for the PDF, never has - see file
+   header) - not hand-approximated values. Its `var(--label-*)`/`var(--deprecated-*)`/
+   `var(--alpha-beta-*)`/`var(--success-color)` custom properties are themselves
+   defined in `docs-ui/src/css/vars.css` in terms of raw design tokens from the
+   Needle design system (`@neo4j-ndl/base`'s `tokens/css/tokens.css`); resolved
+   to literal values below since neither of those files is otherwise pulled in
+   here. Re-resolve from those two sources if this ever drifts. */
+.label {
+  display: inline-block;
+  /* Vertical padding trimmed from the copied 0.2rem: consecutive inline
+     labels on adjacent lines (e.g. label:x[] label:y[] each on their own
+     line) had no visible gap between them otherwise - line-height alone
+     isn't enough since the pills' padding pushed their edges flush. */
+  padding: 0.1rem 0.8rem;
+  flex-shrink: 0;
+  border-radius: 9999px;
+  background: var(--brand-primary);   /* --label-default-background-color: --theme-light-color-primary-text */
+  color: var(--brand-primary-weak);   /* --label-default-color: --palette-baltic-10 */
+  font-weight: 600;
+  font-size: calc(0.8 * 0.875rem);     /* --label-title-font-size: calc(0.8 * --typography-label-font-size) */
+  font-style: normal;
+}
+.tableblock .label {
+  margin-top: 0.2rem;
+  margin-bottom: 0.5rem;
+}
+span.label--added,
+span.label--changed,
+span.label--new,
+span.label--featured,
+span.label--renamed,
+span.label--updated,
+span.label--yes {
+  background: #3f7824; /* --label-success-color: --theme-light-color-success-bg-strong */
+  color: #e7fcd7;      /* --label-success-background-color: --theme-light-color-success-bg-weak */
+}
+span.label--admin-only,
+span.label--danger,
+span.label--discontinued,
+span.label--na,
+span.label--no,
+span.label--not-on-aura,
+span.label.not-available,
+span.label--removed,
+span.label--warning,
+span.label--breaking {
+  background: #bb2d00; /* --label-warning-background-color: --theme-light-color-danger-bg-strong */
+  color: #ffe9e7;      /* --label-warning-color: --theme-light-color-danger-bg-weak */
+}
+span.label--deprecated {
+  background: #ffd600; /* --deprecated-background-color: --palette-lemon-30 */
+  color: #251b00;      /* --deprecated-color: --palette-lemon-80 */
+}
+span.label--alpha,
+span.label--beta,
+span.label--beta-until {
+  background: #ba7a00; /* --alpha-beta-background-color: --palette-marigold-50 */
+  color: #fff0d2;      /* --alpha-beta-color: --palette-marigold-10 */
+}
+span.label--procedure,
+span.label--function,
+span.label--unix,
+span.label--mac-os,
+span.label--linux,
+span.label--windows,
+span.label--syntax,
+span.label--functionality,
+span.label--cypher,
+span.label--cluster-member-core,
+span.label--cluster-member-read-replica,
+span.label--cluster-member-single,
+span.label--core,
+span.label--apoc-core,
+span.label--full,
+span.label--apoc-full {
+  background: #8fe3e8; /* --label-os-background-color: --theme-dark-color-primary-text */
+  color: #081e2b;      /* --label-os-color: --palette-baltic-70 */
+}
+span.label--labs,
+span.label--labs-label {
+  color: var(--brand-primary-weak);  /* --label-labs-color: --palette-baltic-10 */
+  background: #5a34aa;               /* --label-labs-background-color: --palette-lavender-45 */
+}
+span.label--graph-academy {
+  background: #3f7824; /* --success-color: --theme-light-color-success-bg-strong */
+}
+
+div.labels {
+  display: flex;
+  align-self: center;
+  gap: 0.25rem;
+  line-height: 1.8;             /* --doc-line-height */
+  font-family: var(--font-body); /* --body-font-family */
+}
+.flex-labels-container {
+  display: flex;
+  justify-content: space-between;
+  align-items: flex-start;
+  flex-direction: row-reverse;
+}
+.header-label-container {
+  display: flex;
+  flex-wrap: wrap;
+}
+.admonitionblock div.labels { padding: 0.5rem 0 1rem; }
+.exampleblock div.labels { padding: 0.5rem; }
+.header-label-container > div.labels {
+  justify-content: space-between;
+  margin-left: auto;
+}
+.header-label-container > div.labels.wrapped {
+  margin-left: 0;
+  margin-top: 0.5rem;
+}
+h1 > .header-label {
+  margin-top: 1.2rem;
+}
+.header-label-container > .header-label:first-of-type {
+  margin-left: auto;
+}
+.listing-block .content-labels,
+.example-block .content-labels,
+.content-labels {
+  margin-bottom: 0.2rem;
+}
+.paragraph.has-label {
+  padding-left: 0.4rem;
+  border-left: 2px solid var(--brand-border-strong); /* --palette-baltic-60, not otherwise used here */
+}
+.paragraph.has-label:has(> .labels > .label--new) {
+  border-left-color: #3f7824; /* --success-color */
+}
+.paragraph.has-label:has(> .labels > .label--deprecated) {
+  border-left-color: #251b00; /* --deprecated-color */
+}
+h2 > .flex-label {
+  float: inline-end;
+  line-height: 1.8;
+  margin-left: 0.2rem;
+  margin-top: 0.2rem;
+}
+
+/* TOC (hidden fixed div rendered separately by asciidoctor-web-pdf's own TOC mechanism) */
+.toc-entry a { color: var(--brand-text); text-decoration: none; }

package/scripts/convert.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+'use strict'
+
+// Wraps the real asciidoctor-web-pdf binary as the assembler's build.command.
+// Every path below is computed from this script's own location (__dirname) -
+// never hardcoded, never dependent on where a consuming project's
+// node_modules happens to hoist things - see this package's own README.
+
+const { spawn } = require('node:child_process')
+const path = require('node:path')
+
+// asciidoctor-pdf needs @asciidoctor/core 4.x while Antora needs 2.x, and it
+// doesn't declare @asciidoctor/core as its own dependency (only a peerDep on
+// the `asciidoctor` wrapper) - npm has no signal to ever nest an isolated
+// copy for it, so a normal dependency install can silently hoist Antora's
+// 2.x copy in instead, which crashes at import time. `vendor/` is a real,
+// pre-installed node_modules tree (asciidoctor + asciidoctor-pdf and their
+// own transitive deps only) shipped as plain files with this package - not
+// npm dependencies at all from a consumer's point of view - so it's immune
+// to whatever else a docset's own install needs. The postprocessor/adapter
+// extensions live inside vendor/ too, so their own `require('asciidoctor')`
+// resolves the same isolated copy the renderer itself uses (required for
+// `Postprocessor` - see roles-labels-postprocessor.js's own comment); their
+// other requires (`node-html-parser`, `@neo4j-antora/roles-labels`, ...) fall
+// through vendor/'s node_modules to the consumer's normal install, since
+// those have no such conflict and should stay deduped normally.
+const RENDERER = path.join(__dirname, '../vendor/node_modules/asciidoctor-pdf/bin/asciidoctor-web-pdf')
+const STYLESHEET = path.join(__dirname, '../pdf-theme/print.css')
+const ROLES_LABELS_POSTPROCESSOR = path.join(__dirname, '../vendor/extensions/roles-labels-postprocessor.js')
+const TABLE_FOOTNOTES_POSTPROCESSOR = path.join(__dirname, '../vendor/extensions/table-footnotes-postprocessor.js')
+const REMOTE_INCLUDE_ADAPTER = path.join(__dirname, '../vendor/extensions/remote-include-adapter.js')
+const MACROS_ADAPTER = path.join(__dirname, '../vendor/extensions/macros-adapter.js')
+
+const PAGE_BOUNDARY_RX = /(?=^:page-docname: .*$)/m
+const GLOSSARY_MARKER_RX = /^\[discrete\.glossary#.*\]$/m
+
+// Some docsets (e.g. docs-http-api) repeat a glossary include on several
+// source pages, meant to be excluded from PDF via ifndef::backend-pdf[],
+// which doesn't evaluate correctly under this pipeline (see this package's
+// own README - the assembler resolves that attribute against its own
+// internal re-parse context, not the real, final PDF conversion). This is a
+// no-op for any docset with no `[discrete.glossary#...]` marker in its
+// merged source.
+function dedupeGlossary (adoc) {
+  const [preamble, ...pages] = adoc.split(PAGE_BOUNDARY_RX)
+  let glossaryChunk
+  const strippedPages = pages.map((page) => {
+    const match = GLOSSARY_MARKER_RX.exec(page)
+    if (!match) return page
+    if (!glossaryChunk) {
+      // Drop the "discrete" style so the glossary becomes a normal chapter
+      // section: included in the TOC and picked up by the print theme's
+      // `.sect1 { break-before: page }` rule like every other chapter.
+      glossaryChunk = page
+        .slice(match.index)
+        .trimEnd()
+        .replace(/^\[discrete\.glossary/, '[glossary')
+    }
+    // Keep a blank line before whatever follows (the next page's own
+    // `:page-docname:` metadata block, mid-document) - an undelimited
+    // single-paragraph admonition like [NOTE] only ends at a blank line, so
+    // trimming it away merges the next page's raw attribute lines straight
+    // into that paragraph's text instead of stopping it.
+    return page.slice(0, match.index).trimEnd() + '\n\n'
+  })
+  let result = preamble + strippedPages.join('')
+  if (glossaryChunk) result = result.trimEnd() + '\n\n' + glossaryChunk + '\n'
+  return result
+}
+
+function readStdin () {
+  const chunks = []
+  return new Promise((resolve, reject) => {
+    process.stdin.on('data', (chunk) => chunks.push(chunk))
+    process.stdin.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')))
+    process.stdin.on('error', reject)
+  })
+}
+
+// asciidoctor-web-pdf only reads these from the environment (no -a attribute or
+// CLI flag equivalent - see lib/browser.js) and defaults to 30s, which a large
+// docset can easily exceed. Give it more headroom here rather than relying on
+// whoever runs the build to remember to export these.
+const PUPPETEER_TIMEOUT_ENV = {
+  PUPPETEER_NAVIGATION_TIMEOUT: '180000',
+  PUPPETEER_RENDERING_TIMEOUT: '180000',
+}
+
+// antora-assembler-pdf.yml deliberately does NOT set a `stylesheet` attribute
+// itself - it's added here instead, __dirname-computed, so the path is always
+// correct wherever this package happens to be installed. CSS url()s resolve
+// relative to the stylesheet's own location, but Asciidoctor's `stylesheet`
+// attribute resolves relative to docdir/cwd - a different base entirely - so
+// this can't just be a relative value in the playbook/assembler config.
+const args = process.argv.slice(2)
+const stdinMarkerIdx = args.lastIndexOf('-')
+// roles-labels-postprocessor.js and table-footnotes-postprocessor.js port the
+// essential parts of the Antora extensions of the same name (see those
+// files); macros-adapter.js and remote-include-adapter.js wrap the real
+// @neo4j-documentation packages - added here, __dirname-computed, for the
+// same reason as the stylesheet above.
+const extraArgs = [
+  '-a', `stylesheet=${STYLESHEET}`,
+  '--extension', ROLES_LABELS_POSTPROCESSOR,
+  '--extension', TABLE_FOOTNOTES_POSTPROCESSOR,
+  '--extension', REMOTE_INCLUDE_ADAPTER,
+  '--extension', MACROS_ADAPTER,
+]
+const finalArgs =
+  stdinMarkerIdx === -1
+    ? [...args, ...extraArgs]
+    : [...args.slice(0, stdinMarkerIdx), ...extraArgs, ...args.slice(stdinMarkerIdx)]
+
+readStdin().then((adoc) => {
+  const child = spawn(RENDERER, finalArgs, {
+    stdio: ['pipe', 'inherit', 'inherit'],
+    env: { ...PUPPETEER_TIMEOUT_ENV, ...process.env },
+  })
+  child.on('error', (err) => {
+    console.error(err)
+    process.exit(1)
+  })
+  child.on('close', (status) => process.exit(status ?? 1))
+  child.stdin.end(dedupeGlossary(adoc))
+})

package/scripts/setup-vendor.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+'use strict'
+
+// Runs as this package's own `postinstall` (see package.json) - installs
+// asciidoctor-pdf + the exact Asciidoctor.js it needs (4.x) into vendor/,
+// fresh, in whichever environment this package itself just got installed
+// into. asciidoctor-pdf needs @asciidoctor/core 4.x while Antora needs 2.x,
+// and asciidoctor-pdf doesn't declare @asciidoctor/core as its own
+// dependency (only a peerDep on the `asciidoctor` wrapper) - npm has no
+// signal to isolate it from a docset's own shared install, and can silently
+// hoist Antora's incompatible 2.x copy in instead, which crashes at import
+// time. A real, separate `npm install` in vendor/'s own directory - exactly
+// what the old isolated `renderer/` project this replaces did by hand -
+// fixes that; running it from this package's own `postinstall` makes it
+// automatic instead of a manual convention a consumer has to know about.
+//
+// vendor/package.json is written here, at install time, rather than shipped
+// as a static file in the published package: a *shipped* nested
+// package.json triggers some npm install-time reorganization that quietly
+// merges vendor/'s own subfolders into this package's root and drops the
+// file entirely (confirmed directly, by inspecting exactly what a real `npm
+// install` of a real packed tarball produces vs. what plain `tar -x` of that
+// same tarball contains - the tarball itself was correct, so this is npm's
+// install step specifically, not a packaging mistake). Writing it fresh here
+// avoids whatever triggers that.
+//
+// A published package's own devDependencies (used for local development -
+// see this package's package.json) are never installed for a consumer at
+// all, so this can't just be `asciidoctor`/`asciidoctor-pdf` deps declared
+// there instead - nothing would ever install them for anyone but a
+// contributor working on this package directly.
+
+const { spawnSync } = require('node:child_process')
+const fs = require('node:fs')
+const path = require('node:path')
+
+const vendorDir = path.join(__dirname, '../vendor')
+const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm'
+
+fs.writeFileSync(
+  path.join(vendorDir, 'package.json'),
+  JSON.stringify(
+    {
+      name: 'pdf-generator-vendor',
+      version: '1.0.0',
+      private: true,
+      dependencies: {
+        asciidoctor: '4.1.0',
+        'asciidoctor-pdf': '1.0.2',
+      },
+    },
+    null,
+    2
+  ) + '\n'
+)
+
+const result = spawnSync(npmCmd, ['install', '--omit=dev', '--no-audit', '--no-fund'], {
+  cwd: vendorDir,
+  stdio: 'inherit',
+})
+
+if (result.error || result.status !== 0) {
+  console.error('@neo4j-antora/pdf-generator: failed to install its isolated asciidoctor-pdf renderer (see vendor/package.json)')
+  process.exit(result.status || 1)
+}

package/vendor/extensions/macros-adapter.js

@@ -0,0 +1,64 @@
+'use strict'
+
+// @neo4j-documentation/macros' `label:x[]` inline macro reads
+// `attr.$positional` (pre-4.x Asciidoctor.js's Opal-bridge attribute
+// wrapper) to get the macro's positional text argument - removed in
+// Asciidoctor.js 4.x, which instead hands a plain object with 1-indexed
+// string keys (e.g. `{"1": "Custom text"}`). Without a fix, `attr.$positional`
+// is just `undefined`, so any custom inline label text (e.g.
+// `label:new[Custom text]`) is silently dropped in favour of the default
+// display text - it doesn't throw, so this is easy to miss.
+//
+// Rather than patch the vendored file with patch-package (its postinstall
+// hook isn't guaranteed to run once this package is itself a nested
+// dependency of a docset's install - npm doesn't run a dependency's own
+// lifecycle scripts by default), this wraps `registry.inlineMacro` so any
+// attrs object handed to a macro's `process` callback gets `$positional`
+// backfilled from those numeric keys, matching the shape macros.js expects.
+//
+// Must intercept via a Proxy rather than binding/replacing `self.process`
+// directly - the installed Asciidoctor.js engine here is a compiled/WASM
+// binding, and a `.bind()`'d reference to its native `process` method
+// silently never invokes the callback it's given, even though calling it
+// unbound (`target.process(fn)`) works correctly. Verified directly against
+// the unpatched package and the installed engine.
+const macros = require('@neo4j-documentation/macros')
+
+function backfillPositionalAttrs (attrs) {
+  if (!attrs || attrs.$positional) return
+  const positional = []
+  let i = 1
+  while (attrs[String(i)] !== undefined) {
+    positional.push(attrs[String(i)])
+    i++
+  }
+  if (positional.length) attrs.$positional = positional
+}
+
+function shimOpalPositionalAttrs (registry) {
+  const original = registry.inlineMacro.bind(registry)
+  registry.inlineMacro = function (name, fn) {
+    return original(name, function (...outerArgs) {
+      const target = this
+      const selfProxy = new Proxy(target, {
+        get (t, prop, receiver) {
+          if (prop === 'process') {
+            return function (processFn) {
+              return t.process(function (parent, macroTarget, attrs) {
+                backfillPositionalAttrs(attrs)
+                return processFn(parent, macroTarget, attrs)
+              })
+            }
+          }
+          return Reflect.get(t, prop, receiver)
+        },
+      })
+      return fn.apply(selfProxy, outerArgs)
+    })
+  }
+}
+
+module.exports.register = function (registry, context) {
+  shimOpalPositionalAttrs(registry)
+  macros.register(registry, context)
+}

package/vendor/extensions/remote-include-adapter.js

@@ -0,0 +1,43 @@
+'use strict'
+
+// @neo4j-documentation/remote-include exports its registration function
+// directly (`module.exports = function () { this.includeProcessor(...) }`),
+// which is what Antora's own extension loader expects, but not what
+// asciidoctor-web-pdf's --extension loader does (it requires `lib.register`
+// to be a function - see requireLibrary/_prepareExtensions in
+// asciidoctor/lib/cli.js). This bridges the two conventions.
+//
+// It also works around a second, unrelated problem: the package's own
+// includeProcessor body calls the pre-4.x Asciidoctor.js Opal-bridge API
+// (`this.$option(...)`), removed in 4.x (now `this.option(...)`) - see
+// macros-adapter.js for the same class of bug in a different package.
+// Rather than patch the vendored file with patch-package (its postinstall
+// hook isn't guaranteed to run once this package is itself a nested
+// dependency of a docset's install - npm doesn't run a dependency's own
+// lifecycle scripts by default), this wraps `registry.includeProcessor`
+// so the callback's `this` transparently answers `$option` calls by
+// forwarding to the real `option` method. Verified directly against the
+// unpatched package and the installed Asciidoctor.js engine.
+
+const remoteInclude = require('@neo4j-documentation/remote-include')
+
+function shimOpalOptionApi (registry) {
+  const original = registry.includeProcessor.bind(registry)
+  registry.includeProcessor = function (fn) {
+    return original(function (...args) {
+      const target = this
+      const self = new Proxy(target, {
+        get (t, prop, receiver) {
+          if (prop === '$option') return t.option.bind(t)
+          return Reflect.get(t, prop, receiver)
+        },
+      })
+      return fn.apply(self, args)
+    })
+  }
+}
+
+module.exports.register = function (registry) {
+  shimOpalOptionApi(registry)
+  remoteInclude.call(registry)
+}

package/vendor/extensions/roles-labels-postprocessor.js

@@ -0,0 +1,70 @@
+'use strict'
+
+// Reuses @neo4j-antora/roles-labels' own shared core (extensions/antora/
+// roles-labels/lib/process-labels.js in docs-tools) so PDF labels are
+// produced by the exact same logic as the real HTML site - synonym
+// resolution, version/product-suffix stripping, dataset attributes, inline
+// vs role handling included - rather than a hand-ported subset that can
+// silently drift from it (see docs-tools/pdf/README).
+//
+// roles-labels itself can't be *registered* here - it hooks Antora's own
+// `pagesComposed` event and operates on files in an Antora ContentCatalog,
+// which never exist in this pipeline: asciidoctor-web-pdf runs a completely
+// separate, isolated Asciidoctor conversion on the assembler's merged .adoc
+// text, so roles-labels never gets a chance to see - let alone transform -
+// this content. This is a Postprocessor instead (Asciidoctor's own extension
+// point, run after conversion to HTML, before the PDF renderer sees it) that
+// calls the same shared `processLabels` function roles-labels.js calls.
+
+const { parse: parseHTML } = require('node-html-parser')
+// Must come from the same package identity the running engine (loaded via
+// `asciidoctor`, not `@asciidoctor/core` directly, by asciidoctor-web-pdf/
+// the CLI) uses internally - requiring the class from a different copy of
+// the module fails Registry's own instanceof-style check with "Invalid type
+// for postprocessor extension" even though it's structurally identical.
+const { Postprocessor } = require('asciidoctor')
+const { processLabels } = require('@neo4j-antora/roles-labels/lib/process-labels')
+
+// Minimal shim matching the { info(meta, msg, ...args), warn(...), debug(...) }
+// shape processLabels expects from Antora's pino-based logger - this pipeline
+// has no Antora logger to reuse.
+function makeLogger () {
+  const log = (level) => (meta, msg, ...args) => {
+    const consoleMethod = level === 'debug' ? 'log' : level
+    // eslint-disable-next-line no-console
+    console[consoleMethod](`[roles-labels] ${msg}`.replace(/%s/g, () => args.shift()), meta)
+  }
+  return { info: log('info'), warn: log('warn'), error: log('error'), debug: log('debug') }
+}
+
+const logger = makeLogger()
+
+class RolesLabelsPostprocessor extends Postprocessor {
+  process (document, output) {
+    if (!output.includes('label--')) return output
+    const root = parseHTML(output)
+    processLabels(root, {
+      src: { path: 'pdf-export' },
+      attributes: document.getAttributes(),
+      logger,
+      defaultLogLevel: 'info',
+      replaceInlineLabelText: false,
+      // Plain Asciidoctor HTML5 output (used here) never has Antora's
+      // `article.doc` wrapper - falls back to the parsed root itself, since
+      // there's no better place to hang page-wide dataset attributes.
+      docRootSelector: 'article.doc',
+      // @antora/assembler marks *every* merged page's heading `discrete` to
+      // flatten section nesting/IDs across the book - unlike on a real
+      // Antora page, that's never a signal the author marked this heading as
+      // a non-section (see process-labels.js's own comment on this option),
+      // so a role on it must still become a label, exactly as it would in
+      // the HTML this page was built from.
+      skipDiscrete: false,
+    })
+    return root.toString()
+  }
+}
+
+module.exports.register = function (registry) {
+  registry.postprocessor(RolesLabelsPostprocessor)
+}

package/vendor/extensions/table-footnotes-postprocessor.js

@@ -0,0 +1,74 @@
+'use strict'
+
+// Ports @neo4j-antora/table-footnotes for the PDF pipeline: moving a table's
+// own footnotes out of Asciidoctor's single document-wide #footnotes div and
+// into a <tfoot> row on that specific table, instead of leaving them
+// dumped at the very end of the whole document, disconnected from the table
+// they came from.
+//
+// Same reason this can't just reuse table-footnotes.js directly as roles-
+// labels-postprocessor.js: it hooks Antora's own `pagesComposed` event and
+// operates on files in an Antora ContentCatalog, neither of which exist in
+// this pipeline (see docs-tools/pdf/README) - asciidoctor-web-pdf runs a
+// separate, isolated Asciidoctor conversion on the assembler's merged .adoc
+// text that table-footnotes never gets a chance to see. This is a
+// Postprocessor instead (Asciidoctor's own extension point, run after
+// conversion to HTML), with the same DOM manipulation ported over near
+// verbatim - it's pure HTML restructuring, no Antora-specific data needed.
+
+const { parse: parseHTML } = require('node-html-parser')
+// Must come from the same package identity the running engine uses
+// internally, not a separately-resolved copy - see roles-labels-
+// postprocessor.js for why requiring the class from the wrong copy of the
+// module fails Registry's own type check.
+const { Postprocessor } = require('asciidoctor')
+
+function createElement (el, className = '') {
+  return parseHTML(`<${el}${className ? ` class="${className}"` : ''}></${el}>`)
+}
+
+class TableFootnotesPostprocessor extends Postprocessor {
+  process (_document, output) {
+    if (!output.includes('id="footnotes"')) return output
+    const root = parseHTML(output)
+    const footnotesDiv = root.getElementById('footnotes')
+    const tables = root.querySelectorAll('table')
+    if (!footnotesDiv || tables.length === 0) return output
+
+    tables.forEach((table) => {
+      const tableFootnotes = table.querySelectorAll('tbody a.footnote')
+      if (tableFootnotes.length === 0) return
+
+      const cols = table.querySelectorAll('colgroup col').length
+      const tFoot = createElement('tfoot')
+      const footnoteRow = createElement('tr')
+      tFoot.firstElementChild.appendChild(footnoteRow)
+      const footnoteCell = createElement('td', 'tableblock footnote-cell')
+      footnoteCell.firstElementChild.setAttribute('colspan', cols)
+
+      // For each footnote reference in this table, find the matching
+      // footnote definition (by id, from its href) in the document-wide
+      // footnotes div, and move it into this table's own footer.
+      tableFootnotes.forEach((footnote) => {
+        const footnoteId = footnote.getAttribute('href').replace('#', '')
+        const matchingFootnote = footnotesDiv.querySelector(`#${footnoteId}`)
+        if (!matchingFootnote) return
+        footnoteCell.firstElementChild.appendChild(matchingFootnote)
+      })
+
+      footnoteRow.firstElementChild.appendChild(footnoteCell)
+      table.appendChild(tFoot)
+    })
+
+    // Remove the document-wide footnotes div if every footnote in it ended
+    // up moved into a table footer.
+    if (footnotesDiv.querySelectorAll('div.footnote').length === 0) {
+      footnotesDiv.remove()
+    }
+    return root.toString()
+  }
+}
+
+module.exports.register = function (registry) {
+  registry.postprocessor(TableFootnotesPostprocessor)
+}