@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 +10 -0
- package/extension.js +19 -0
- package/package.json +1 -1
- package/scripts/convert.js +2 -0
- package/vendor/extensions/page-role-preprocessor.js +83 -0
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.
|
|
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": [
|
package/scripts/convert.js
CHANGED
|
@@ -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
|
+
}
|