@neo4j-antora/pdf-generator 0.1.14 → 0.1.16
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/extension.js +12 -1
- package/package.json +1 -1
- package/pdf-theme/print.css +31 -13
- package/scripts/convert.js +10 -2
- package/scripts/setup-vendor.js +38 -0
- package/vendor/extensions/kroki-adapter.js +39 -0
package/extension.js
CHANGED
|
@@ -41,8 +41,19 @@ function limitLocalSourcesToHead ({ playbook }) {
|
|
|
41
41
|
}
|
|
42
42
|
}
|
|
43
43
|
|
|
44
|
+
// When the renderer fails, the assembler logs nothing, adds no PDF and Antora still exits 0, so the
|
|
45
|
+
// failure only shows up later, when the workflow cannot find a PDF. Registered after
|
|
46
|
+
// @antora/pdf-extension, this runs once the assembler has added its PDFs to the content catalog,
|
|
47
|
+
// and fails the build if there are none.
|
|
48
|
+
function requirePdf ({ contentCatalog }) {
|
|
49
|
+
const pdfs = contentCatalog.findBy({ family: 'export' }).filter((file) => file.out?.path?.endsWith('.pdf'))
|
|
50
|
+
if (!pdfs.length) throw new Error('@neo4j-antora/pdf-generator: no PDF was generated (see the renderer output above)')
|
|
51
|
+
}
|
|
52
|
+
|
|
44
53
|
module.exports.register = function ({ config = {} } = {}) {
|
|
45
54
|
this.once('playbookBuilt', limitLocalSourcesToHead.bind(this))
|
|
46
55
|
const resolvedConfig = Object.assign({ configFile: DEFAULT_CONFIG_FILE }, config)
|
|
47
|
-
|
|
56
|
+
const result = pdfExtension.register.call(this, { config: resolvedConfig })
|
|
57
|
+
this.once('navigationBuilt', requirePdf)
|
|
58
|
+
return result
|
|
48
59
|
}
|
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.16",
|
|
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/pdf-theme/print.css
CHANGED
|
@@ -66,7 +66,7 @@
|
|
|
66
66
|
|
|
67
67
|
@page {
|
|
68
68
|
size: A4;
|
|
69
|
-
margin:
|
|
69
|
+
margin: 15mm;
|
|
70
70
|
}
|
|
71
71
|
/* Verso (even/left) pages: page number on the outer (left) edge */
|
|
72
72
|
@page :left {
|
|
@@ -117,8 +117,8 @@
|
|
|
117
117
|
body.book {
|
|
118
118
|
font-family: var(--font-body);
|
|
119
119
|
color: var(--brand-text);
|
|
120
|
-
font-size:
|
|
121
|
-
line-height: 1.
|
|
120
|
+
font-size: 10pt;
|
|
121
|
+
line-height: 1.35;
|
|
122
122
|
/* Real site.css sets a bare `body{font-weight:var(--weight-light)}` (300) - meant for
|
|
123
123
|
its own Public Sans webfont (see the Google Fonts @import this theme adds below),
|
|
124
124
|
not whatever this static PDF render actually has loaded, and reads as faint, thin
|
|
@@ -161,13 +161,13 @@ body.book {
|
|
|
161
161
|
own README).
|
|
162
162
|
`height: 100%` doesn't resolve here - this renderer's Vivliostyle Viewer
|
|
163
163
|
layout engine doesn't give this box a definite containing-block height
|
|
164
|
-
to be a percentage of, so centering silently no-ops.
|
|
164
|
+
to be a percentage of, so centering silently no-ops. 267mm is the actual
|
|
165
165
|
per-page content height this theme produces: A4 (297mm) minus this
|
|
166
|
-
file's own `@page` rule above (
|
|
166
|
+
file's own `@page` rule above (15mm top margin, 15mm bottom) - update
|
|
167
167
|
this alongside that rule if it ever changes. */
|
|
168
168
|
#colophon {
|
|
169
169
|
page-break-after: always;
|
|
170
|
-
height:
|
|
170
|
+
height: 267mm;
|
|
171
171
|
display: flex;
|
|
172
172
|
flex-direction: column;
|
|
173
173
|
justify-content: center;
|
|
@@ -279,8 +279,8 @@ body.book {
|
|
|
279
279
|
per a style pass comparing against the legacy pipeline's own output, where chapter
|
|
280
280
|
titles were much more prominent than this theme's original 18pt. */
|
|
281
281
|
#pdf-export h2 { font-size: 26pt; border-bottom: 1pt solid var(--brand-border); padding-bottom: 6pt; }
|
|
282
|
-
#pdf-export h3 { font-size:
|
|
283
|
-
#pdf-export h4 { font-size:
|
|
282
|
+
#pdf-export h3 { font-size: 16pt; }
|
|
283
|
+
#pdf-export h4 { font-size: 13pt; }
|
|
284
284
|
/* A page nested two levels deep in its component's nav (e.g. a page under a sub-chapter)
|
|
285
285
|
has its own internal headings shifted down by that same nav depth once merged into this
|
|
286
286
|
book, same as the page's own top heading is (see convert.js's comment on heading
|
|
@@ -347,9 +347,9 @@ body.book {
|
|
|
347
347
|
background-clip: padding-box keeps the background strictly inside the border instead
|
|
348
348
|
of under it. */
|
|
349
349
|
background-clip: padding-box;
|
|
350
|
-
padding: 8pt
|
|
351
|
-
font-size:
|
|
352
|
-
line-height: 1.
|
|
350
|
+
padding: 6pt 8pt;
|
|
351
|
+
font-size: 8.5pt;
|
|
352
|
+
line-height: 1.3;
|
|
353
353
|
white-space: pre-wrap;
|
|
354
354
|
word-break: break-word;
|
|
355
355
|
}
|
|
@@ -413,11 +413,11 @@ body.book {
|
|
|
413
413
|
border: 0.5pt solid var(--brand-border);
|
|
414
414
|
width: 100%;
|
|
415
415
|
break-inside: auto;
|
|
416
|
-
font-size:
|
|
416
|
+
font-size: 9pt;
|
|
417
417
|
}
|
|
418
418
|
#pdf-export table.tableblock th, #pdf-export table.tableblock td {
|
|
419
419
|
border: 0.5pt solid var(--brand-border);
|
|
420
|
-
padding: 5pt
|
|
420
|
+
padding: 3pt 5pt;
|
|
421
421
|
vertical-align: top;
|
|
422
422
|
/* Same box-sizing bug as the admonition-in-table-cell fix above, just unfixed here for
|
|
423
423
|
every ordinary cell - with no explicit box-sizing, border+padding (15pt total: 2x7pt
|
|
@@ -848,3 +848,21 @@ h2 > .flex-label {
|
|
|
848
848
|
|
|
849
849
|
/* TOC (hidden fixed div rendered separately by asciidoctor-web-pdf's own TOC mechanism) */
|
|
850
850
|
.toc-entry a { color: var(--brand-text); text-decoration: none; }
|
|
851
|
+
|
|
852
|
+
/* Print density. Real site.css spaces content for a screen: a 1.8 line height on .doc (which
|
|
853
|
+
overrides body.book above), 1.5rem under every block, 2rem around tables, and 1.5rem of
|
|
854
|
+
padding inside the code element of every listing, on top of the padding of its pre. In print
|
|
855
|
+
that made a book about 1.5 times as long as the legacy pipeline produced for the same
|
|
856
|
+
content. These rules tighten the spacing for print only. */
|
|
857
|
+
#pdf-export .doc { line-height: 1.5; padding-bottom: 0; }
|
|
858
|
+
#pdf-export .doc table.tableblock, #pdf-export .doc td, #pdf-export .doc th { line-height: 1.45; }
|
|
859
|
+
#pdf-export .doc pre.highlight > code, #pdf-export .doc pre > code { padding: 0; }
|
|
860
|
+
#pdf-export .doc .paragraph, #pdf-export .doc .ulist, #pdf-export .doc .olist, #pdf-export .doc .dlist,
|
|
861
|
+
#pdf-export .doc .listingblock, #pdf-export .doc .literalblock, #pdf-export .doc .exampleblock,
|
|
862
|
+
#pdf-export .doc .imageblock, #pdf-export .doc .colist { margin: 0 0 1.25em; }
|
|
863
|
+
#pdf-export .doc .admonitionblock { margin: 1.25em 0; }
|
|
864
|
+
#pdf-export .doc table.tableblock { margin: 0.75em 0 1.25em; }
|
|
865
|
+
#pdf-export .doc h3 { margin: 1.2em 0 0.5em; line-height: 1.25; }
|
|
866
|
+
#pdf-export .doc h4, #pdf-export .doc h5, #pdf-export .doc h6 { margin: 1em 0 0.4em; line-height: 1.25; }
|
|
867
|
+
/* Keep a block title (Query, Parameters, Result, ...) on the same page as its block. */
|
|
868
|
+
#pdf-export .doc .listingblock > .title, #pdf-export .doc .tableblock > .title, #pdf-export .doc table.tableblock > caption { break-after: avoid; }
|
package/scripts/convert.js
CHANGED
|
@@ -37,6 +37,7 @@ const COLOPHON_POSTPROCESSOR = path.join(__dirname, '../vendor/extensions/coloph
|
|
|
37
37
|
const ABSOLUTE_LINKS_POSTPROCESSOR = path.join(__dirname, '../vendor/extensions/absolute-links-postprocessor.js')
|
|
38
38
|
const DOC_WRAPPER_POSTPROCESSOR = path.join(__dirname, '../vendor/extensions/doc-wrapper-postprocessor.js')
|
|
39
39
|
const CYPHER_LANGUAGE_ADAPTER = path.join(__dirname, '../vendor/extensions/cypher-language-adapter.js')
|
|
40
|
+
const KROKI_ADAPTER = path.join(__dirname, '../vendor/extensions/kroki-adapter.js')
|
|
40
41
|
const TABBED_EXAMPLE_POSTPROCESSOR = path.join(__dirname, '../vendor/extensions/tabbed-example-postprocessor.js')
|
|
41
42
|
|
|
42
43
|
// Unlike the extensions above, `@djencks/asciidoctor-mathjax` isn't a
|
|
@@ -218,10 +219,16 @@ function readStdin () {
|
|
|
218
219
|
// asciidoctor-web-pdf only reads these from the environment (no -a attribute or
|
|
219
220
|
// CLI flag equivalent - see lib/browser.js) and defaults to 30s, which a large
|
|
220
221
|
// docset can easily exceed. Give it more headroom here rather than relying on
|
|
221
|
-
// whoever runs the build to remember to export these.
|
|
222
|
+
// whoever runs the build to remember to export these. Rendering, printing and
|
|
223
|
+
// protocol calls (PUPPETEER_PROTOCOL_TIMEOUT, added by setup-vendor.js) all run
|
|
224
|
+
// for as long as the whole layout takes, about 40 minutes for the Cypher Manual,
|
|
225
|
+
// so they get 2 hours. Values already set in the environment win.
|
|
226
|
+
const TWO_HOURS = String(2 * 60 * 60 * 1000)
|
|
222
227
|
const PUPPETEER_TIMEOUT_ENV = {
|
|
223
228
|
PUPPETEER_NAVIGATION_TIMEOUT: '180000',
|
|
224
|
-
PUPPETEER_RENDERING_TIMEOUT:
|
|
229
|
+
PUPPETEER_RENDERING_TIMEOUT: TWO_HOURS,
|
|
230
|
+
PUPPETEER_PRINT_TIMEOUT: TWO_HOURS,
|
|
231
|
+
PUPPETEER_PROTOCOL_TIMEOUT: TWO_HOURS,
|
|
225
232
|
}
|
|
226
233
|
|
|
227
234
|
// antora-assembler-pdf.yml deliberately does NOT set a `stylesheet` attribute
|
|
@@ -292,6 +299,7 @@ Promise.all([buildStylesheet(), readStdin()]).then(([stylesheet, adoc]) => {
|
|
|
292
299
|
'--extension', ROLES_LABELS_POSTPROCESSOR,
|
|
293
300
|
'--extension', REMOTE_INCLUDE_ADAPTER,
|
|
294
301
|
'--extension', MACROS_ADAPTER,
|
|
302
|
+
'--extension', KROKI_ADAPTER,
|
|
295
303
|
'--extension', COLOPHON_POSTPROCESSOR,
|
|
296
304
|
'--extension', ABSOLUTE_LINKS_POSTPROCESSOR,
|
|
297
305
|
'--extension', DOC_WRAPPER_POSTPROCESSOR,
|
package/scripts/setup-vendor.js
CHANGED
|
@@ -63,3 +63,41 @@ if (result.error || result.status !== 0) {
|
|
|
63
63
|
console.error('@neo4j-antora/pdf-generator: failed to install its isolated asciidoctor-pdf renderer (see vendor/package.json)')
|
|
64
64
|
process.exit(result.status || 1)
|
|
65
65
|
}
|
|
66
|
+
|
|
67
|
+
// Two patches to asciidoctor-web-pdf's lib/browser.js. Each fails the install if its anchor is
|
|
68
|
+
// missing, so a renderer upgrade cannot silently drop it.
|
|
69
|
+
//
|
|
70
|
+
// 1. protocolTimeout: Chromium is launched without one, so every call Puppeteer makes to the page
|
|
71
|
+
// is limited to the Puppeteer default of 180 seconds. While Vivliostyle lays out a large
|
|
72
|
+
// document, the page cannot answer the call that checks whether layout has finished, and the
|
|
73
|
+
// conversion fails with "Waiting failed" (the Cypher Manual needs about 30 minutes). None of
|
|
74
|
+
// the PUPPETEER_*_TIMEOUT variables that asciidoctor-web-pdf reads change this, so the launch
|
|
75
|
+
// options read PUPPETEER_PROTOCOL_TIMEOUT as well.
|
|
76
|
+
// 2. polling: the check for finished layout polls on requestAnimationFrame by default. In long
|
|
77
|
+
// local builds the browser has stopped producing animation frames, so the check never ran again
|
|
78
|
+
// and the build hung after layout had finished. A 1-second timer does not depend on frames.
|
|
79
|
+
const browserJs = path.join(vendorDir, 'node_modules/asciidoctor-pdf/lib/browser.js')
|
|
80
|
+
const PATCHES = [
|
|
81
|
+
{
|
|
82
|
+
done: 'protocolTimeout',
|
|
83
|
+
anchor: ' headless: !preview,\n',
|
|
84
|
+
replacement:
|
|
85
|
+
' headless: !preview,\n' +
|
|
86
|
+
' protocolTimeout: process.env.PUPPETEER_PROTOCOL_TIMEOUT ? Number(process.env.PUPPETEER_PROTOCOL_TIMEOUT) : undefined,\n',
|
|
87
|
+
},
|
|
88
|
+
{
|
|
89
|
+
done: 'timeout: this.renderingTimeout, polling: 1000',
|
|
90
|
+
anchor: ' { timeout: this.renderingTimeout },\n',
|
|
91
|
+
replacement: ' { timeout: this.renderingTimeout, polling: 1000 },\n',
|
|
92
|
+
},
|
|
93
|
+
]
|
|
94
|
+
let browserSource = fs.readFileSync(browserJs, 'utf8')
|
|
95
|
+
for (const { done, anchor, replacement } of PATCHES) {
|
|
96
|
+
if (browserSource.includes(done)) continue
|
|
97
|
+
if (browserSource.split(anchor).length !== 2) {
|
|
98
|
+
console.error(`@neo4j-antora/pdf-generator: cannot patch ${browserJs}: expected exactly one ${JSON.stringify(anchor.trim())}`)
|
|
99
|
+
process.exit(1)
|
|
100
|
+
}
|
|
101
|
+
browserSource = browserSource.replace(anchor, replacement)
|
|
102
|
+
}
|
|
103
|
+
fs.writeFileSync(browserJs, browserSource)
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
// Renders diagram blocks such as [graphviz] and [mermaid] as images from a Kroki server, the same
|
|
4
|
+
// way the asciidoctor-kroki extension does for the HTML site. asciidoctor-kroki itself cannot run
|
|
5
|
+
// here: it depends on the Opal API of Asciidoctor.js 2 and 3, and this renderer uses Asciidoctor.js
|
|
6
|
+
// 4 ("Opal is not defined"). Without this, every diagram is printed as its raw source.
|
|
7
|
+
//
|
|
8
|
+
// The image URL has the same format as the one asciidoctor-kroki builds:
|
|
9
|
+
// <kroki-server-url>/<diagram type>/svg/<source, deflated and base64url-encoded>
|
|
10
|
+
// kroki-server-url defaults to https://kroki.io, as it does in asciidoctor-kroki.
|
|
11
|
+
const zlib = require('node:zlib')
|
|
12
|
+
|
|
13
|
+
const DIAGRAM_TYPES = [
|
|
14
|
+
'actdiag', 'blockdiag', 'bpmn', 'bytefield', 'c4plantuml', 'd2', 'dbml', 'ditaa', 'erd',
|
|
15
|
+
'excalidraw', 'graphviz', 'mermaid', 'nomnoml', 'nwdiag', 'packetdiag', 'pikchr', 'plantuml',
|
|
16
|
+
'rackdiag', 'seqdiag', 'structurizr', 'svgbob', 'symbolator', 'tikz', 'umlet', 'vega', 'vegalite',
|
|
17
|
+
'wavedrom', 'wireviz',
|
|
18
|
+
]
|
|
19
|
+
|
|
20
|
+
function encode (source) {
|
|
21
|
+
return zlib.deflateSync(Buffer.from(source, 'utf8'), { level: 9 }).toString('base64url')
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
module.exports.register = function (registry) {
|
|
25
|
+
for (const type of DIAGRAM_TYPES) {
|
|
26
|
+
registry.block(type, function () {
|
|
27
|
+
this.onContexts('listing', 'literal')
|
|
28
|
+
this.process(function (parent, reader, attrs) {
|
|
29
|
+
const server = String(parent.getDocument().getAttribute('kroki-server-url', 'https://kroki.io')).replace(/\/+$/, '')
|
|
30
|
+
const target = `${server}/${type}/svg/${encode(reader.getLines().join('\n'))}`
|
|
31
|
+
const imageAttrs = { target, alt: attrs.alt || `${type} diagram` }
|
|
32
|
+
for (const name of ['id', 'title', 'role', 'width', 'height', 'align']) {
|
|
33
|
+
if (attrs[name] != null) imageAttrs[name] = attrs[name]
|
|
34
|
+
}
|
|
35
|
+
return this.createImageBlock(parent, imageAttrs)
|
|
36
|
+
})
|
|
37
|
+
})
|
|
38
|
+
}
|
|
39
|
+
}
|