@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 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 dependency - a docset adds it as a devDependency
10
- and gets a real, versioned copy in its own `node_modules`, the same way it
11
- already depends on `@neo4j-antora/roles-labels` or `@neo4j-antora/tabbed-nav`.
12
- There's nothing to check out, symlink, or hand-configure: `@antora/pdf-
13
- extension` is this package's own dependency (not something a docset lists
14
- itself), so `npm install @neo4j-antora/pdf-generator` is the entire setup.
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
- A docset needs its own small playbook (like `preview.yml`/`publish.yml`,
19
- since content sources/attributes differ per docset - not shared here) that
20
- registers `@antora/pdf-extension` with this package's assembler config:
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-extension'
27
- config_file: './node_modules/@neo4j-antora/pdf-generator/antora-assembler-pdf.yml'
49
+ - require: '@neo4j-antora/pdf-generator'
28
50
  ----
29
51
 
30
- and a `package.json` script to run it, e.g. `"pdf": "antora pdf.yml"`.
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` and
57
- `table-footnotes-postprocessor.js` port the essential parts of the Antora
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
- - **No footnotes render at all, anywhere in the PDF, because of the TOC.**
76
- Isolated by direct testing against `asciidoctor-web-pdf` outside this whole
77
- pipeline: passing `-a toc` alone (nothing else - no tables, no our own
78
- extensions) is enough to break native Asciidoctor `footnote:[...]`
79
- conversion entirely - no superscript reference, no `#footnotes` div, just
80
- the footnote text dropped in-line as if the macro had never been
81
- processed. Since the print theme enables `toc` for every docset, this
82
- currently affects every PDF this pipeline produces, not just docsets using
83
- footnotes inside tables. `extensions/table-footnotes-postprocessor.js`
84
- (see above) is correctly written and wired in, but has nothing to do while
85
- this is broken - there's no `#footnotes` div for it to move content out of.
86
- Not yet root-caused further (asciidoctor-web-pdf itself, or its Vivliostyle
87
- dependency) or fixed.
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` is ported
93
- as a plain Asciidoctor `Postprocessor` instead
94
- (`extensions/table-footnotes-postprocessor.js`) - pure HTML restructuring,
95
- no Antora-specific data needed, so the port is a straight copy.
96
- `roles-labels-postprocessor.js` reuses `@neo4j-antora/roles-labels`'s own
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.0-rc.2",
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-rc.1",
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"
@@ -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
 
@@ -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 and table-footnotes-postprocessor.js port the
98
- // essential parts of the Antora extensions of the same name (see those
99
- // files); macros-adapter.js and remote-include-adapter.js wrap the real
100
- // @neo4j-documentation packages - added here, __dirname-computed, for the
101
- // same reason as the stylesheet above.
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
- }