@neo4j-antora/pdf-generator 0.1.12 → 0.1.14

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
@@ -34,6 +34,10 @@ antora publish.yml --extension @neo4j-antora/pdf-generator
34
34
  npm run verify:publish -- --extension @neo4j-antora/pdf-generator
35
35
  ----
36
36
 
37
+ A PDF contains a single version: the one being built. When the playbook is built, every local content
38
+ source (the repository being built) is limited to `branches: [HEAD]`, so the other versions the
39
+ playbook lists are not collected or rendered. Remote content sources are left as they are.
40
+
37
41
  Generating a PDF this way always regenerates the full HTML site alongside
38
42
  it in the same Antora run (`@antora/assembler`/`@antora/pdf-extension` hook
39
43
  into normal site generation rather than replacing it) - there's no way to
@@ -103,6 +107,12 @@ during) for the fix and the full explanation.
103
107
  already run.
104
108
  - `extensions/` - `roles-labels-postprocessor.js` ports the essential parts
105
109
  of the Antora extension of the same name (see "Known limitations" below);
110
+ `page-role-preprocessor.js` carries a page's `:page-role:` across to the
111
+ PDF as the label under that page's title (on the real site the page layout
112
+ puts the role on the page's `<h1>`, which this pipeline never goes through,
113
+ and the assembler leaves the role as an attribute entry before the page
114
+ title that never reaches the converted HTML - so it is copied onto the
115
+ title as a role first, for the postprocessor above to turn into a label);
106
116
  `tabbed-example-postprocessor.js` labels each alternative of a
107
117
  `[.tabbed-example]`/`[.include-with-X]` group with its own real-site tab
108
118
  text (ported directly from the real site's own client-side JS, which
package/extension.js CHANGED
@@ -23,7 +23,26 @@ const DEFAULT_CONFIG_FILE = path.join(__dirname, 'antora-assembler-pdf.yml')
23
23
  // as the one argument - confirmed directly against the installed Antora,
24
24
  // including that @antora/pdf-extension's own optional second `providers`
25
25
  // parameter is never actually populated by a real Antora invocation either.
26
+ // A PDF contains a single version: the one being built. The playbook of a docset usually lists
27
+ // its other versions as branches of the same repository (HEAD, 5.x, 4.4, ...), and building them
28
+ // would render a PDF for each one, only to throw all but one away. A local content source is the
29
+ // repository being built, and HEAD is the branch that is checked out, so those sources are limited
30
+ // to HEAD, before any content is collected. Remote sources are left as they are.
31
+ const REMOTE_URL = /^(?:[a-z][a-z0-9+.-]*:\/\/|git@)/i
32
+
33
+ function limitLocalSourcesToHead ({ playbook }) {
34
+ const logger = this.getLogger?.('neo4j-pdf-generator')
35
+ for (const source of playbook?.content?.sources ?? []) {
36
+ if (REMOTE_URL.test(source.url ?? '')) continue
37
+ const branches = [].concat(source.branches ?? [])
38
+ if (branches.length === 1 && branches[0] === 'HEAD') continue
39
+ source.branches = ['HEAD']
40
+ logger?.info({ source: { url: source.url } }, 'Building HEAD only (was: %s)', branches.join(', ') || 'the playbook default')
41
+ }
42
+ }
43
+
26
44
  module.exports.register = function ({ config = {} } = {}) {
45
+ this.once('playbookBuilt', limitLocalSourcesToHead.bind(this))
27
46
  const resolvedConfig = Object.assign({ configFile: DEFAULT_CONFIG_FILE }, config)
28
47
  return pdfExtension.register.call(this, { config: resolvedConfig })
29
48
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@neo4j-antora/pdf-generator",
3
- "version": "0.1.12",
3
+ "version": "0.1.14",
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": [
@@ -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
+ }