@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.
|
|
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": [
|
package/pdf-theme/print.css
CHANGED
|
@@ -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,
|
package/scripts/convert.js
CHANGED
|
@@ -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, '&').replace(/</g, '<').replace(/>/g, '>')
|
|
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
|
+
}
|