@neo4j-antora/pdf-generator 0.1.5 → 0.1.7
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/antora-assembler-pdf.yml +1 -1
- package/package.json +2 -1
- package/pages/license.adoc +34 -0
- package/pdf-theme/print.css +83 -13
- package/scripts/convert.js +86 -3
- package/vendor/extensions/absolute-links-postprocessor.js +55 -0
- package/vendor/extensions/colophon-postprocessor.js +68 -0
- package/vendor/extensions/mathjax-adapter.js +69 -0
package/antora-assembler-pdf.yml
CHANGED
package/package.json
CHANGED
|
@@ -1,11 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@neo4j-antora/pdf-generator",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.7",
|
|
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": [
|
|
7
7
|
"extension.js",
|
|
8
8
|
"antora-assembler-pdf.yml",
|
|
9
|
+
"pages",
|
|
9
10
|
"pdf-theme",
|
|
10
11
|
"scripts",
|
|
11
12
|
"vendor/extensions",
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
[discrete]
|
|
2
|
+
[[license]]
|
|
3
|
+
== License
|
|
4
|
+
|
|
5
|
+
Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0)
|
|
6
|
+
|
|
7
|
+
.You are free to
|
|
8
|
+
|
|
9
|
+
Share:: copy and redistribute the material in any medium or format
|
|
10
|
+
Adapt:: remix, transform, and build upon the material
|
|
11
|
+
|
|
12
|
+
The licensor cannot revoke these freedoms as long as you follow the license terms.
|
|
13
|
+
|
|
14
|
+
.Under the following terms
|
|
15
|
+
|
|
16
|
+
Attribution::
|
|
17
|
+
You must give appropriate credit, provide a link to the license, and indicate if changes were made.
|
|
18
|
+
You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
|
|
19
|
+
NonCommercial::
|
|
20
|
+
You may not use the material for commercial purposes.
|
|
21
|
+
ShareAlike::
|
|
22
|
+
If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.
|
|
23
|
+
No additional restrictions::
|
|
24
|
+
You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.
|
|
25
|
+
|
|
26
|
+
.Notices
|
|
27
|
+
You do not have to comply with the license for elements of the material in the public domain or where your use is permitted by an applicable exception or limitation.
|
|
28
|
+
|
|
29
|
+
No warranties are given.
|
|
30
|
+
The license may not give you all of the permissions necessary for your intended use.
|
|
31
|
+
For example, other rights such as publicity, privacy, or moral rights may limit how you use the material.
|
|
32
|
+
|
|
33
|
+
See https://creativecommons.org/licenses/by-nc-sa/4.0/ for further details.
|
|
34
|
+
The full license text is available at https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode.
|
package/pdf-theme/print.css
CHANGED
|
@@ -124,6 +124,36 @@ body.book {
|
|
|
124
124
|
display: none;
|
|
125
125
|
}
|
|
126
126
|
|
|
127
|
+
/* Colophon (added by colophon-postprocessor.js, right after the cover/
|
|
128
|
+
title page and before the table of contents) - the one-time copyright/
|
|
129
|
+
trademark boilerplate statement this pipeline uses in place of running
|
|
130
|
+
@neo4j-antora/mark-terms's inline, per-page marks (see this package's
|
|
131
|
+
own README).
|
|
132
|
+
`height: 100%` doesn't resolve here - this renderer's Vivliostyle Viewer
|
|
133
|
+
layout engine doesn't give this box a definite containing-block height
|
|
134
|
+
to be a percentage of, so centering silently no-ops. 252mm is the actual
|
|
135
|
+
per-page content height this theme produces: A4 (297mm) minus this
|
|
136
|
+
file's own `@page` rule above (25mm top margin, 20mm bottom) - update
|
|
137
|
+
this alongside that rule if it ever changes. */
|
|
138
|
+
#colophon {
|
|
139
|
+
page-break-after: always;
|
|
140
|
+
height: 252mm;
|
|
141
|
+
display: flex;
|
|
142
|
+
flex-direction: column;
|
|
143
|
+
justify-content: center;
|
|
144
|
+
font-family: var(--font-body);
|
|
145
|
+
}
|
|
146
|
+
#colophon h1 {
|
|
147
|
+
font-size: 22pt;
|
|
148
|
+
margin-bottom: 16pt;
|
|
149
|
+
}
|
|
150
|
+
#colophon p {
|
|
151
|
+
font-size: 9pt;
|
|
152
|
+
line-height: 1.5;
|
|
153
|
+
color: var(--brand-text-weak);
|
|
154
|
+
margin: 0 0 0.75em;
|
|
155
|
+
}
|
|
156
|
+
|
|
127
157
|
/* Table of contents */
|
|
128
158
|
#toc {
|
|
129
159
|
page-break-after: always;
|
|
@@ -143,23 +173,31 @@ body.book {
|
|
|
143
173
|
margin-left: 0;
|
|
144
174
|
padding-left: 0;
|
|
145
175
|
}
|
|
146
|
-
|
|
176
|
+
/* Asciidoctor's own TOC class names are 1-indexed (sectlevel1 is the outermost list, for
|
|
177
|
+
level-1/== headings - there is no sectlevel0), not 0-indexed - these selectors used to
|
|
178
|
+
target sectlevel0/sectlevel1, which Asciidoctor's TOC markup never actually emits, so
|
|
179
|
+
this indentation (and the top-level bold/colour styling below) was a silent no-op in
|
|
180
|
+
every PDF this pipeline has ever shipped. */
|
|
181
|
+
#toc ul.sectlevel1 {
|
|
147
182
|
margin-left: 0;
|
|
148
183
|
}
|
|
149
|
-
#toc ul ul.
|
|
184
|
+
#toc ul ul.sectlevel2 {
|
|
150
185
|
margin-left: 14pt;
|
|
151
186
|
}
|
|
187
|
+
#toc ul ul ul.sectlevel3 {
|
|
188
|
+
margin-left: 28pt;
|
|
189
|
+
}
|
|
152
190
|
#toc li {
|
|
153
191
|
margin-top: 6pt;
|
|
154
192
|
line-height: 1.4;
|
|
155
193
|
}
|
|
156
194
|
#toc a {
|
|
157
|
-
display:
|
|
195
|
+
display: block;
|
|
158
196
|
color: var(--brand-text);
|
|
159
197
|
text-decoration: none;
|
|
160
198
|
font-size: 10.5pt;
|
|
161
199
|
}
|
|
162
|
-
#toc ul.
|
|
200
|
+
#toc ul.sectlevel1 > li > a {
|
|
163
201
|
font-weight: 600;
|
|
164
202
|
font-style: normal;
|
|
165
203
|
color: var(--brand-primary-strong);
|
|
@@ -173,15 +211,35 @@ body.book {
|
|
|
173
211
|
.sect1 { break-before: page; }
|
|
174
212
|
.sect1:first-child { break-before: avoid; }
|
|
175
213
|
|
|
214
|
+
/* The closing License page (convert.js always appends one - see its own comment) is a
|
|
215
|
+
[discrete] heading, so it isn't wrapped in a .sect1 div the way every real chapter is,
|
|
216
|
+
and therefore doesn't inherit the page-break-before rule above. */
|
|
217
|
+
#license { break-before: page; }
|
|
218
|
+
|
|
176
219
|
h1, h2, h3, h4, h5, h6 {
|
|
177
220
|
font-family: var(--font-body);
|
|
178
221
|
color: var(--brand-primary-strong);
|
|
179
222
|
font-weight: 700;
|
|
180
223
|
break-after: avoid;
|
|
181
224
|
}
|
|
182
|
-
h2
|
|
183
|
-
|
|
184
|
-
|
|
225
|
+
/* h2 is this book's chapter title (every merged page's own top-level heading - see
|
|
226
|
+
convert.js's own comment on heading levels) - testing locally against docs-java-reference
|
|
227
|
+
per a style pass comparing against the legacy pipeline's own output, where chapter
|
|
228
|
+
titles were much more prominent than this theme's original 18pt. */
|
|
229
|
+
h2 { font-size: 26pt; border-bottom: 1pt solid var(--brand-border); padding-bottom: 6pt; }
|
|
230
|
+
h3 { font-size: 18pt; }
|
|
231
|
+
h4 { font-size: 14pt; }
|
|
232
|
+
/* A page nested two levels deep in its component's nav (e.g. a page under a sub-chapter)
|
|
233
|
+
has its own internal headings shifted down by that same nav depth once merged into this
|
|
234
|
+
book, same as the page's own top heading is (see convert.js's comment on heading
|
|
235
|
+
levels) - a heading the source HTML renders as h3/h4 can easily land as h5/h6 here.
|
|
236
|
+
h5/h6 had no size rule at all before this, so they fell back to the renderer's tiny
|
|
237
|
+
unstyled defaults - barely legible next to 10.5pt body text. h6 is Asciidoctor's deepest
|
|
238
|
+
possible heading level, so it gets no further room to shrink into here; italicizing it
|
|
239
|
+
instead of sizing it down keeps it readable as a heading at a size this close to body
|
|
240
|
+
text. */
|
|
241
|
+
h5 { font-size: 12pt; }
|
|
242
|
+
h6 { font-size: 11pt; font-style: italic; }
|
|
185
243
|
|
|
186
244
|
a { color: var(--brand-primary); text-decoration: none; }
|
|
187
245
|
|
|
@@ -437,19 +495,31 @@ div.labels {
|
|
|
437
495
|
align-items: flex-start;
|
|
438
496
|
flex-direction: row-reverse;
|
|
439
497
|
}
|
|
498
|
+
/* On the real site, `.header-label-container > div.labels` sits inline to the right of
|
|
499
|
+
its title by default, and client-side JS adds `.wrapped` (below, full-width) only when
|
|
500
|
+
the title doesn't have room to share its line with the labels. That JS never runs here
|
|
501
|
+
- there's no live layout to measure against in a static PDF render - so this static
|
|
502
|
+
theme always applies the "wrapped" styling outright instead of the pre-JS default,
|
|
503
|
+
rather than ever trying to fit a label beside a title on the page's fixed, narrow
|
|
504
|
+
content width. */
|
|
440
505
|
.header-label-container {
|
|
441
|
-
display:
|
|
442
|
-
|
|
506
|
+
display: block;
|
|
507
|
+
/* .header-label-container is always the heading element itself (see
|
|
508
|
+
process-labels.js's own labelsLocation logic) with its labels div appended as a
|
|
509
|
+
child, not a sibling - so without this, a heading whose title text just barely
|
|
510
|
+
fits at the bottom of a page can have its labels div alone pushed onto the next
|
|
511
|
+
page, split from the title it belongs to. break-inside keeps the whole heading
|
|
512
|
+
(title text + labels) together as one unit, moving it to the next page entirely
|
|
513
|
+
when it doesn't fit, the same way a heading on its own already does via
|
|
514
|
+
h1..h6's break-after: avoid. */
|
|
515
|
+
break-inside: avoid;
|
|
443
516
|
}
|
|
444
517
|
.admonitionblock div.labels { padding: 0.5rem 0 1rem; }
|
|
445
518
|
.exampleblock div.labels { padding: 0.5rem; }
|
|
446
519
|
.header-label-container > div.labels {
|
|
447
|
-
justify-content: space-between;
|
|
448
|
-
margin-left: auto;
|
|
449
|
-
}
|
|
450
|
-
.header-label-container > div.labels.wrapped {
|
|
451
520
|
margin-left: 0;
|
|
452
521
|
margin-top: 0.5rem;
|
|
522
|
+
justify-content: flex-start;
|
|
453
523
|
}
|
|
454
524
|
h1 > .header-label {
|
|
455
525
|
margin-top: 1.2rem;
|
package/scripts/convert.js
CHANGED
|
@@ -7,6 +7,7 @@
|
|
|
7
7
|
// node_modules happens to hoist things - see this package's own README.
|
|
8
8
|
|
|
9
9
|
const { spawn } = require('node:child_process')
|
|
10
|
+
const fs = require('node:fs')
|
|
10
11
|
const path = require('node:path')
|
|
11
12
|
|
|
12
13
|
// asciidoctor-pdf needs @asciidoctor/core 4.x while Antora needs 2.x, and it
|
|
@@ -29,6 +30,40 @@ const STYLESHEET = path.join(__dirname, '../pdf-theme/print.css')
|
|
|
29
30
|
const ROLES_LABELS_POSTPROCESSOR = path.join(__dirname, '../vendor/extensions/roles-labels-postprocessor.js')
|
|
30
31
|
const REMOTE_INCLUDE_ADAPTER = path.join(__dirname, '../vendor/extensions/remote-include-adapter.js')
|
|
31
32
|
const MACROS_ADAPTER = path.join(__dirname, '../vendor/extensions/macros-adapter.js')
|
|
33
|
+
const MATHJAX_ADAPTER = path.join(__dirname, '../vendor/extensions/mathjax-adapter.js')
|
|
34
|
+
const COLOPHON_POSTPROCESSOR = path.join(__dirname, '../vendor/extensions/colophon-postprocessor.js')
|
|
35
|
+
const ABSOLUTE_LINKS_POSTPROCESSOR = path.join(__dirname, '../vendor/extensions/absolute-links-postprocessor.js')
|
|
36
|
+
|
|
37
|
+
// Unlike the extensions above, `@djencks/asciidoctor-mathjax` isn't a
|
|
38
|
+
// dependency of this package - it's an opt-in feature a docset adds itself
|
|
39
|
+
// (alongside registering it in its own preview.yml, for the live HTML site)
|
|
40
|
+
// only if it actually uses `stem`/`latexmath` blocks. Registering it here
|
|
41
|
+
// only when the docset's own install actually has it keeps every other
|
|
42
|
+
// docset's PDF build unaffected (no extra dependency, nothing to fail).
|
|
43
|
+
//
|
|
44
|
+
// A plain `require.resolve` walks up from *this file's own real location*
|
|
45
|
+
// (Node dereferences symlinks before resolving), which is this package's
|
|
46
|
+
// own install under the docset's node_modules in the normal case - fine.
|
|
47
|
+
// But under `npm link` (this package developed as a local checkout,
|
|
48
|
+
// symlinked into a docset for testing), that real location is somewhere
|
|
49
|
+
// else entirely, so the docset's own node_modules is never on the search
|
|
50
|
+
// path and this always reports unavailable even when the docset has the
|
|
51
|
+
// package. Falling back to a resolve rooted at the working directory
|
|
52
|
+
// (antora's own cwd is always the docset being built) covers that case
|
|
53
|
+
// too, without changing anything for a normal, non-linked install.
|
|
54
|
+
function mathjaxAvailable () {
|
|
55
|
+
try {
|
|
56
|
+
require.resolve('@djencks/asciidoctor-mathjax')
|
|
57
|
+
return true
|
|
58
|
+
} catch {
|
|
59
|
+
try {
|
|
60
|
+
require.resolve('@djencks/asciidoctor-mathjax', { paths: [process.cwd()] })
|
|
61
|
+
return true
|
|
62
|
+
} catch {
|
|
63
|
+
return false
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
}
|
|
32
67
|
|
|
33
68
|
const PAGE_BOUNDARY_RX = /(?=^:page-docname: .*$)/m
|
|
34
69
|
const GLOSSARY_MARKER_RX = /^\[discrete\.glossary#.*\]$/m
|
|
@@ -67,6 +102,22 @@ function dedupeGlossary (adoc) {
|
|
|
67
102
|
return result
|
|
68
103
|
}
|
|
69
104
|
|
|
105
|
+
// Every PDF this pipeline produces gets the same closing License page appended -
|
|
106
|
+
// not a per-docset opt-in, the same way the old Gradle pipeline's build.gradle
|
|
107
|
+
// unconditionally appended its own copy of this page to every book's pdfNav.
|
|
108
|
+
// Vendored here (rather than read from a consuming docset's own content, the
|
|
109
|
+
// way a couple of repos still happen to carry a copy of this exact page at
|
|
110
|
+
// modules/ROOT/pages/license.adoc left over from that old pipeline, unused by
|
|
111
|
+
// their nav and therefore invisible to this one) so every docset gets it
|
|
112
|
+
// identically regardless of what that docset's own content tree does or
|
|
113
|
+
// doesn't contain. `[discrete]` keeps it out of the book's own table of
|
|
114
|
+
// contents, same as a real book's colophon page; the heading is still a
|
|
115
|
+
// level-1 (`==`) heading, matching every other chapter this pipeline merges
|
|
116
|
+
// in, so it inherits the same typography - only the page-break-before (since a
|
|
117
|
+
// discrete heading, unlike a real chapter, isn't wrapped in its own `.sect1`)
|
|
118
|
+
// needs a dedicated rule in print.css.
|
|
119
|
+
const LICENSE_PAGE = fs.readFileSync(path.join(__dirname, '../pages/license.adoc'), 'utf8')
|
|
120
|
+
|
|
70
121
|
function readStdin () {
|
|
71
122
|
const chunks = []
|
|
72
123
|
return new Promise((resolve, reject) => {
|
|
@@ -93,8 +144,35 @@ const PUPPETEER_TIMEOUT_ENV = {
|
|
|
93
144
|
// this can't just be a relative value in the playbook/assembler config.
|
|
94
145
|
const args = process.argv.slice(2)
|
|
95
146
|
const stdinMarkerIdx = args.lastIndexOf('-')
|
|
96
|
-
//
|
|
97
|
-
//
|
|
147
|
+
// reusable-docs-pdf-build.yml sets DOCS_PUBLISH_URL as this job's own env - the
|
|
148
|
+
// exact same value reusable-docs-build.yml's own HTML build resolves (dev
|
|
149
|
+
// sandbox vs prod) - which reaches this child process for free (plain env var
|
|
150
|
+
// inheritance), rather than needing to round-trip it through Antora's own CLI
|
|
151
|
+
// args: Antora's top-level command has no generic attribute-override flag the
|
|
152
|
+
// way plain asciidoctor does, so there's no "-a" to read it back out of here.
|
|
153
|
+
//
|
|
154
|
+
// A root-relative href (from neo4j-docs-base-uri - see
|
|
155
|
+
// absolute-links-postprocessor.js's own comment) always starts with the literal
|
|
156
|
+
// "/docs" - true site-root-relative on production, where DOCS_PUBLISH_URL's own
|
|
157
|
+
// path is just "/docs", but not on a sandbox/dev deployment, whose
|
|
158
|
+
// DOCS_PUBLISH_URL has a longer path that merely *ends* in that same "/docs"
|
|
159
|
+
// segment (e.g. ".../sandbox/restructure/docs"). Stripping that one trailing
|
|
160
|
+
// segment before prepending gives the prefix that's correct in both cases - the
|
|
161
|
+
// href's own "/docs" fills back in whichever one was removed:
|
|
162
|
+
// prod: https://neo4j.com/docs -> https://neo4j.com
|
|
163
|
+
// sandbox: https://development.neo4j.dev/docs/sandbox/restructure/docs
|
|
164
|
+
// -> https://development.neo4j.dev/docs/sandbox/restructure
|
|
165
|
+
function linkPrefix () {
|
|
166
|
+
if (!process.env.DOCS_PUBLISH_URL) return null
|
|
167
|
+
try {
|
|
168
|
+
const url = new URL(process.env.DOCS_PUBLISH_URL)
|
|
169
|
+
return url.origin + url.pathname.replace(/\/docs\/?$/, '')
|
|
170
|
+
} catch {
|
|
171
|
+
return null
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
// roles-labels-postprocessor.js and colophon-postprocessor.js port/add
|
|
175
|
+
// behavior of their own (see those files); macros-adapter.js and
|
|
98
176
|
// remote-include-adapter.js wrap the real @neo4j-documentation packages -
|
|
99
177
|
// added here, __dirname-computed, for the same reason as the stylesheet
|
|
100
178
|
// above. (table-footnotes has no equivalent here: CSS `float: footnote` -
|
|
@@ -106,7 +184,12 @@ const extraArgs = [
|
|
|
106
184
|
'--extension', ROLES_LABELS_POSTPROCESSOR,
|
|
107
185
|
'--extension', REMOTE_INCLUDE_ADAPTER,
|
|
108
186
|
'--extension', MACROS_ADAPTER,
|
|
187
|
+
'--extension', COLOPHON_POSTPROCESSOR,
|
|
188
|
+
'--extension', ABSOLUTE_LINKS_POSTPROCESSOR,
|
|
109
189
|
]
|
|
190
|
+
const prefix = linkPrefix()
|
|
191
|
+
if (prefix) extraArgs.push('-a', `absolute-link-prefix=${prefix}`)
|
|
192
|
+
if (mathjaxAvailable()) extraArgs.push('--extension', MATHJAX_ADAPTER)
|
|
110
193
|
// Reading from stdin (this is piped the merged .adoc, not a real file - see
|
|
111
194
|
// below), asciidoctor-web-pdf invents a fictive input path rooted at
|
|
112
195
|
// `--base-dir`/`-B` if given, else its own cwd (lib/cli.js's
|
|
@@ -140,5 +223,5 @@ readStdin().then((adoc) => {
|
|
|
140
223
|
process.exit(1)
|
|
141
224
|
})
|
|
142
225
|
child.on('close', (status) => process.exit(status ?? 1))
|
|
143
|
-
child.stdin.end(dedupeGlossary(adoc))
|
|
226
|
+
child.stdin.end(dedupeGlossary(adoc).trimEnd() + '\n\n' + LICENSE_PAGE)
|
|
144
227
|
})
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
// Antora's own site.url is deliberately root-relative for most docsets
|
|
4
|
+
// (neo4j-docs-base-uri: /docs, and every per-manual *-base-uri attribute
|
|
5
|
+
// built from it - javadocs, cypher-manual, operations-manual, etc.), so a
|
|
6
|
+
// cross-manual link:{neo4j-docs-base-uri}/operations-manual/...[] macro
|
|
7
|
+
// resolves to an href like "/docs/operations-manual/.../securing-extensions"
|
|
8
|
+
// - correct inside a browser loaded from https://neo4j.com, where a path
|
|
9
|
+
// starting with "/" resolves against that origin. A standalone PDF has no
|
|
10
|
+
// such origin: opened via file://, that same href resolves to a literal,
|
|
11
|
+
// nonexistent local path (file:///docs/operations-manual/...), so the link
|
|
12
|
+
// silently does nothing when clicked - confirmed directly against a real
|
|
13
|
+
// build's rendered links.
|
|
14
|
+
//
|
|
15
|
+
// The old Gradle PDF pipeline hit the exact same problem and solved it by
|
|
16
|
+
// hardcoding its own base-uri playbook attributes to always be absolute
|
|
17
|
+
// (https://neo4j.com/...), for every manual, by name. That doesn't scale
|
|
18
|
+
// here - this pipeline has no equivalent master list of every manual's own
|
|
19
|
+
// base-uri attribute, and a hardcoded list would silently miss a real
|
|
20
|
+
// Antora cross-component xref (page-to-page, not attribute-based) that
|
|
21
|
+
// resolves to a root-relative href the exact same way. Rewriting every
|
|
22
|
+
// root-relative link after rendering, regardless of what produced it,
|
|
23
|
+
// handles both cases with one general fix.
|
|
24
|
+
const { parse: parseHTML } = require('node-html-parser')
|
|
25
|
+
// Must come from the same package identity the running engine uses
|
|
26
|
+
// internally - see roles-labels-postprocessor.js's own comment on this.
|
|
27
|
+
const { Postprocessor } = require('asciidoctor')
|
|
28
|
+
|
|
29
|
+
class AbsoluteLinksPostprocessor extends Postprocessor {
|
|
30
|
+
process (document, output) {
|
|
31
|
+
if (!output.includes('href="/')) return output
|
|
32
|
+
// reusable-docs-pdf-build.yml passes DOCS_PUBLISH_URL through (the exact
|
|
33
|
+
// value its HTML build equivalent resolves - dev sandbox vs prod), and
|
|
34
|
+
// convert.js turns it into this attribute - see its own linkPrefix()
|
|
35
|
+
// comment for why this is more than just an origin. Falls back to the
|
|
36
|
+
// real production origin if that ever isn't available, rather than
|
|
37
|
+
// leaving a root-relative, unusable link in a downloaded, standalone PDF.
|
|
38
|
+
const prefix = document.getAttribute('absolute-link-prefix') || 'https://neo4j.com'
|
|
39
|
+
const root = parseHTML(output)
|
|
40
|
+
root.querySelectorAll('a[href]').forEach((a) => {
|
|
41
|
+
const href = a.getAttribute('href')
|
|
42
|
+
// Root-relative only ("/foo") - leave protocol-relative ("//foo",
|
|
43
|
+
// a different origin entirely) and everything else (full URLs,
|
|
44
|
+
// same-page "#fragment"s, "mailto:", ...) untouched.
|
|
45
|
+
if (href.startsWith('/') && !href.startsWith('//')) {
|
|
46
|
+
a.setAttribute('href', prefix + href)
|
|
47
|
+
}
|
|
48
|
+
})
|
|
49
|
+
return root.toString()
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
module.exports.register = function (registry) {
|
|
54
|
+
registry.postprocessor(AbsoluteLinksPostprocessor)
|
|
55
|
+
}
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
// Inserts a one-time copyright/trademark colophon page, right after the
|
|
4
|
+
// cover/title page and before the table of contents, as an alternative to
|
|
5
|
+
// running @neo4j-antora/mark-terms in this pipeline (see this package's own
|
|
6
|
+
// README, "Known limitations" - mark-terms marks a term's *first use per
|
|
7
|
+
// page*, a notion this pipeline's single merged document has no equivalent
|
|
8
|
+
// of). One boilerplate statement covering the whole PDF sidesteps that
|
|
9
|
+
// entirely. Distinct from the closing License page convert.js always
|
|
10
|
+
// appends (the CC BY-NC-SA 4.0 licensing terms) - this is Neo4j's own
|
|
11
|
+
// trademark notice, placed at the front of the book instead.
|
|
12
|
+
//
|
|
13
|
+
// This has to insert into already-rendered HTML rather than as real
|
|
14
|
+
// AsciiDoc content (e.g. a discrete heading placed in the document
|
|
15
|
+
// preamble with `toc-placement: preamble` to push the auto-generated TOC
|
|
16
|
+
// below it) - that would only work if the merged document's own preamble
|
|
17
|
+
// were otherwise empty, but a docset's own first page very often has real
|
|
18
|
+
// intro text before its own first heading, which would then also count as
|
|
19
|
+
// "preamble" and get pulled in front of the TOC alongside this notice.
|
|
20
|
+
// Inserting directly before whatever HTML element the TOC actually
|
|
21
|
+
// produced sidesteps that risk entirely - it doesn't depend on any
|
|
22
|
+
// document content structure, just the cover/TOC/content divs the PDF
|
|
23
|
+
// converter itself always emits in that fixed order.
|
|
24
|
+
//
|
|
25
|
+
// The year is the docset's own `copyright` attribute (already maintained
|
|
26
|
+
// by every docs-* repo's playbook for this purpose - see its own comment
|
|
27
|
+
// in preview.yml/publish.yml: "update the copyright value with the first
|
|
28
|
+
// commit in a new year"), not a fresh computation to keep in sync with it.
|
|
29
|
+
const { parse: parseHTML } = require('node-html-parser')
|
|
30
|
+
// Must come from the same package identity the running engine (loaded via
|
|
31
|
+
// `asciidoctor`, not `@asciidoctor/core` directly) uses internally - see
|
|
32
|
+
// roles-labels-postprocessor.js's own comment on this.
|
|
33
|
+
const { Postprocessor } = require('asciidoctor')
|
|
34
|
+
|
|
35
|
+
const TRADEMARK_NOTICE =
|
|
36
|
+
'Neo Technology®, Neo4j®, Cypher®, Neo4j Bloom™, Neo4j Graph Data Science Library™, Neo4j® Aura™, and ' +
|
|
37
|
+
'Neo4j® AuraDB™ are registered trademarks or trademarks of Neo4j, Inc. in the United States ' +
|
|
38
|
+
'and other countries.'
|
|
39
|
+
const OTHER_MARKS_NOTICE =
|
|
40
|
+
'All other trademarks, service marks, registered trademarks, or registered service marks mentioned ' +
|
|
41
|
+
'in this document are the property of their respective owners.'
|
|
42
|
+
|
|
43
|
+
class ColophonPostprocessor extends Postprocessor {
|
|
44
|
+
process (document, output) {
|
|
45
|
+
if (!output.includes('id="content"')) return output
|
|
46
|
+
const root = parseHTML(output)
|
|
47
|
+
// Insert before the TOC if there is one (the normal case - every
|
|
48
|
+
// docset's PDF build enables it), else fall back to right before the
|
|
49
|
+
// main content div.
|
|
50
|
+
const anchor = root.getElementById('toc') || root.getElementById('content')
|
|
51
|
+
if (!anchor) return output
|
|
52
|
+
const year = document.getAttribute('copyright') || new Date().getFullYear().toString()
|
|
53
|
+
const colophon = parseHTML(
|
|
54
|
+
`<div id="colophon">
|
|
55
|
+
<h1>Copyright & Trademarks</h1>
|
|
56
|
+
<p>© ${year} Neo4j, Inc. All rights reserved.</p>
|
|
57
|
+
<p>${TRADEMARK_NOTICE}</p>
|
|
58
|
+
<p>${OTHER_MARKS_NOTICE}</p>
|
|
59
|
+
</div>`
|
|
60
|
+
).firstChild
|
|
61
|
+
anchor.before(colophon)
|
|
62
|
+
return root.toString()
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
module.exports.register = function (registry) {
|
|
67
|
+
registry.postprocessor(ColophonPostprocessor)
|
|
68
|
+
}
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
// @djencks/asciidoctor-mathjax's tree processor was written against the
|
|
4
|
+
// pre-4.x Asciidoctor.js Opal-bridge API - removed in the 4.x engine this
|
|
5
|
+
// vendored asciidoctor-web-pdf requires (see macros-adapter.js/
|
|
6
|
+
// remote-include-adapter.js for the same class of bug in other packages):
|
|
7
|
+
// - `doc.$playback_attributes(...)` / `doc.$restore_attributes()` -> now
|
|
8
|
+
// plain `doc.playbackAttributes(...)` / `doc.restoreAttributes()`
|
|
9
|
+
// (Document instance methods, no `$`-prefixed alias kept in 4.x).
|
|
10
|
+
// - `processor.$create_pass_block(...)` -> now `processor.createPassBlock(...)`.
|
|
11
|
+
// - `stem.attributes.$$smap.role` - `$$smap` was Ruby Hash's internal
|
|
12
|
+
// string-keyed map, exposed by Opal; 4.x attributes are a plain object,
|
|
13
|
+
// so this is just `stem.attributes.role`.
|
|
14
|
+
// - `Opal.hash({})` - passed as an empty attrs argument; no `Opal` global
|
|
15
|
+
// exists in this engine at all (it isn't Opal-compiled), so this throws
|
|
16
|
+
// a bare ReferenceError. An empty plain object is the exact equivalent.
|
|
17
|
+
// - `cell.$inner_document()` - `innerDocument` is a plain getter property
|
|
18
|
+
// in 4.x, not a method.
|
|
19
|
+
//
|
|
20
|
+
// These are direct property/method accesses buried inside the package's own
|
|
21
|
+
// module-level functions (not calls made through a `this`/callback we
|
|
22
|
+
// control), so a `registry.*` proxy shim like the other adapters use can't
|
|
23
|
+
// reach them. Instead this loads the real file's source and rewrites just
|
|
24
|
+
// those call sites in memory before evaluating it - not patch-package,
|
|
25
|
+
// since its postinstall hook isn't guaranteed to run once this package is a
|
|
26
|
+
// nested dependency of a docset's own install (see this package's own
|
|
27
|
+
// README). Verified directly against the unpatched package and the
|
|
28
|
+
// installed Asciidoctor.js engine.
|
|
29
|
+
const fs = require('node:fs')
|
|
30
|
+
const path = require('node:path')
|
|
31
|
+
const Module = require('node:module')
|
|
32
|
+
|
|
33
|
+
const REPLACEMENTS = [
|
|
34
|
+
[/\.\$playback_attributes\(/g, '.playbackAttributes('],
|
|
35
|
+
[/\.\$restore_attributes\(/g, '.restoreAttributes('],
|
|
36
|
+
[/\.\$create_pass_block\(/g, '.createPassBlock('],
|
|
37
|
+
[/stem\.attributes\.\$\$smap\.role/g, 'stem.attributes.role'],
|
|
38
|
+
[/Opal\.hash\(\{\}\)/g, '{}'],
|
|
39
|
+
[/\.\$inner_document\(\)/g, '.innerDocument'],
|
|
40
|
+
]
|
|
41
|
+
|
|
42
|
+
function resolveSource (id) {
|
|
43
|
+
// See convert.js's own resolveMathjaxSource comment: this file's real
|
|
44
|
+
// (symlink-dereferenced) location isn't the docset's own node_modules
|
|
45
|
+
// under `npm link`, so fall back to a resolve rooted at the working
|
|
46
|
+
// directory (antora's cwd is always the docset being built).
|
|
47
|
+
try {
|
|
48
|
+
return require.resolve(id)
|
|
49
|
+
} catch {
|
|
50
|
+
return require.resolve(id, { paths: [process.cwd()] })
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
function loadPatched (id) {
|
|
55
|
+
const target = resolveSource(id)
|
|
56
|
+
let src = fs.readFileSync(target, 'utf8')
|
|
57
|
+
for (const [pattern, replacement] of REPLACEMENTS) src = src.replace(pattern, replacement)
|
|
58
|
+
const patched = new Module(target, module)
|
|
59
|
+
patched.filename = target
|
|
60
|
+
patched.paths = Module._nodeModulePaths(path.dirname(target))
|
|
61
|
+
patched._compile(src, target)
|
|
62
|
+
return patched.exports
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
const mathjax = loadPatched('@djencks/asciidoctor-mathjax')
|
|
66
|
+
|
|
67
|
+
module.exports.register = function (registry, context) {
|
|
68
|
+
mathjax.register(registry, context)
|
|
69
|
+
}
|