@neo4j-antora/pdf-generator 0.1.9 → 0.1.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.adoc CHANGED
@@ -53,6 +53,17 @@ Either form picks up this package's own `antora-assembler-pdf.yml` as the
53
53
  default `configFile` - pass a `config:` block in the playbook form to
54
54
  override individual assembler settings if needed.
55
55
 
56
+ === Optional: PDF headings/TOC use each page's own title, not its nav title
57
+
58
+ `@antora/assembler` builds every merged page's own heading (and, from that,
59
+ the PDF's own table of contents) from the page's *nav* title, not the page's
60
+ own `= Real Title` document title - see
61
+ `@neo4j-antora/real-title-navtitle` (a standalone package, deliberately not
62
+ nested in this one - this one's own `postinstall` sets up a full
63
+ `asciidoctor-pdf`/Puppeteer vendor tree, too heavy to be a permanent
64
+ dependency of a docset's plain HTML build, which this fix also needs to run
65
+ during) for the fix and the full explanation.
66
+
56
67
  == Layout
57
68
 
58
69
  - `antora-assembler-pdf.yml` - Assembler config, pointed at from a docset's
@@ -92,6 +103,12 @@ override individual assembler settings if needed.
92
103
  already run.
93
104
  - `extensions/` - `roles-labels-postprocessor.js` ports the essential parts
94
105
  of the Antora extension of the same name (see "Known limitations" below);
106
+ `tabbed-example-postprocessor.js` labels each alternative of a
107
+ `[.tabbed-example]`/`[.include-with-X]` group with its own real-site tab
108
+ text (ported directly from the real site's own client-side JS, which
109
+ derives it the same way - never runs in a static PDF) and un-nests the
110
+ real site's own double border on the group, since both come from a
111
+ client-side tab widget this renderer has no equivalent of;
95
112
  `macros-adapter.js` and `remote-include-adapter.js` wrap the real
96
113
  `@neo4j-documentation/macros`/`remote-include` packages, fixing a
97
114
  pre-4.x-Asciidoctor.js API incompatibility in each at runtime (see their
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@neo4j-antora/pdf-generator",
3
- "version": "0.1.9",
3
+ "version": "0.1.10",
4
4
  "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",
5
5
  "main": "extension.js",
6
6
  "files": [
@@ -540,6 +540,40 @@ body.book {
540
540
  }
541
541
  #pdf-export .admonitionblock.tip td.content > .title { color: var(--brand-success); }
542
542
 
543
+ /* tabbed examples - `[.tabbed-example]` wraps several `[.include-with-X]` example
544
+ blocks; the real site's own client-side JS (site.js) turns these into an actual
545
+ clickable tab widget - see tabbed-example-postprocessor.js's own comment for the full
546
+ explanation and where the `.tabbed-example-label` div it inserts comes from. Real
547
+ site.css's own plain, unscoped `.exampleblock{border:1px solid ...;border-radius:8px}`
548
+ applies to both the outer wrapper and each inner alternative, since both carry the base
549
+ `exampleblock` class - the real site has its own fix for this
550
+ (`.tabbed-container>.exampleblock>.content{border:none}`), scoped to a wrapper class
551
+ client-side JS adds at runtime, which never exists in this static render. Stripping the
552
+ outer wrapper's own border/background/padding here leaves only each inner alternative
553
+ with its own single, clean box - reported directly: nested double borders, "ugly". */
554
+ #pdf-export .exampleblock.tabbed-example {
555
+ border: none;
556
+ background: none;
557
+ padding: 0;
558
+ margin: 0;
559
+ }
560
+ #pdf-export .exampleblock.tabbed-example > .content {
561
+ padding: 0;
562
+ }
563
+ /* A bold, non-italic label reads better here than real site.css's own generic
564
+ `.exampleblock .title` caption style (small, italic - built for a figure caption, not
565
+ for "which of these alternatives is this"), so this is deliberately its own rule
566
+ rather than reusing that one, even though the postprocessor also adds the genuine
567
+ `title` class alongside it (for docsets that prefer the plain caption look without
568
+ this override). */
569
+ #pdf-export .tabbed-example-label {
570
+ font-style: normal;
571
+ font-weight: 700;
572
+ font-size: 9.5pt;
573
+ color: var(--brand-primary-strong);
574
+ margin-bottom: 4pt;
575
+ }
576
+
543
577
  /* quoteblocks - includes a page's own [abstract]/{description} block (every page
544
578
  authors `[abstract]\n{description}` right after its own title), which Asciidoctor
545
579
  renders as a plain, unstyled quoteblock - this theme never styled quoteblocks at all,
@@ -36,6 +36,7 @@ const COLOPHON_POSTPROCESSOR = path.join(__dirname, '../vendor/extensions/coloph
36
36
  const ABSOLUTE_LINKS_POSTPROCESSOR = path.join(__dirname, '../vendor/extensions/absolute-links-postprocessor.js')
37
37
  const DOC_WRAPPER_POSTPROCESSOR = path.join(__dirname, '../vendor/extensions/doc-wrapper-postprocessor.js')
38
38
  const CYPHER_LANGUAGE_ADAPTER = path.join(__dirname, '../vendor/extensions/cypher-language-adapter.js')
39
+ const TABBED_EXAMPLE_POSTPROCESSOR = path.join(__dirname, '../vendor/extensions/tabbed-example-postprocessor.js')
39
40
 
40
41
  // Unlike the extensions above, `@djencks/asciidoctor-mathjax` isn't a
41
42
  // dependency of this package - it's an opt-in feature a docset adds itself
@@ -292,6 +293,7 @@ Promise.all([buildStylesheet(), readStdin()]).then(([stylesheet, adoc]) => {
292
293
  '--extension', COLOPHON_POSTPROCESSOR,
293
294
  '--extension', ABSOLUTE_LINKS_POSTPROCESSOR,
294
295
  '--extension', DOC_WRAPPER_POSTPROCESSOR,
296
+ '--extension', TABBED_EXAMPLE_POSTPROCESSOR,
295
297
  ]
296
298
  const prefix = linkPrefix()
297
299
  if (prefix) extraArgs.push('-a', `absolute-link-prefix=${prefix}`)
@@ -0,0 +1,66 @@
1
+ 'use strict'
2
+
3
+ // On the real site, `[.tabbed-example]` wraps several `[.include-with-<name>]` example
4
+ // blocks, and client-side JS (site.js) moves them into an actual clickable tab widget,
5
+ // deriving each tab's own visible button text from its `include-with-<name>` role - e.g.
6
+ // `include-with-procedure-integration-tests` becomes the tab labelled "Procedure
7
+ // integration tests". None of that JS ever runs in a static PDF, so without this
8
+ // postprocessor, every `[.include-with-X]` alternative just renders as a plain, unlabelled
9
+ // box, stacked one after another with no indication these are alternatives at all, let
10
+ // alone which is which - reported directly: multiple near-identical Java test examples
11
+ // shown back to back with nothing to tell them apart.
12
+ //
13
+ // This runs as a Postprocessor (after HTML conversion, same point roles-labels-
14
+ // postprocessor.js and absolute-links-postprocessor.js already operate at) rather than
15
+ // manipulating the Asciidoctor document tree before conversion - simpler to reuse
16
+ // node-html-parser's own CSS-selector-based DOM API than Asciidoctor's own block-title
17
+ // API, and this pipeline already depends on node-html-parser for exactly this purpose
18
+ // (see roles-labels-postprocessor.js).
19
+ //
20
+ // Label text derivation ported directly from the real site's own site.js (the exact
21
+ // function that builds each tab's clickable button text) - confirmed directly by fetching
22
+ // and reading it: replace hyphens with spaces, capitalize only the first letter (not
23
+ // title-case), with a handful of names special-cased to match a real human label
24
+ // (`csharp`/`dotnet` -> "C#", `javascript` -> "JavaScript", `macos` -> "macOS"). The real
25
+ // function also handles version-number segments (e.g. a `neo4j-5-20`-style role becoming
26
+ // "Neo4j 5.20") - not ported here, since no content in this pipeline's docsets uses that
27
+ // pattern; add it if one ever does.
28
+ const { Postprocessor } = require('asciidoctor')
29
+ const { parse: parseHTML } = require('node-html-parser')
30
+
31
+ const SPECIAL_LABELS = {
32
+ csharp: 'C#',
33
+ dotnet: 'C#',
34
+ javascript: 'JavaScript',
35
+ macos: 'macOS',
36
+ }
37
+
38
+ function deriveLabel (roleName) {
39
+ if (roleName in SPECIAL_LABELS) return SPECIAL_LABELS[roleName]
40
+ const spaced = roleName.replace(/-/g, ' ')
41
+ return spaced.charAt(0).toUpperCase() + spaced.slice(1)
42
+ }
43
+
44
+ class TabbedExamplePostprocessor extends Postprocessor {
45
+ process (_document, output) {
46
+ if (!output.includes('tabbed-example')) return output
47
+ const root = parseHTML(output)
48
+ root.querySelectorAll('.exampleblock.tabbed-example').forEach((wrapper) => {
49
+ wrapper.querySelectorAll(':scope > .content > .exampleblock').forEach((variant) => {
50
+ const roleClass = variant.classList.value.find((cls) => cls.startsWith('include-with-'))
51
+ if (!roleClass) return
52
+ const label = deriveLabel(roleClass.slice('include-with-'.length))
53
+ const content = variant.querySelector(':scope > .content')
54
+ ;(content || variant).insertAdjacentHTML(
55
+ 'afterbegin',
56
+ `<div class="title tabbed-example-label">${label}</div>`
57
+ )
58
+ })
59
+ })
60
+ return root.toString()
61
+ }
62
+ }
63
+
64
+ module.exports.register = function (registry) {
65
+ registry.postprocessor(TabbedExamplePostprocessor)
66
+ }