@neo4j-antora/pdf-generator 0.1.9 → 0.1.11

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.11",
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,91 @@ 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
+ /* No border/box at all on each alternative - the postprocessor's own jump-list (just
564
+ below) now does the job a border/accent bar was standing in for, making the grouping
565
+ explicit and navigable rather than merely visual. A box or accent bar also always had
566
+ an edge to look visibly cut when an alternative started near the bottom of a page and
567
+ flowed onto the next one; a plain block in the normal page flow has no such edge.
568
+ A thin rule between alternatives (same weight/colour as the rule under the jump-list)
569
+ still marks where one ends and the next begins, without a box's open top/bottom edge
570
+ problem - omitted after the last alternative, since real content already follows there. */
571
+ #pdf-export .exampleblock.tabbed-example > .content > .exampleblock {
572
+ border: none;
573
+ background: none;
574
+ padding: 0 0 1em;
575
+ margin: 0 0 1em;
576
+ }
577
+ #pdf-export .exampleblock.tabbed-example > .content > .exampleblock:not(:last-child) {
578
+ border-bottom: 0.5pt solid var(--brand-border-strong);
579
+ }
580
+ /* Each alternative's own nested `.content` carries real site.css's default exampleblock
581
+ padding, which otherwise left the section title/body sitting further right than the
582
+ surrounding body copy - zeroed so a section's title/body flush-aligns with ordinary
583
+ paragraphs outside the group, same as the jump-list below. */
584
+ #pdf-export .exampleblock.tabbed-example > .content > .exampleblock > .content {
585
+ padding: 0;
586
+ }
587
+ /* The jump-list the postprocessor inserts at the top of each group, one link per
588
+ alternative, jumping down to that alternative's own anchor - stands in for the real
589
+ site's clickable tab strip, and is what now carries the "these are alternatives of the
590
+ same thing" signal that a border/accent bar used to carry on its own. Styled distinctly
591
+ from an ordinary body list - smaller, numbers and link text in the same brand colour as
592
+ `.tabbed-example-label` below (visually tying the two together as one feature), with a
593
+ thin rule underneath to cap the group off as a single self-contained unit, rather than
594
+ reading as a stray numbered list dropped into the middle of running prose.
595
+ `list-style-position: inside` (rather than a left `padding`) keeps the numbers flush
596
+ with the surrounding body margin instead of hanging further left or indenting the text
597
+ further right - full left-align with everything else on the page, including the
598
+ sections themselves. */
599
+ #pdf-export .tabbed-example-list {
600
+ margin: 0 0 1em;
601
+ padding: 0 0 0.75em;
602
+ list-style-position: inside;
603
+ font-size: 9.5pt;
604
+ border-bottom: 0.5pt solid var(--brand-border-strong);
605
+ }
606
+ #pdf-export .tabbed-example-list > li::marker {
607
+ color: var(--brand-primary-strong);
608
+ font-weight: 700;
609
+ }
610
+ #pdf-export .tabbed-example-list a {
611
+ color: var(--brand-primary-strong);
612
+ font-weight: 600;
613
+ }
614
+ /* A bold, non-italic label reads better here than real site.css's own generic
615
+ `.exampleblock .title` caption style (small, italic - built for a figure caption, not
616
+ for "which of these alternatives is this"), so this is deliberately its own rule
617
+ rather than reusing that one, even though the postprocessor also adds the genuine
618
+ `title` class alongside it (for docsets that prefer the plain caption look without
619
+ this override). */
620
+ #pdf-export .tabbed-example-label {
621
+ font-style: normal;
622
+ font-weight: 700;
623
+ font-size: 9.5pt;
624
+ color: var(--brand-primary-strong);
625
+ margin-bottom: 4pt;
626
+ }
627
+
543
628
  /* quoteblocks - includes a page's own [abstract]/{description} block (every page
544
629
  authors `[abstract]\n{description}` right after its own title), which Asciidoctor
545
630
  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,93 @@
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
+ // Beyond labelling each alternative in place, this also inserts a short numbered list of
14
+ // internal links at the top of the group (where the HTML tab-switcher buttons would have
15
+ // been), one per alternative, each jumping down to that alternative's own section - the
16
+ // label alone says "you are now reading the X alternative", but doesn't tell a reader
17
+ // browsing linearly, before reaching the group, that several alternatives of the same
18
+ // thing are coming up and what they are; the list makes that grouping explicit and
19
+ // navigable, the way the real tab strip does on the live site.
20
+ //
21
+ // This runs as a Postprocessor (after HTML conversion, same point roles-labels-
22
+ // postprocessor.js and absolute-links-postprocessor.js already operate at) rather than
23
+ // manipulating the Asciidoctor document tree before conversion - simpler to reuse
24
+ // node-html-parser's own CSS-selector-based DOM API than Asciidoctor's own block-title
25
+ // API, and this pipeline already depends on node-html-parser for exactly this purpose
26
+ // (see roles-labels-postprocessor.js). It also runs once against the *whole*, already-
27
+ // merged book (the assembler hands this renderer one combined document, not one page at a
28
+ // time), so anchor IDs are minted from a counter kept for the lifetime of a single
29
+ // process() call, not derived from role names alone - two different pages using the same
30
+ // role name (e.g. both having an `include-with-java` alternative) would otherwise collide.
31
+ //
32
+ // Label text derivation ported directly from the real site's own site.js (the exact
33
+ // function that builds each tab's clickable button text) - confirmed directly by fetching
34
+ // and reading it: replace hyphens with spaces, capitalize only the first letter (not
35
+ // title-case), with a handful of names special-cased to match a real human label
36
+ // (`csharp`/`dotnet` -> "C#", `javascript` -> "JavaScript", `macos` -> "macOS"). The real
37
+ // function also handles version-number segments (e.g. a `neo4j-5-20`-style role becoming
38
+ // "Neo4j 5.20") - not ported here, since no content in this pipeline's docsets uses that
39
+ // pattern; add it if one ever does.
40
+ const { Postprocessor } = require('asciidoctor')
41
+ const { parse: parseHTML } = require('node-html-parser')
42
+
43
+ const SPECIAL_LABELS = {
44
+ csharp: 'C#',
45
+ dotnet: 'C#',
46
+ javascript: 'JavaScript',
47
+ macos: 'macOS',
48
+ }
49
+
50
+ function deriveLabel (roleName) {
51
+ if (roleName in SPECIAL_LABELS) return SPECIAL_LABELS[roleName]
52
+ const spaced = roleName.replace(/-/g, ' ')
53
+ return spaced.charAt(0).toUpperCase() + spaced.slice(1)
54
+ }
55
+
56
+ function escapeHtml (text) {
57
+ return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
58
+ }
59
+
60
+ class TabbedExamplePostprocessor extends Postprocessor {
61
+ process (_document, output) {
62
+ if (!output.includes('tabbed-example')) return output
63
+ const root = parseHTML(output)
64
+ let groupCounter = 0
65
+ root.querySelectorAll('.exampleblock.tabbed-example').forEach((wrapper) => {
66
+ groupCounter++
67
+ const listItems = []
68
+ let variantCounter = 0
69
+ wrapper.querySelectorAll(':scope > .content > .exampleblock').forEach((variant) => {
70
+ const roleClass = variant.classList.value.find((cls) => cls.startsWith('include-with-'))
71
+ if (!roleClass) return
72
+ variantCounter++
73
+ const label = deriveLabel(roleClass.slice('include-with-'.length))
74
+ const anchorId = `tabbed-example-${groupCounter}-${variantCounter}`
75
+ variant.setAttribute('id', anchorId)
76
+ const content = variant.querySelector(':scope > .content')
77
+ ;(content || variant).insertAdjacentHTML(
78
+ 'afterbegin',
79
+ `<div class="title tabbed-example-label">${escapeHtml(label)}</div>`
80
+ )
81
+ listItems.push(`<li><a href="#${anchorId}">${escapeHtml(label)}</a></li>`)
82
+ })
83
+ if (listItems.length > 1) {
84
+ wrapper.insertAdjacentHTML('afterbegin', `<ol class="tabbed-example-list">${listItems.join('')}</ol>`)
85
+ }
86
+ })
87
+ return root.toString()
88
+ }
89
+ }
90
+
91
+ module.exports.register = function (registry) {
92
+ registry.postprocessor(TabbedExamplePostprocessor)
93
+ }