@neo4j-antora/pdf-generator 0.1.11 → 0.1.13

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
@@ -103,6 +103,12 @@ during) for the fix and the full explanation.
103
103
  already run.
104
104
  - `extensions/` - `roles-labels-postprocessor.js` ports the essential parts
105
105
  of the Antora extension of the same name (see "Known limitations" below);
106
+ `page-role-preprocessor.js` carries a page's `:page-role:` across to the
107
+ PDF as the label under that page's title (on the real site the page layout
108
+ puts the role on the page's `<h1>`, which this pipeline never goes through,
109
+ and the assembler leaves the role as an attribute entry before the page
110
+ title that never reaches the converted HTML - so it is copied onto the
111
+ title as a role first, for the postprocessor above to turn into a label);
106
112
  `tabbed-example-postprocessor.js` labels each alternative of a
107
113
  `[.tabbed-example]`/`[.include-with-X]` group with its own real-site tab
108
114
  text (ported directly from the real site's own client-side JS, which
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@neo4j-antora/pdf-generator",
3
- "version": "0.1.11",
3
+ "version": "0.1.13",
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": [
@@ -25,7 +25,7 @@
25
25
  "license": "MIT",
26
26
  "dependencies": {
27
27
  "@antora/pdf-extension": "1.0.0",
28
- "@neo4j-antora/roles-labels": "0.1.14",
28
+ "@neo4j-antora/roles-labels": "0.1.15",
29
29
  "@neo4j-documentation/macros": "1.0.4",
30
30
  "@neo4j-documentation/remote-include": "1.0.0",
31
31
  "node-html-parser": "9.0.4"
@@ -28,6 +28,7 @@ const os = require('node:os')
28
28
  // those have no such conflict and should stay deduped normally.
29
29
  const RENDERER = path.join(__dirname, '../vendor/node_modules/asciidoctor-pdf/bin/asciidoctor-web-pdf')
30
30
  const PRINT_CSS = path.join(__dirname, '../pdf-theme/print.css')
31
+ const PAGE_ROLE_PREPROCESSOR = path.join(__dirname, '../vendor/extensions/page-role-preprocessor.js')
31
32
  const ROLES_LABELS_POSTPROCESSOR = path.join(__dirname, '../vendor/extensions/roles-labels-postprocessor.js')
32
33
  const REMOTE_INCLUDE_ADAPTER = path.join(__dirname, '../vendor/extensions/remote-include-adapter.js')
33
34
  const MACROS_ADAPTER = path.join(__dirname, '../vendor/extensions/macros-adapter.js')
@@ -287,6 +288,7 @@ Promise.all([buildStylesheet(), readStdin()]).then(([stylesheet, adoc]) => {
287
288
  // loads every `--extension` up front, before conversion starts, so position in this
288
289
  // list doesn't matter beyond that) - see cypher-language-adapter.js's own comment.
289
290
  '--extension', CYPHER_LANGUAGE_ADAPTER,
291
+ '--extension', PAGE_ROLE_PREPROCESSOR,
290
292
  '--extension', ROLES_LABELS_POSTPROCESSOR,
291
293
  '--extension', REMOTE_INCLUDE_ADAPTER,
292
294
  '--extension', MACROS_ADAPTER,
@@ -0,0 +1,83 @@
1
+ 'use strict'
2
+
3
+ // Carries a page's `:page-role:` (e.g. `:page-role: not-on-mvcc` in the document header)
4
+ // across to the PDF, where it becomes the label next to the page title, as on the real site.
5
+ //
6
+ // On the real site the page layout puts the page role on the page's <h1>, and
7
+ // @neo4j-antora/roles-labels turns an <h1> role into the label beside the title. The PDF
8
+ // pipeline never goes through that layout: @antora/assembler merges every page into one
9
+ // document, and plain Asciidoctor converts it. In that merged source a page's attributes
10
+ // are written as attribute entries in the block just before its title, with the page's own
11
+ // `:page-role:` first and `:page-url:` last, then the title preceded by an anchor line:
12
+ //
13
+ // :page-role: not-on-mvcc
14
+ // :page-docname: mvcc
15
+ // ...
16
+ // :page-url: /docs-tools/dev/mvcc/
17
+ // [#mvcc]
18
+ // == MVCC Label
19
+ //
20
+ // and the role is cleared again with `:!page-role:` after the page. An attribute entry never
21
+ // reaches the converted HTML, so nothing downstream can see it. This preprocessor reads the
22
+ // merged lines, finds the anchor line that follows `:page-url:` while a `:page-role:` is
23
+ // set, and adds the label roles to it (`[#mvcc]` becomes `[#mvcc.label--not-on-mvcc]`). The
24
+ // roles-labels postprocessor then turns that role on the title into the label, exactly as it
25
+ // does for a role written on a heading by hand.
26
+ //
27
+ // A page-role value that is not a label (for example a styling role) is left alone: only
28
+ // names roles-labels knows are added, resolved the same way processLabels resolves them
29
+ // (`label--x` as is, a label name as `label--<name>`, a synonym as is).
30
+ //
31
+ // Rewrites `reader._lines`, the reader's own storage of the remaining lines. It is stored
32
+ // reversed (next line last), and the public `lines` getter only returns a copy, so the lines
33
+ // cannot be changed through the public API, which also has no synchronous way to replace
34
+ // them (readLines() is async and a preprocessor must return the reader synchronously).
35
+ // Verified against Asciidoctor.js 4.1.
36
+
37
+ const { Preprocessor } = require('asciidoctor')
38
+ const rolesData = require('@neo4j-antora/roles-labels/data/roles.json')
39
+
40
+ const PAGE_ROLE = /^:page-role:\s*(.*?)\s*$/
41
+ const PAGE_ROLE_UNSET = /^:(?:!page-role|page-role!):\s*$/
42
+ const PAGE_URL = /^:page-url:/
43
+ const ANCHOR = /^\[#([^\].,\s]+)\]$/
44
+
45
+ // The role processLabels will turn into a label, or undefined if this value is not a label.
46
+ function labelRole (value) {
47
+ if (value.startsWith('label--')) return value
48
+ if (rolesData.labels[value]) return `label--${value}`
49
+ if (rolesData.synonyms[value]) return value
50
+ }
51
+
52
+ function addPageRoles (lines) {
53
+ let roles = []
54
+ for (let i = 0; i < lines.length; i++) {
55
+ const line = lines[i]
56
+ const set = PAGE_ROLE.exec(line)
57
+ if (set) {
58
+ roles = set[1].split(/\s+/).map(labelRole).filter(Boolean)
59
+ } else if (PAGE_ROLE_UNSET.test(line)) {
60
+ roles = []
61
+ } else if (roles.length && PAGE_URL.test(line)) {
62
+ const anchor = ANCHOR.exec(lines[i + 1] || '')
63
+ if (anchor) lines[i + 1] = `[#${anchor[1]}${roles.map((role) => `.${role}`).join('')}]`
64
+ }
65
+ }
66
+ return lines
67
+ }
68
+
69
+ class PageRolePreprocessor extends Preprocessor {
70
+ process (document, reader) {
71
+ const lines = reader.getLines()
72
+ if (!lines.some((line) => PAGE_ROLE.test(line))) return reader
73
+ const rewritten = addPageRoles(lines.slice())
74
+ reader._lines.splice(0, reader._lines.length, ...rewritten.slice().reverse())
75
+ return reader
76
+ }
77
+ }
78
+
79
+ module.exports.addPageRoles = addPageRoles
80
+
81
+ module.exports.register = function (registry) {
82
+ registry.preprocessor(PageRolePreprocessor)
83
+ }