@neo4j-antora/pdf-generator 0.1.10 → 0.1.12

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@neo4j-antora/pdf-generator",
3
- "version": "0.1.10",
3
+ "version": "0.1.12",
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": [
@@ -25,7 +25,7 @@
25
25
  "license": "MIT",
26
26
  "dependencies": {
27
27
  "@antora/pdf-extension": "1.0.0",
28
- "@neo4j-antora/roles-labels": "0.1.14",
28
+ "@neo4j-antora/roles-labels": "0.1.15",
29
29
  "@neo4j-documentation/macros": "1.0.4",
30
30
  "@neo4j-documentation/remote-include": "1.0.0",
31
31
  "node-html-parser": "9.0.4"
@@ -560,6 +560,57 @@ body.book {
560
560
  #pdf-export .exampleblock.tabbed-example > .content {
561
561
  padding: 0;
562
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
+ }
563
614
  /* A bold, non-italic label reads better here than real site.css's own generic
564
615
  `.exampleblock .title` caption style (small, italic - built for a figure caption, not
565
616
  for "which of these alternatives is this"), so this is deliberately its own rule
@@ -10,12 +10,24 @@
10
10
  // alone which is which - reported directly: multiple near-identical Java test examples
11
11
  // shown back to back with nothing to tell them apart.
12
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
+ //
13
21
  // This runs as a Postprocessor (after HTML conversion, same point roles-labels-
14
22
  // postprocessor.js and absolute-links-postprocessor.js already operate at) rather than
15
23
  // manipulating the Asciidoctor document tree before conversion - simpler to reuse
16
24
  // node-html-parser's own CSS-selector-based DOM API than Asciidoctor's own block-title
17
25
  // API, and this pipeline already depends on node-html-parser for exactly this purpose
18
- // (see roles-labels-postprocessor.js).
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.
19
31
  //
20
32
  // Label text derivation ported directly from the real site's own site.js (the exact
21
33
  // function that builds each tab's clickable button text) - confirmed directly by fetching
@@ -41,21 +53,36 @@ function deriveLabel (roleName) {
41
53
  return spaced.charAt(0).toUpperCase() + spaced.slice(1)
42
54
  }
43
55
 
56
+ function escapeHtml (text) {
57
+ return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
58
+ }
59
+
44
60
  class TabbedExamplePostprocessor extends Postprocessor {
45
61
  process (_document, output) {
46
62
  if (!output.includes('tabbed-example')) return output
47
63
  const root = parseHTML(output)
64
+ let groupCounter = 0
48
65
  root.querySelectorAll('.exampleblock.tabbed-example').forEach((wrapper) => {
66
+ groupCounter++
67
+ const listItems = []
68
+ let variantCounter = 0
49
69
  wrapper.querySelectorAll(':scope > .content > .exampleblock').forEach((variant) => {
50
70
  const roleClass = variant.classList.value.find((cls) => cls.startsWith('include-with-'))
51
71
  if (!roleClass) return
72
+ variantCounter++
52
73
  const label = deriveLabel(roleClass.slice('include-with-'.length))
74
+ const anchorId = `tabbed-example-${groupCounter}-${variantCounter}`
75
+ variant.setAttribute('id', anchorId)
53
76
  const content = variant.querySelector(':scope > .content')
54
77
  ;(content || variant).insertAdjacentHTML(
55
78
  'afterbegin',
56
- `<div class="title tabbed-example-label">${label}</div>`
79
+ `<div class="title tabbed-example-label">${escapeHtml(label)}</div>`
57
80
  )
81
+ listItems.push(`<li><a href="#${anchorId}">${escapeHtml(label)}</a></li>`)
58
82
  })
83
+ if (listItems.length > 1) {
84
+ wrapper.insertAdjacentHTML('afterbegin', `<ol class="tabbed-example-list">${listItems.join('')}</ol>`)
85
+ }
59
86
  })
60
87
  return root.toString()
61
88
  }