@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.
|
|
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": [
|
package/pdf-theme/print.css
CHANGED
|
@@ -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,
|
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,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
|
+
}
|