@neo4j-antora/pdf-generator 0.1.0-rc.2 → 0.1.1
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 +60 -33
- package/package.json +10 -2
- package/pdf-theme/print.css +22 -0
- package/scripts/convert.js +8 -7
- package/vendor/extensions/table-footnotes-postprocessor.js +0 -74
package/README.adoc
CHANGED
|
@@ -6,28 +6,52 @@ renderer) instead of the legacy Gradle + AsciidoctorJ mono-merge pipeline.
|
|
|
6
6
|
See `reusable-pdf-build.yml` in `.github/workflows/` for the CI entry point
|
|
7
7
|
that uses this package.
|
|
8
8
|
|
|
9
|
-
Published as a normal npm
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
9
|
+
Published as a normal npm package, but deliberately *not* one a docset
|
|
10
|
+
declares in its own `package.json`: it's only ever needed for a PDF-specific
|
|
11
|
+
build, and a docset's `package.json` is shared by every job that runs
|
|
12
|
+
`npm install` against it (including totally unrelated jobs, e.g. a plain
|
|
13
|
+
HTML PR check), so declaring it there would make all of those fail whenever
|
|
14
|
+
a given version isn't published yet. `reusable-docs-pdf-build.yml` installs
|
|
15
|
+
it itself, as its own explicit `npm install @neo4j-antora/pdf-generator@...`
|
|
16
|
+
step, the same way it installs a specific Antora version regardless of what
|
|
17
|
+
the docset's own `package.json` pins. There's nothing to check out, symlink,
|
|
18
|
+
or hand-configure beyond that: `@antora/pdf-extension` is this package's own
|
|
19
|
+
dependency (not something a docset lists itself), so installing this one
|
|
20
|
+
package is the entire setup.
|
|
15
21
|
|
|
16
22
|
== Usage
|
|
17
23
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
24
|
+
This package self-registers as a real Antora extension (it wraps
|
|
25
|
+
`@antora/pdf-extension`, pre-wired with its own assembler config as the
|
|
26
|
+
default - see `extension.js`), so it needs no dedicated playbook or
|
|
27
|
+
`package.json` script of its own. Pass it as a one-off `--extension` flag
|
|
28
|
+
onto whatever playbook/script a docset already uses for a normal build:
|
|
29
|
+
|
|
30
|
+
[source,shell]
|
|
31
|
+
----
|
|
32
|
+
antora publish.yml --extension @neo4j-antora/pdf-generator
|
|
33
|
+
# or, reusing an existing package.json script:
|
|
34
|
+
npm run verify:publish -- --extension @neo4j-antora/pdf-generator
|
|
35
|
+
----
|
|
36
|
+
|
|
37
|
+
Generating a PDF this way always regenerates the full HTML site alongside
|
|
38
|
+
it in the same Antora run (`@antora/assembler`/`@antora/pdf-extension` hook
|
|
39
|
+
into normal site generation rather than replacing it) - there's no way to
|
|
40
|
+
get "just the PDF" from a single run.
|
|
41
|
+
|
|
42
|
+
A docset can still register it declaratively in a playbook instead, if
|
|
43
|
+
preferred:
|
|
21
44
|
|
|
22
45
|
[source,yaml]
|
|
23
46
|
----
|
|
24
47
|
antora:
|
|
25
48
|
extensions:
|
|
26
|
-
- require: '@antora/pdf-
|
|
27
|
-
config_file: './node_modules/@neo4j-antora/pdf-generator/antora-assembler-pdf.yml'
|
|
49
|
+
- require: '@neo4j-antora/pdf-generator'
|
|
28
50
|
----
|
|
29
51
|
|
|
30
|
-
|
|
52
|
+
Either form picks up this package's own `antora-assembler-pdf.yml` as the
|
|
53
|
+
default `configFile` - pass a `config:` block in the playbook form to
|
|
54
|
+
override individual assembler settings if needed.
|
|
31
55
|
|
|
32
56
|
== Layout
|
|
33
57
|
|
|
@@ -53,9 +77,8 @@ and a `package.json` script to run it, e.g. `"pdf": "antora pdf.yml"`.
|
|
|
53
77
|
`pdf-theme/assets/fonts/` rather than read from a docset's own HTML
|
|
54
78
|
build output, so this theme has no dependency on that build having
|
|
55
79
|
already run.
|
|
56
|
-
- `extensions/` - `roles-labels-postprocessor.js`
|
|
57
|
-
|
|
58
|
-
extensions of the same name (see "Known limitations" below);
|
|
80
|
+
- `extensions/` - `roles-labels-postprocessor.js` ports the essential parts
|
|
81
|
+
of the Antora extension of the same name (see "Known limitations" below);
|
|
59
82
|
`macros-adapter.js` and `remote-include-adapter.js` wrap the real
|
|
60
83
|
`@neo4j-documentation/macros`/`remote-include` packages, fixing a
|
|
61
84
|
pre-4.x-Asciidoctor.js API incompatibility in each at runtime (see their
|
|
@@ -72,28 +95,32 @@ and a `package.json` script to run it, e.g. `"pdf": "antora pdf.yml"`.
|
|
|
72
95
|
|
|
73
96
|
== Known limitations
|
|
74
97
|
|
|
75
|
-
- **
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
98
|
+
- **Fixed**: footnotes used to render inline, in the middle of the running
|
|
99
|
+
text, with no number and no separation from the surrounding sentence -
|
|
100
|
+
easy to mistake for the macro being dropped entirely, since the text is
|
|
101
|
+
still technically there. Root cause: `asciidoctor-web-pdf`'s own converter
|
|
102
|
+
emits a footnote as a single self-contained `<span class="footnote">text
|
|
103
|
+
</span>` right at the point of use, and relies entirely on its default
|
|
104
|
+
theme's `span.footnote { float: footnote }` (a native CSS Generated
|
|
105
|
+
Content for Paged Media rule - the browser/Vivliostyle itself lays the
|
|
106
|
+
floated span into the footnote area of whichever page it lands on, and
|
|
107
|
+
generates the marker/counter) to pull it out and number it. Overriding
|
|
108
|
+
`stylesheet` wholesale (see `print.css` above) replaces that default theme
|
|
109
|
+
entirely rather than layering on top of it, so this pipeline had silently
|
|
110
|
+
dropped that rule. `print.css` now carries its own copy of it. Because the
|
|
111
|
+
float is resolved per-page by the layout engine itself, this also means a
|
|
112
|
+
footnote always lands on the same page as whatever referenced it - table
|
|
113
|
+
or not - with no extra plumbing needed.
|
|
88
114
|
- `@neo4j-antora/roles-labels` and `@neo4j-antora/table-footnotes` are Antora
|
|
89
115
|
extensions (hook `pagesComposed`, operate on an Antora `ContentCatalog`) -
|
|
90
116
|
neither can run against this pipeline at all, structurally: the assembler
|
|
91
117
|
hands the merged `.adoc` to a completely separate, isolated Asciidoctor
|
|
92
|
-
conversion with no Antora generator context. `table-footnotes`
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
`roles-labels-postprocessor.js`
|
|
118
|
+
conversion with no Antora generator context. `table-footnotes` has no
|
|
119
|
+
ported equivalent here (nor is it in `reusable-docs-pdf-build.yml`'s
|
|
120
|
+
`antora-extensions` default list) - per the footnote fix above, the native
|
|
121
|
+
CSS float already puts a table's footnotes on the right page on its own,
|
|
122
|
+
so there's nothing left for it to do. `roles-labels-postprocessor.js`
|
|
123
|
+
reuses `@neo4j-antora/roles-labels`'s own
|
|
97
124
|
shared `lib/process-labels.js` core directly (same synonym resolution,
|
|
98
125
|
version/product-suffix stripping, dataset attributes as the real HTML
|
|
99
126
|
site - not a hand-ported subset), with one deliberate behavioural
|
package/package.json
CHANGED
|
@@ -1,8 +1,16 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@neo4j-antora/pdf-generator",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
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
|
+
"files": [
|
|
7
|
+
"extension.js",
|
|
8
|
+
"antora-assembler-pdf.yml",
|
|
9
|
+
"pdf-theme",
|
|
10
|
+
"scripts",
|
|
11
|
+
"vendor/extensions",
|
|
12
|
+
"README.adoc"
|
|
13
|
+
],
|
|
6
14
|
"scripts": {
|
|
7
15
|
"test": "echo \"Error: no test specified\" && exit 1",
|
|
8
16
|
"postinstall": "node scripts/setup-vendor.js"
|
|
@@ -15,7 +23,7 @@
|
|
|
15
23
|
"license": "MIT",
|
|
16
24
|
"dependencies": {
|
|
17
25
|
"@antora/pdf-extension": "1.0.0",
|
|
18
|
-
"@neo4j-antora/roles-labels": "0.1.14
|
|
26
|
+
"@neo4j-antora/roles-labels": "0.1.14",
|
|
19
27
|
"@neo4j-documentation/macros": "1.0.4",
|
|
20
28
|
"@neo4j-documentation/remote-include": "1.0.0",
|
|
21
29
|
"node-html-parser": "9.0.4"
|
package/pdf-theme/print.css
CHANGED
|
@@ -270,6 +270,28 @@ tr { break-inside: avoid; }
|
|
|
270
270
|
/* lists */
|
|
271
271
|
.ulist, .olist, .dlist { margin: 0.5em 0; }
|
|
272
272
|
|
|
273
|
+
/* footnotes (copied from asciidoctor-web-pdf's own default document.css -
|
|
274
|
+
overriding `stylesheet` wholesale, as this theme does, drops the default
|
|
275
|
+
theme's CSS entirely, not just the rules this theme redefines. Without
|
|
276
|
+
these, a footnote's `span.footnote` renders in normal document flow
|
|
277
|
+
instead of being pulled out via the CSS `float: footnote`/`::footnote`
|
|
278
|
+
paged-media mechanism Vivliostyle implements, so the note text shows up
|
|
279
|
+
inline, right where footnote:[...] was written, with no superscript
|
|
280
|
+
marker and no separation from the surrounding sentence - easy to mistake
|
|
281
|
+
for footnotes being silently dropped, since nothing errors and the text
|
|
282
|
+
is still technically present.) */
|
|
283
|
+
span.footnote {
|
|
284
|
+
float: footnote;
|
|
285
|
+
}
|
|
286
|
+
|
|
287
|
+
[data-footnote-call]::after {
|
|
288
|
+
content: "[" counter(footnote) "]";
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
a[data-footnote-call] {
|
|
292
|
+
cursor: pointer;
|
|
293
|
+
}
|
|
294
|
+
|
|
273
295
|
/* role labels (badges added by @neo4j-antora/roles-labels for label:x[] macros
|
|
274
296
|
and :page-role:/[role=label--x] roles).
|
|
275
297
|
|
package/scripts/convert.js
CHANGED
|
@@ -27,7 +27,6 @@ const path = require('node:path')
|
|
|
27
27
|
const RENDERER = path.join(__dirname, '../vendor/node_modules/asciidoctor-pdf/bin/asciidoctor-web-pdf')
|
|
28
28
|
const STYLESHEET = path.join(__dirname, '../pdf-theme/print.css')
|
|
29
29
|
const ROLES_LABELS_POSTPROCESSOR = path.join(__dirname, '../vendor/extensions/roles-labels-postprocessor.js')
|
|
30
|
-
const TABLE_FOOTNOTES_POSTPROCESSOR = path.join(__dirname, '../vendor/extensions/table-footnotes-postprocessor.js')
|
|
31
30
|
const REMOTE_INCLUDE_ADAPTER = path.join(__dirname, '../vendor/extensions/remote-include-adapter.js')
|
|
32
31
|
const MACROS_ADAPTER = path.join(__dirname, '../vendor/extensions/macros-adapter.js')
|
|
33
32
|
|
|
@@ -94,15 +93,17 @@ const PUPPETEER_TIMEOUT_ENV = {
|
|
|
94
93
|
// this can't just be a relative value in the playbook/assembler config.
|
|
95
94
|
const args = process.argv.slice(2)
|
|
96
95
|
const stdinMarkerIdx = args.lastIndexOf('-')
|
|
97
|
-
// roles-labels-postprocessor.js
|
|
98
|
-
//
|
|
99
|
-
//
|
|
100
|
-
//
|
|
101
|
-
//
|
|
96
|
+
// roles-labels-postprocessor.js ports the essential parts of the Antora
|
|
97
|
+
// extension of the same name (see that file); macros-adapter.js and
|
|
98
|
+
// remote-include-adapter.js wrap the real @neo4j-documentation packages -
|
|
99
|
+
// added here, __dirname-computed, for the same reason as the stylesheet
|
|
100
|
+
// above. (table-footnotes has no equivalent here: CSS `float: footnote` -
|
|
101
|
+
// see the print theme's own comment - already places a footnote on whatever
|
|
102
|
+
// page its table lands on, natively, so there's nothing for a postprocessor
|
|
103
|
+
// to move.)
|
|
102
104
|
const extraArgs = [
|
|
103
105
|
'-a', `stylesheet=${STYLESHEET}`,
|
|
104
106
|
'--extension', ROLES_LABELS_POSTPROCESSOR,
|
|
105
|
-
'--extension', TABLE_FOOTNOTES_POSTPROCESSOR,
|
|
106
107
|
'--extension', REMOTE_INCLUDE_ADAPTER,
|
|
107
108
|
'--extension', MACROS_ADAPTER,
|
|
108
109
|
]
|
|
@@ -1,74 +0,0 @@
|
|
|
1
|
-
'use strict'
|
|
2
|
-
|
|
3
|
-
// Ports @neo4j-antora/table-footnotes for the PDF pipeline: moving a table's
|
|
4
|
-
// own footnotes out of Asciidoctor's single document-wide #footnotes div and
|
|
5
|
-
// into a <tfoot> row on that specific table, instead of leaving them
|
|
6
|
-
// dumped at the very end of the whole document, disconnected from the table
|
|
7
|
-
// they came from.
|
|
8
|
-
//
|
|
9
|
-
// Same reason this can't just reuse table-footnotes.js directly as roles-
|
|
10
|
-
// labels-postprocessor.js: it hooks Antora's own `pagesComposed` event and
|
|
11
|
-
// operates on files in an Antora ContentCatalog, neither of which exist in
|
|
12
|
-
// this pipeline (see docs-tools/pdf/README) - asciidoctor-web-pdf runs a
|
|
13
|
-
// separate, isolated Asciidoctor conversion on the assembler's merged .adoc
|
|
14
|
-
// text that table-footnotes never gets a chance to see. This is a
|
|
15
|
-
// Postprocessor instead (Asciidoctor's own extension point, run after
|
|
16
|
-
// conversion to HTML), with the same DOM manipulation ported over near
|
|
17
|
-
// verbatim - it's pure HTML restructuring, no Antora-specific data needed.
|
|
18
|
-
|
|
19
|
-
const { parse: parseHTML } = require('node-html-parser')
|
|
20
|
-
// Must come from the same package identity the running engine uses
|
|
21
|
-
// internally, not a separately-resolved copy - see roles-labels-
|
|
22
|
-
// postprocessor.js for why requiring the class from the wrong copy of the
|
|
23
|
-
// module fails Registry's own type check.
|
|
24
|
-
const { Postprocessor } = require('asciidoctor')
|
|
25
|
-
|
|
26
|
-
function createElement (el, className = '') {
|
|
27
|
-
return parseHTML(`<${el}${className ? ` class="${className}"` : ''}></${el}>`)
|
|
28
|
-
}
|
|
29
|
-
|
|
30
|
-
class TableFootnotesPostprocessor extends Postprocessor {
|
|
31
|
-
process (_document, output) {
|
|
32
|
-
if (!output.includes('id="footnotes"')) return output
|
|
33
|
-
const root = parseHTML(output)
|
|
34
|
-
const footnotesDiv = root.getElementById('footnotes')
|
|
35
|
-
const tables = root.querySelectorAll('table')
|
|
36
|
-
if (!footnotesDiv || tables.length === 0) return output
|
|
37
|
-
|
|
38
|
-
tables.forEach((table) => {
|
|
39
|
-
const tableFootnotes = table.querySelectorAll('tbody a.footnote')
|
|
40
|
-
if (tableFootnotes.length === 0) return
|
|
41
|
-
|
|
42
|
-
const cols = table.querySelectorAll('colgroup col').length
|
|
43
|
-
const tFoot = createElement('tfoot')
|
|
44
|
-
const footnoteRow = createElement('tr')
|
|
45
|
-
tFoot.firstElementChild.appendChild(footnoteRow)
|
|
46
|
-
const footnoteCell = createElement('td', 'tableblock footnote-cell')
|
|
47
|
-
footnoteCell.firstElementChild.setAttribute('colspan', cols)
|
|
48
|
-
|
|
49
|
-
// For each footnote reference in this table, find the matching
|
|
50
|
-
// footnote definition (by id, from its href) in the document-wide
|
|
51
|
-
// footnotes div, and move it into this table's own footer.
|
|
52
|
-
tableFootnotes.forEach((footnote) => {
|
|
53
|
-
const footnoteId = footnote.getAttribute('href').replace('#', '')
|
|
54
|
-
const matchingFootnote = footnotesDiv.querySelector(`#${footnoteId}`)
|
|
55
|
-
if (!matchingFootnote) return
|
|
56
|
-
footnoteCell.firstElementChild.appendChild(matchingFootnote)
|
|
57
|
-
})
|
|
58
|
-
|
|
59
|
-
footnoteRow.firstElementChild.appendChild(footnoteCell)
|
|
60
|
-
table.appendChild(tFoot)
|
|
61
|
-
})
|
|
62
|
-
|
|
63
|
-
// Remove the document-wide footnotes div if every footnote in it ended
|
|
64
|
-
// up moved into a table footer.
|
|
65
|
-
if (footnotesDiv.querySelectorAll('div.footnote').length === 0) {
|
|
66
|
-
footnotesDiv.remove()
|
|
67
|
-
}
|
|
68
|
-
return root.toString()
|
|
69
|
-
}
|
|
70
|
-
}
|
|
71
|
-
|
|
72
|
-
module.exports.register = function (registry) {
|
|
73
|
-
registry.postprocessor(TableFootnotesPostprocessor)
|
|
74
|
-
}
|