@neo4j-antora/pdf-generator 0.1.7 → 0.1.9
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 +42 -16
- package/package.json +7 -1
- package/pdf-theme/print.css +254 -42
- package/scripts/convert.js +152 -44
- package/vendor/extensions/cypher-language-adapter.js +69 -0
- package/vendor/extensions/doc-wrapper-postprocessor.js +46 -0
- package/vendor/languages/cypher.js +61 -0
package/README.adoc
CHANGED
|
@@ -65,18 +65,31 @@ override individual assembler settings if needed.
|
|
|
65
65
|
Also works around a real bug (`ifndef::backend-pdf[]` not evaluating
|
|
66
66
|
correctly under this pipeline) for docsets using that idiom - a no-op for
|
|
67
67
|
any docset that doesn't.
|
|
68
|
-
- `pdf-theme/print.css` -
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
68
|
+
- `pdf-theme/print.css` - combined at build time (see `convert.js`'s
|
|
69
|
+
`buildStylesheet()`) with the real, live site's own `assets/css/site.css`
|
|
70
|
+
(fetched fresh from whichever environment `DOCS_PUBLISH_URL` points at -
|
|
71
|
+
dev sandbox vs prod have different CSS, not just a different host) and
|
|
72
|
+
Google Fonts' own Public Sans CSS - real site.css supplies almost all
|
|
73
|
+
content styling (admonitions, labels, tables, images, syntax-highlighting
|
|
74
|
+
token colours, ...) for free, kept automatically in sync with the live
|
|
75
|
+
site as it evolves, rather than this theme hand-reimplementing (and
|
|
76
|
+
inevitably drifting from) each one individually. `print.css` itself is
|
|
77
|
+
only what's genuinely paged-media-specific (page size/margins, the cover/
|
|
78
|
+
colophon/TOC, footnote floats) plus a deliberate, documented set of
|
|
79
|
+
overrides for places real site.css assumes a live, scripted browser page
|
|
80
|
+
this static render doesn't have - most prominently, several `display:
|
|
81
|
+
flex` layouts (`.imageblock`, `.sect2`, ...) that this renderer
|
|
82
|
+
(Vivliostyle) doesn't paginate correctly at book length, overridden back
|
|
83
|
+
to `display: block` (see `doc-wrapper-postprocessor.js` for why these
|
|
84
|
+
selectors, written against Antora's own `.doc`-wrapped HTML, match this
|
|
85
|
+
pipeline's plain Asciidoctor HTML5 output at all). Asciidoctor's own HTML5
|
|
86
|
+
backend has no Cypher syntax-highlighting grammar; `vendor/languages/
|
|
87
|
+
cypher.js` vendors the same community `highlightjs-cypher` grammar the
|
|
88
|
+
real site itself bundles (confirmed byte-for-byte), registered via
|
|
89
|
+
`cypher-language-adapter.js`. Fonts are vendored into
|
|
90
|
+
`pdf-theme/assets/fonts/` rather than read from a docset's own HTML
|
|
91
|
+
build output, so this theme has no dependency on that build having
|
|
92
|
+
already run.
|
|
80
93
|
- `extensions/` - `roles-labels-postprocessor.js` ports the essential parts
|
|
81
94
|
of the Antora extension of the same name (see "Known limitations" below);
|
|
82
95
|
`macros-adapter.js` and `remote-include-adapter.js` wrap the real
|
|
@@ -152,7 +165,20 @@ override individual assembler settings if needed.
|
|
|
152
165
|
(e.g. the cover or a colophon page) instead of inline marks. Needs a call
|
|
153
166
|
on the right behaviour before doing the (otherwise straightforward)
|
|
154
167
|
registration work.
|
|
155
|
-
- This package's `print.css`
|
|
156
|
-
`docs-ui`'s
|
|
157
|
-
`
|
|
158
|
-
|
|
168
|
+
- This package's `print.css` still carries its own hand-resolved copy of
|
|
169
|
+
`docs-ui`'s label colours (`span.label--*`) as a fallback for when the
|
|
170
|
+
real site.css fetch fails (see `buildStylesheet()`'s own comment) - those,
|
|
171
|
+
not read from `docs-ui` live, can drift from the Needle tokens/`labels.css`
|
|
172
|
+
they were resolved from until someone notices and re-syncs them by hand.
|
|
173
|
+
Normal builds (the fetch succeeding) get live label colours from the real
|
|
174
|
+
site.css instead, same as everything else.
|
|
175
|
+
- A table with many columns and no `cols=` width hints (Asciidoctor then
|
|
176
|
+
emits no `<colgroup>` at all) can still wrap a column's own header word
|
|
177
|
+
mid-word even when the column is visually wide enough for it, because
|
|
178
|
+
this renderer's table layout starves a short-content column's width in
|
|
179
|
+
favour of a sibling column holding a long, unbreakable value (e.g. a
|
|
180
|
+
`"RELATIONSHIP"`-length string) - `table-layout: fixed` (the standard CSS
|
|
181
|
+
fix for exactly this) has no visible effect here, suggesting Vivliostyle's
|
|
182
|
+
own paginated-table layout doesn't fully implement it. Not yet resolved -
|
|
183
|
+
a very-many-column result table is a real, pre-existing edge case, not a
|
|
184
|
+
regression from the real-site.css-reuse work above.
|
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.9",
|
|
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": [
|
|
@@ -10,6 +10,7 @@
|
|
|
10
10
|
"pdf-theme",
|
|
11
11
|
"scripts",
|
|
12
12
|
"vendor/extensions",
|
|
13
|
+
"vendor/languages",
|
|
13
14
|
"README.adoc"
|
|
14
15
|
],
|
|
15
16
|
"scripts": {
|
|
@@ -28,5 +29,10 @@
|
|
|
28
29
|
"@neo4j-documentation/macros": "1.0.4",
|
|
29
30
|
"@neo4j-documentation/remote-include": "1.0.0",
|
|
30
31
|
"node-html-parser": "9.0.4"
|
|
32
|
+
},
|
|
33
|
+
"repository": {
|
|
34
|
+
"type": "git",
|
|
35
|
+
"url": "git+https://github.com/neo4j/docs-tools.git",
|
|
36
|
+
"directory": "pdf-generator"
|
|
31
37
|
}
|
|
32
38
|
}
|
package/pdf-theme/print.css
CHANGED
|
@@ -1,9 +1,20 @@
|
|
|
1
1
|
/* Print-specific stylesheet shared by every docset's PDF export (see
|
|
2
2
|
docs-tools/pdf/README - checked out into each repo's build by
|
|
3
|
-
reusable-pdf-build.yml).
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
3
|
+
reusable-pdf-build.yml).
|
|
4
|
+
|
|
5
|
+
convert.js fetches the real, live site.css and concatenates it before this
|
|
6
|
+
file into one combined stylesheet - real site.css supplies almost all real
|
|
7
|
+
content styling (admonitions, labels, tables, quoteblocks, images, examples,
|
|
8
|
+
...) for free, kept automatically in sync with the live site as it evolves,
|
|
9
|
+
rather than this theme hand-reimplementing (and inevitably drifting from)
|
|
10
|
+
each one individually - doc-wrapper-postprocessor.js adds the `docs`/`doc`
|
|
11
|
+
classes real site.css's selectors expect but plain Asciidoctor html5 output
|
|
12
|
+
doesn't have on its own. This file only has what's genuinely paged-media
|
|
13
|
+
specific and has no browser equivalent at all: @page size/margins, the
|
|
14
|
+
cover/colophon/license pages, the TOC's leader() dots, footnote floats,
|
|
15
|
+
and page-break rules - plus a handful of small, deliberate overrides (see
|
|
16
|
+
their own comments) for places real site.css assumes a live, scripted
|
|
17
|
+
browser page this static render doesn't have.
|
|
7
18
|
|
|
8
19
|
Every asset path below is relative to this file's own location, not to
|
|
9
20
|
whatever repo/cwd the build runs in - a browser resolves CSS url()s
|
|
@@ -11,6 +22,15 @@
|
|
|
11
22
|
wherever docs-tools gets checked out. Font files are vendored into
|
|
12
23
|
assets/fonts/ here (not read from a docset's own build output) so this
|
|
13
24
|
theme has no dependency on that docset's HTML build having already run. */
|
|
25
|
+
:root {
|
|
26
|
+
/* Real site.css declares `color-scheme: light dark` (supports both, picked by
|
|
27
|
+
the viewer's own OS/browser preference) - meaningless for a static, downloaded
|
|
28
|
+
PDF with no "viewer preference" of its own, and left unset would be at the
|
|
29
|
+
mercy of whatever default the renderer's own environment happens to have.
|
|
30
|
+
Forced to light explicitly, after real site.css (loads first in the combined
|
|
31
|
+
stylesheet - see convert.js) so this wins on equal specificity. */
|
|
32
|
+
color-scheme: light;
|
|
33
|
+
}
|
|
14
34
|
@font-face {
|
|
15
35
|
font-family: 'Roboto Mono';
|
|
16
36
|
font-weight: 400;
|
|
@@ -37,6 +57,9 @@
|
|
|
37
57
|
--brand-danger-bg: #fdf1ef;
|
|
38
58
|
--brand-warning: #8a5a00;
|
|
39
59
|
--brand-warning-bg: #fdf6e8;
|
|
60
|
+
--brand-success: #3f7824;
|
|
61
|
+
--brand-success-border: #90cb62;
|
|
62
|
+
--brand-success-bg: #e7fcd7;
|
|
40
63
|
--font-body: 'Public Sans', 'Nunito Sans', 'Helvetica Neue', Helvetica, Arial, sans-serif;
|
|
41
64
|
--font-mono: 'Roboto Mono', Menlo, Monaco, Consolas, 'Courier New', monospace;
|
|
42
65
|
}
|
|
@@ -96,6 +119,13 @@ body.book {
|
|
|
96
119
|
color: var(--brand-text);
|
|
97
120
|
font-size: 10.5pt;
|
|
98
121
|
line-height: 1.5;
|
|
122
|
+
/* Real site.css sets a bare `body{font-weight:var(--weight-light)}` (300) - meant for
|
|
123
|
+
its own Public Sans webfont (see the Google Fonts @import this theme adds below),
|
|
124
|
+
not whatever this static PDF render actually has loaded, and reads as faint, thin
|
|
125
|
+
text next to this theme's own headings. `body.book` (element+class) already
|
|
126
|
+
outranks that bare `body` (element-only) rule, so this alone is enough to win -
|
|
127
|
+
reported directly: "text is just thin". */
|
|
128
|
+
font-weight: 400;
|
|
99
129
|
}
|
|
100
130
|
|
|
101
131
|
#cover.title-page {
|
|
@@ -211,12 +241,34 @@ body.book {
|
|
|
211
241
|
.sect1 { break-before: page; }
|
|
212
242
|
.sect1:first-child { break-before: avoid; }
|
|
213
243
|
|
|
244
|
+
/* The sandbox/restructure site.css (docs-ui, not yet in production) lays every level-2
|
|
245
|
+
section's own wrapper div out as `body.docs .sect2{display:flex;flex-direction:column;
|
|
246
|
+
border-radius:16px;...}` - our own doc-wrapper-postprocessor.js already adds `docs` to
|
|
247
|
+
<body>, so this matches every single `.sect2` directly. Harmless for one or two
|
|
248
|
+
sections in a browser, but this renderer (Vivliostyle) can't paginate a long document
|
|
249
|
+
with dozens/hundreds of `.sect2`s all laid out as flex columns - confirmed directly: a
|
|
250
|
+
real multi-chapter book (production site.css: 305 pages, ~200s, succeeds) hard-fails
|
|
251
|
+
(180s timeout, no PDF at all) the moment just this one rule is present, same root
|
|
252
|
+
cause and same fix as the `.toc a`/`.imageblock` `display:flex` bugs already fixed
|
|
253
|
+
above - block layout gives the same visual stacking without the flex layout this
|
|
254
|
+
renderer can't handle at this scale. */
|
|
255
|
+
#pdf-export .sect2 { display: block; }
|
|
256
|
+
|
|
214
257
|
/* The closing License page (convert.js always appends one - see its own comment) is a
|
|
215
258
|
[discrete] heading, so it isn't wrapped in a .sect1 div the way every real chapter is,
|
|
216
259
|
and therefore doesn't inherit the page-break-before rule above. */
|
|
217
260
|
#license { break-before: page; }
|
|
218
261
|
|
|
219
|
-
|
|
262
|
+
/* `#pdf-export` (the id doc-wrapper-postprocessor.js adds to <body>) prefixes every
|
|
263
|
+
heading/code/table/admonition/quoteblock/label selector below - real site.css styles
|
|
264
|
+
all of these the same way, under its own `.doc <thing>` (or deeper, e.g.
|
|
265
|
+
`.doc h2:not(.discrete)`, `.doc table.tableblock>:not(thead) th`) selectors, which
|
|
266
|
+
otherwise out-specificity this theme's own plain element/single-class selectors for
|
|
267
|
+
the same property regardless of load order, and silently win - reported directly:
|
|
268
|
+
headings far too small, no table borders/stripes, malformed admonition/code-block
|
|
269
|
+
corners. See doc-wrapper-postprocessor.js's own comment on why an id (rather than
|
|
270
|
+
fixing each individually, as happened first with .imageblock below) is the right fix. */
|
|
271
|
+
#pdf-export h1, #pdf-export h2, #pdf-export h3, #pdf-export h4, #pdf-export h5, #pdf-export h6 {
|
|
220
272
|
font-family: var(--font-body);
|
|
221
273
|
color: var(--brand-primary-strong);
|
|
222
274
|
font-weight: 700;
|
|
@@ -226,9 +278,9 @@ h1, h2, h3, h4, h5, h6 {
|
|
|
226
278
|
convert.js's own comment on heading levels) - testing locally against docs-java-reference
|
|
227
279
|
per a style pass comparing against the legacy pipeline's own output, where chapter
|
|
228
280
|
titles were much more prominent than this theme's original 18pt. */
|
|
229
|
-
h2 { font-size: 26pt; border-bottom: 1pt solid var(--brand-border); padding-bottom: 6pt; }
|
|
230
|
-
h3 { font-size: 18pt; }
|
|
231
|
-
h4 { font-size: 14pt; }
|
|
281
|
+
#pdf-export h2 { font-size: 26pt; border-bottom: 1pt solid var(--brand-border); padding-bottom: 6pt; }
|
|
282
|
+
#pdf-export h3 { font-size: 18pt; }
|
|
283
|
+
#pdf-export h4 { font-size: 14pt; }
|
|
232
284
|
/* A page nested two levels deep in its component's nav (e.g. a page under a sub-chapter)
|
|
233
285
|
has its own internal headings shifted down by that same nav depth once merged into this
|
|
234
286
|
book, same as the page's own top heading is (see convert.js's comment on heading
|
|
@@ -238,30 +290,70 @@ h4 { font-size: 14pt; }
|
|
|
238
290
|
possible heading level, so it gets no further room to shrink into here; italicizing it
|
|
239
291
|
instead of sizing it down keeps it readable as a heading at a size this close to body
|
|
240
292
|
text. */
|
|
241
|
-
h5 { font-size: 12pt; }
|
|
242
|
-
h6 { font-size: 11pt; font-style: italic; }
|
|
293
|
+
#pdf-export h5 { font-size: 12pt; }
|
|
294
|
+
#pdf-export h6 { font-size: 11pt; font-style: italic; }
|
|
243
295
|
|
|
244
|
-
a { color: var(--brand-primary); text-decoration: none; }
|
|
296
|
+
#pdf-export a { color: var(--brand-primary); text-decoration: none; }
|
|
245
297
|
|
|
246
298
|
/* code */
|
|
247
|
-
pre, code, kbd, tt {
|
|
299
|
+
#pdf-export pre, #pdf-export code, #pdf-export kbd, #pdf-export tt {
|
|
248
300
|
font-family: var(--font-mono);
|
|
249
301
|
}
|
|
302
|
+
/* Real site.css's own `.doc pre:not(.highlight){height:100%;overflow-x:auto;...}` is
|
|
303
|
+
written for a `pre` sitting inside its own scrollable widget in a browser (the
|
|
304
|
+
`.listingblock` card below) - a fixed/percentage height a renderer can scroll inside
|
|
305
|
+
is the opposite of what a paginated PDF needs, and this renderer (Vivliostyle) doesn't
|
|
306
|
+
grow or fragment a box constrained to `height:100%` across a page break, it just stops
|
|
307
|
+
- this, not the `.listingblock` break-inside rule below, is what was actually losing
|
|
308
|
+
the rest of a long listing's content: reported directly, still truncated on page 47
|
|
309
|
+
even after that rule was changed to `auto`. Reset to a real, unconstrained height so
|
|
310
|
+
the block can grow across as many pages as its content needs. */
|
|
311
|
+
#pdf-export pre {
|
|
312
|
+
height: auto;
|
|
313
|
+
}
|
|
250
314
|
.listingblock {
|
|
251
|
-
|
|
315
|
+
/* A listing long enough to fill more than one page (reported directly: "codeblock in
|
|
316
|
+
Create the Movie Graph is truncated") can't have its own break avoided - forcing
|
|
317
|
+
avoid-page onto something taller than a full page doesn't push it to a fresh page,
|
|
318
|
+
it has nowhere that fits, and this renderer (Vivliostyle) drops the overflow instead
|
|
319
|
+
of falling back to breaking it, silently losing the rest of the block's content.
|
|
320
|
+
`auto` lets a long block break across pages like a normal paragraph would; a short
|
|
321
|
+
block (the common case) still naturally avoids breaking, since there's no pressure
|
|
322
|
+
to split something that already fits on one page. */
|
|
323
|
+
break-inside: auto;
|
|
252
324
|
margin: 1em 0;
|
|
253
325
|
}
|
|
254
|
-
.listingblock
|
|
326
|
+
/* Real site.css's own `.doc .listingblock{border:1px solid ...;border-radius:.5rem}`
|
|
327
|
+
draws its own card border+radius on the OUTER wrapper div, a completely different
|
|
328
|
+
element from the `pre` this theme styles below - rather than one competing rule
|
|
329
|
+
losing the cascade, both simply painted, nested (reported directly: "rounded corners
|
|
330
|
+
which don't look right" - two slightly different rounded boxes, one just inside the
|
|
331
|
+
other). Reset to nothing here so the `pre`'s own border below is the only box drawn -
|
|
332
|
+
same root cause, same fix, as `.admonitionblock` further down. */
|
|
333
|
+
#pdf-export .listingblock {
|
|
334
|
+
border: none;
|
|
335
|
+
border-radius: 0;
|
|
336
|
+
background: none;
|
|
337
|
+
}
|
|
338
|
+
#pdf-export .listingblock pre {
|
|
255
339
|
background: var(--brand-bg-strong);
|
|
256
340
|
border: 0.5pt solid var(--brand-border);
|
|
257
341
|
border-radius: 3pt;
|
|
342
|
+
/* Pairing a border-radius with a background on a box this renderer may slice across a
|
|
343
|
+
page break: without this, the background was observed painting fractionally past the
|
|
344
|
+
border's own inner edge at the rounded corners (most visible on the corner nearest a
|
|
345
|
+
page break), giving the border a broken/disappearing look right at the corner -
|
|
346
|
+
reported directly: "the bold border seems to disappear right in the corner".
|
|
347
|
+
background-clip: padding-box keeps the background strictly inside the border instead
|
|
348
|
+
of under it. */
|
|
349
|
+
background-clip: padding-box;
|
|
258
350
|
padding: 8pt 10pt;
|
|
259
351
|
font-size: 9pt;
|
|
260
352
|
line-height: 1.4;
|
|
261
353
|
white-space: pre-wrap;
|
|
262
354
|
word-break: break-word;
|
|
263
355
|
}
|
|
264
|
-
.listingblock .title {
|
|
356
|
+
#pdf-export .listingblock .title {
|
|
265
357
|
font-weight: 600;
|
|
266
358
|
color: var(--brand-text-weak);
|
|
267
359
|
font-size: 9.5pt;
|
|
@@ -277,55 +369,140 @@ pre, code, kbd, tt {
|
|
|
277
369
|
a wrapper class, since that covers both Asciidoctor's block (.imageblock) and inline
|
|
278
370
|
(.image) image markup the same way. An image with an explicit width: attribute in
|
|
279
371
|
its own image::[] macro still honours that (this only caps it, never upscales). */
|
|
280
|
-
img {
|
|
372
|
+
#pdf-export img {
|
|
281
373
|
max-width: 100%;
|
|
282
374
|
height: auto;
|
|
283
375
|
}
|
|
376
|
+
/* Real site.css lays `.doc .imageblock` out as `display: flex; flex-direction: column`
|
|
377
|
+
(centers the image, then its title/caption, beneath it) - harmless in a browser, but
|
|
378
|
+
Vivliostyle (this renderer's paged-media engine) doesn't size a flex column against the
|
|
379
|
+
page's content height the same way, and instead stretches the block to fill the entire
|
|
380
|
+
remaining page, leaving the image rendered tiny somewhere inside that oversized box. The
|
|
381
|
+
same category of bug as the TOC's `display: flex` (see #toc a above) - block + text-align
|
|
382
|
+
gets the same centered result without the flex layout Vivliostyle mishandles. */
|
|
383
|
+
#pdf-export .imageblock {
|
|
384
|
+
display: block;
|
|
385
|
+
text-align: center;
|
|
386
|
+
}
|
|
284
387
|
|
|
285
388
|
/* tables */
|
|
286
|
-
table.tableblock {
|
|
389
|
+
#pdf-export table.tableblock {
|
|
287
390
|
border-collapse: collapse;
|
|
391
|
+
/* `table-layout: auto` (the default) sizes each column by its own longest unbreakable
|
|
392
|
+
piece of content (here, a value like "RELATIONSHIP" or "token-lookup-1.0") - with
|
|
393
|
+
wrapping always allowed (`white-space`/`word-break` below), the renderer happily
|
|
394
|
+
starves a column with only short content (a header like "lastRead", data like "null")
|
|
395
|
+
down to far less than even its own header needs, to give that width to a column
|
|
396
|
+
whose longest token can't wrap - reported directly, precisely: "not even enough room
|
|
397
|
+
in the same column for the word null". `fixed` (with no per-column `width` set via
|
|
398
|
+
colgroup) instead divides the table's own width evenly across every column,
|
|
399
|
+
regardless of what any individual cell contains. */
|
|
400
|
+
table-layout: fixed;
|
|
401
|
+
/* Real site.css's own `table.tableblock` sets `border-radius:.25em;overflow:hidden`
|
|
402
|
+
(rounds and clips the table for its own un-collapsed card look) - border-collapse
|
|
403
|
+
and a clipping overflow don't agree on where a collapsed border actually paints in
|
|
404
|
+
this renderer, and the result was the table's own outer edge (left/right/bottom -
|
|
405
|
+
anywhere not already covered by the thead's own border-bottom) being clipped away
|
|
406
|
+
entirely, leaving only the inner grid lines visible - reported directly: "tables
|
|
407
|
+
have no left or right border". Resetting both, plus an explicit border on the table
|
|
408
|
+
element itself (belt-and-braces - the perimeter cells' own borders, below, already
|
|
409
|
+
cover this in a spec-conformant border-collapse implementation), removes the clip
|
|
410
|
+
and restores a plain, complete outer edge. */
|
|
411
|
+
border-radius: 0;
|
|
412
|
+
overflow: visible;
|
|
413
|
+
border: 0.5pt solid var(--brand-border);
|
|
288
414
|
width: 100%;
|
|
289
415
|
break-inside: auto;
|
|
290
416
|
font-size: 9.5pt;
|
|
291
417
|
}
|
|
292
|
-
table.tableblock th, table.tableblock td {
|
|
418
|
+
#pdf-export table.tableblock th, #pdf-export table.tableblock td {
|
|
293
419
|
border: 0.5pt solid var(--brand-border);
|
|
294
420
|
padding: 5pt 7pt;
|
|
295
421
|
vertical-align: top;
|
|
296
|
-
|
|
297
|
-
|
|
422
|
+
/* Same box-sizing bug as the admonition-in-table-cell fix above, just unfixed here for
|
|
423
|
+
every ordinary cell - with no explicit box-sizing, border+padding (15pt total: 2x7pt
|
|
424
|
+
padding + 2x0.5pt border) are added on top of whatever width this renderer's table
|
|
425
|
+
layout resolves for the column, instead of being carved out of it, leaving less
|
|
426
|
+
actual room for text than the column's own visible width implies - reported
|
|
427
|
+
directly, precisely: "lastRead" wraps after just "lastR" in a column visibly wide
|
|
428
|
+
enough for the whole word. border-box keeps padding+border inside the resolved
|
|
429
|
+
width instead. */
|
|
430
|
+
box-sizing: border-box;
|
|
431
|
+
}
|
|
432
|
+
#pdf-export table.tableblock thead th {
|
|
298
433
|
background: var(--brand-bg-strong);
|
|
299
434
|
color: var(--brand-text);
|
|
300
435
|
font-weight: 600;
|
|
301
436
|
}
|
|
302
|
-
|
|
437
|
+
/* Zebra-striping was added here once (reported directly: "tables are not striped"), then
|
|
438
|
+
removed again - the real site itself doesn't stripe tables at all (just header shading
|
|
439
|
+
+ row borders), and `--brand-bg-strong` is also this theme's own code-block background
|
|
440
|
+
colour, so a striped row's background was pixel-identical to an inline `code` span's
|
|
441
|
+
own background inside it, making the code span stop reading as a distinct element
|
|
442
|
+
(reported directly: "the table row background color is the same as code background
|
|
443
|
+
color"). Matching the real site's own un-striped look avoids the clash entirely. */
|
|
444
|
+
#pdf-export tr { break-inside: avoid; }
|
|
303
445
|
|
|
304
446
|
/* admonitions */
|
|
305
447
|
.admonitionblock { break-inside: avoid-page; margin: 1em 0; }
|
|
306
|
-
|
|
448
|
+
/* Same double-box bug as .listingblock above: real site.css's own
|
|
449
|
+
`.doc .admonitionblock{border-radius:.5rem;border-style:solid;border-width:1px}` draws
|
|
450
|
+
its own card border+radius on this outer wrapper, a different element from the
|
|
451
|
+
`td.content` box this theme styles below - both paint, nested (reported directly:
|
|
452
|
+
"same with admonitions"). Reset to nothing so td.content's own border below is the
|
|
453
|
+
only box drawn. */
|
|
454
|
+
#pdf-export .admonitionblock {
|
|
455
|
+
border: none;
|
|
456
|
+
border-radius: 0;
|
|
457
|
+
background: none;
|
|
458
|
+
/* Moved here from td.content (still a real table-cell element structurally, even once
|
|
459
|
+
`display: block` below changes how it lays out) rather than there - an admonition
|
|
460
|
+
nested inside a real table cell (Asciidoctor's `a|` syntax) was rendering this as a
|
|
461
|
+
plain default-grey border on every side instead of the intended coloured left
|
|
462
|
+
accent, as if the `<td>`'s own border-resolution (inherited from being part of an
|
|
463
|
+
HTML `<table>`, regardless of its CSS display type) was overriding the explicit
|
|
464
|
+
border property - reported directly: admonition in a table "does not have the dark
|
|
465
|
+
left border like it normally does". `.admonitionblock` is a plain `<div>`, with no
|
|
466
|
+
such ambiguity, in or out of a table. */
|
|
467
|
+
border-left: 3pt solid var(--brand-border-strong);
|
|
468
|
+
box-sizing: border-box;
|
|
469
|
+
max-width: 100%;
|
|
470
|
+
}
|
|
471
|
+
#pdf-export .admonitionblock table { width: 100%; border: none; }
|
|
307
472
|
/* Asciidoctor renders an admonition as a table (icon cell + content cell). Laid out as a
|
|
308
473
|
real table, a content table (or anything else with a footnote) inside it is a table
|
|
309
474
|
nested in a table, and Vivliostyle then never finishes paginating a floated footnote in
|
|
310
475
|
there - the build waits out the 180 s rendering timeout and produces no PDF at all.
|
|
311
476
|
Only the content cell is shown (the icon cell is hidden below), so lay the admonition
|
|
312
477
|
out as plain blocks instead. */
|
|
313
|
-
.admonitionblock > table,
|
|
314
|
-
.admonitionblock > table > tbody,
|
|
315
|
-
.admonitionblock > table > tbody > tr,
|
|
316
|
-
.admonitionblock td.content { display: block; }
|
|
317
|
-
.admonitionblock td.icon { display: none; }
|
|
318
|
-
.admonitionblock td.content {
|
|
319
|
-
border-left: 3pt solid var(--brand-border-strong);
|
|
478
|
+
#pdf-export .admonitionblock > table,
|
|
479
|
+
#pdf-export .admonitionblock > table > tbody,
|
|
480
|
+
#pdf-export .admonitionblock > table > tbody > tr,
|
|
481
|
+
#pdf-export .admonitionblock td.content { display: block; }
|
|
482
|
+
#pdf-export .admonitionblock td.icon { display: none; }
|
|
483
|
+
#pdf-export .admonitionblock td.content {
|
|
320
484
|
padding: 6pt 10pt;
|
|
321
485
|
background: var(--brand-bg-strong);
|
|
486
|
+
/* An admonition nested inside a table cell (Asciidoctor's `a|` cell syntax - reported
|
|
487
|
+
directly: an admonition "overlapping the edge of the table") renders its padding
|
|
488
|
+
added on top of the cell's own already-resolved width rather than inside it, pushing
|
|
489
|
+
the box past the table's own right edge - this renderer's table-cell layout doesn't
|
|
490
|
+
carry the real site.css's own `box-sizing: border-box` reset (confirmed present,
|
|
491
|
+
`html{box-sizing:border-box}` + `*,::before,::after{box-sizing:inherit}`) through
|
|
492
|
+
correctly once `td.content` is forced to `display: block` above (no longer a real
|
|
493
|
+
table-cell Vivliostyle's own table layout algorithm sizes the normal way).
|
|
494
|
+
Re-asserting both directly on the one box that actually has padding keeps it within
|
|
495
|
+
whatever width its container (a real table-cell, not touched here, or a plain page
|
|
496
|
+
column otherwise) actually resolved to. */
|
|
497
|
+
box-sizing: border-box;
|
|
498
|
+
max-width: 100%;
|
|
322
499
|
}
|
|
323
500
|
/* Style only the admonition's own title (a direct child of its content cell), not every
|
|
324
501
|
`.title` inside it. A table in an admonition has its caption as `caption.title`; with
|
|
325
502
|
these rules applied to it, the caption was made `display: block` (so it was laid out
|
|
326
503
|
after the header row instead of above it) and shown in capitals and the admonition
|
|
327
504
|
colour. */
|
|
328
|
-
.admonitionblock td.content > .title {
|
|
505
|
+
#pdf-export .admonitionblock td.content > .title {
|
|
329
506
|
font-weight: 700;
|
|
330
507
|
text-transform: uppercase;
|
|
331
508
|
font-size: 8.5pt;
|
|
@@ -334,25 +511,60 @@ tr { break-inside: avoid; }
|
|
|
334
511
|
display: block;
|
|
335
512
|
margin-bottom: 3pt;
|
|
336
513
|
}
|
|
337
|
-
.admonitionblock.warning
|
|
338
|
-
.admonitionblock.caution
|
|
514
|
+
#pdf-export .admonitionblock.warning,
|
|
515
|
+
#pdf-export .admonitionblock.caution {
|
|
339
516
|
border-left-color: var(--brand-warning);
|
|
517
|
+
}
|
|
518
|
+
#pdf-export .admonitionblock.warning td.content,
|
|
519
|
+
#pdf-export .admonitionblock.caution td.content {
|
|
340
520
|
background: var(--brand-warning-bg);
|
|
341
521
|
}
|
|
342
|
-
.admonitionblock.warning td.content > .title,
|
|
343
|
-
.admonitionblock.caution td.content > .title { color: var(--brand-warning); }
|
|
344
|
-
.admonitionblock.important
|
|
345
|
-
|
|
522
|
+
#pdf-export .admonitionblock.warning td.content > .title,
|
|
523
|
+
#pdf-export .admonitionblock.caution td.content > .title { color: var(--brand-warning); }
|
|
524
|
+
#pdf-export .admonitionblock.important { border-left-color: var(--brand-danger); }
|
|
525
|
+
#pdf-export .admonitionblock.important td.content {
|
|
346
526
|
background: var(--brand-danger-bg);
|
|
347
527
|
}
|
|
348
|
-
.admonitionblock.important td.content > .title { color: var(--brand-danger); }
|
|
349
|
-
.admonitionblock.note
|
|
350
|
-
.admonitionblock.
|
|
351
|
-
border-left-color: var(--brand-primary);
|
|
528
|
+
#pdf-export .admonitionblock.important td.content > .title { color: var(--brand-danger); }
|
|
529
|
+
#pdf-export .admonitionblock.note { border-left-color: var(--brand-primary); }
|
|
530
|
+
#pdf-export .admonitionblock.note td.content {
|
|
352
531
|
background: var(--brand-primary-weak);
|
|
353
532
|
}
|
|
354
|
-
.admonitionblock.note td.content > .title
|
|
355
|
-
|
|
533
|
+
#pdf-export .admonitionblock.note td.content > .title { color: var(--brand-primary-strong); }
|
|
534
|
+
/* tip is its own colour (green/success) on the real site, not a reuse of note's blue -
|
|
535
|
+
reported directly: "there's a tip admon that is green in the old pdf but blue in the
|
|
536
|
+
new one". */
|
|
537
|
+
#pdf-export .admonitionblock.tip { border-left-color: var(--brand-success-border); }
|
|
538
|
+
#pdf-export .admonitionblock.tip td.content {
|
|
539
|
+
background: var(--brand-success-bg);
|
|
540
|
+
}
|
|
541
|
+
#pdf-export .admonitionblock.tip td.content > .title { color: var(--brand-success); }
|
|
542
|
+
|
|
543
|
+
/* quoteblocks - includes a page's own [abstract]/{description} block (every page
|
|
544
|
+
authors `[abstract]\n{description}` right after its own title), which Asciidoctor
|
|
545
|
+
renders as a plain, unstyled quoteblock - this theme never styled quoteblocks at all,
|
|
546
|
+
so it rendered as nothing but the renderer's own default blockquote indent, no visual
|
|
547
|
+
distinction from body text. Styled as a neutral callout box, same visual language as a
|
|
548
|
+
plain (non-colored) admonition above, matching how the real site styles this exact
|
|
549
|
+
block (#preamble .abstract) as a distinct box rather than a plain paragraph. */
|
|
550
|
+
.quoteblock { break-inside: avoid-page; margin: 1em 0; }
|
|
551
|
+
.quoteblock blockquote {
|
|
552
|
+
margin: 0;
|
|
553
|
+
border-left: 3pt solid var(--brand-border-strong);
|
|
554
|
+
padding: 8pt 12pt;
|
|
555
|
+
background: var(--brand-bg-strong);
|
|
556
|
+
font-style: italic;
|
|
557
|
+
color: var(--brand-text-weak);
|
|
558
|
+
}
|
|
559
|
+
.quoteblock blockquote .paragraph:last-child { margin-bottom: 0; }
|
|
560
|
+
.quoteblock .attribution {
|
|
561
|
+
margin-top: 6pt;
|
|
562
|
+
font-size: 9.5pt;
|
|
563
|
+
font-style: normal;
|
|
564
|
+
color: var(--brand-text-weaker);
|
|
565
|
+
text-align: right;
|
|
566
|
+
}
|
|
567
|
+
.quoteblock .attribution cite { font-style: italic; }
|
|
356
568
|
|
|
357
569
|
/* lists */
|
|
358
570
|
.ulist, .olist, .dlist { margin: 0.5em 0; }
|
package/scripts/convert.js
CHANGED
|
@@ -9,6 +9,7 @@
|
|
|
9
9
|
const { spawn } = require('node:child_process')
|
|
10
10
|
const fs = require('node:fs')
|
|
11
11
|
const path = require('node:path')
|
|
12
|
+
const os = require('node:os')
|
|
12
13
|
|
|
13
14
|
// asciidoctor-pdf needs @asciidoctor/core 4.x while Antora needs 2.x, and it
|
|
14
15
|
// doesn't declare @asciidoctor/core as its own dependency (only a peerDep on
|
|
@@ -26,13 +27,15 @@ const path = require('node:path')
|
|
|
26
27
|
// through vendor/'s node_modules to the consumer's normal install, since
|
|
27
28
|
// those have no such conflict and should stay deduped normally.
|
|
28
29
|
const RENDERER = path.join(__dirname, '../vendor/node_modules/asciidoctor-pdf/bin/asciidoctor-web-pdf')
|
|
29
|
-
const
|
|
30
|
+
const PRINT_CSS = path.join(__dirname, '../pdf-theme/print.css')
|
|
30
31
|
const ROLES_LABELS_POSTPROCESSOR = path.join(__dirname, '../vendor/extensions/roles-labels-postprocessor.js')
|
|
31
32
|
const REMOTE_INCLUDE_ADAPTER = path.join(__dirname, '../vendor/extensions/remote-include-adapter.js')
|
|
32
33
|
const MACROS_ADAPTER = path.join(__dirname, '../vendor/extensions/macros-adapter.js')
|
|
33
34
|
const MATHJAX_ADAPTER = path.join(__dirname, '../vendor/extensions/mathjax-adapter.js')
|
|
34
35
|
const COLOPHON_POSTPROCESSOR = path.join(__dirname, '../vendor/extensions/colophon-postprocessor.js')
|
|
35
36
|
const ABSOLUTE_LINKS_POSTPROCESSOR = path.join(__dirname, '../vendor/extensions/absolute-links-postprocessor.js')
|
|
37
|
+
const DOC_WRAPPER_POSTPROCESSOR = path.join(__dirname, '../vendor/extensions/doc-wrapper-postprocessor.js')
|
|
38
|
+
const CYPHER_LANGUAGE_ADAPTER = path.join(__dirname, '../vendor/extensions/cypher-language-adapter.js')
|
|
36
39
|
|
|
37
40
|
// Unlike the extensions above, `@djencks/asciidoctor-mathjax` isn't a
|
|
38
41
|
// dependency of this package - it's an opt-in feature a docset adds itself
|
|
@@ -118,6 +121,89 @@ function dedupeGlossary (adoc) {
|
|
|
118
121
|
// needs a dedicated rule in print.css.
|
|
119
122
|
const LICENSE_PAGE = fs.readFileSync(path.join(__dirname, '../pages/license.adoc'), 'utf8')
|
|
120
123
|
|
|
124
|
+
// Fetched fresh at build time rather than vendored, so it can never drift from what
|
|
125
|
+
// the live site actually looks like (see the print theme's own top comment for why
|
|
126
|
+
// this pipeline reuses it at all) - the tradeoff is a new network dependency at build
|
|
127
|
+
// time, consistent with this pipeline's existing ones (npm installs, the HTML build's
|
|
128
|
+
// own UI bundle fetch). Same base DOCS_PUBLISH_URL as absolute-links-postprocessor.js's
|
|
129
|
+
// own rewrite prefix (see linkPrefix() below), so this always matches whichever
|
|
130
|
+
// environment's real site this PDF is standing in for - dev sandbox vs prod have
|
|
131
|
+
// completely different site.css content (different nav, different feature flags), not
|
|
132
|
+
// just a different URL for the "same" file.
|
|
133
|
+
async function fetchRealSiteCss () {
|
|
134
|
+
const base = (process.env.DOCS_PUBLISH_URL || 'https://neo4j.com/docs').replace(/\/$/, '')
|
|
135
|
+
const url = `${base}/assets/css/site.css`
|
|
136
|
+
const res = await fetch(url)
|
|
137
|
+
if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${url}`)
|
|
138
|
+
return res.text()
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
// The real site's own body copy and headings are all set in Public Sans (see real
|
|
142
|
+
// site.css's own font-family rules) - but, unlike Roboto Mono (vendored as local font
|
|
143
|
+
// files - see print.css's own @font-face rules) or every other font real site.css
|
|
144
|
+
// references (Roboto Mono, FontAwesome, Syne Neo - all declared via their own @font-face
|
|
145
|
+
// with real font file URLs), Public Sans is never declared in site.css at all. The real
|
|
146
|
+
// HTML page loads it from a separate <link> Antora's own template adds to <head>
|
|
147
|
+
// (fonts.googleapis.com/css2?family=Public+Sans...), which this pipeline has no
|
|
148
|
+
// equivalent of - nothing here ever fetches that second stylesheet, so Public Sans was
|
|
149
|
+
// never actually available to any PDF this pipeline has built with real site.css, and
|
|
150
|
+
// every reference to it silently fell through to its own fallback stack (Helvetica/
|
|
151
|
+
// Arial), rendered at real site.css's own `font-weight:300` body default - reported
|
|
152
|
+
// directly as "we seem to have lost the main font" / "text is just thin" (a generic
|
|
153
|
+
// sans-serif has no true light weight to fall back to the way Public Sans does, so the
|
|
154
|
+
// renderer fakes a thinner line weight instead).
|
|
155
|
+
async function fetchGoogleFontCss () {
|
|
156
|
+
const url = 'https://fonts.googleapis.com/css2?family=Public+Sans:wght@300;400;500;600;700&display=swap'
|
|
157
|
+
const res = await fetch(url, {
|
|
158
|
+
headers: {
|
|
159
|
+
// Google's font CSS endpoint serves different @font-face formats depending on
|
|
160
|
+
// the requesting User-Agent (old EOT/TTF for legacy browsers, WOFF2 otherwise) -
|
|
161
|
+
// the default fetch() UA here reads as neither to Google, and gets served a
|
|
162
|
+
// very old format Chromium (what this renderer actually uses) has no use for. A
|
|
163
|
+
// plain desktop Chrome UA string is enough to get the modern WOFF2 response.
|
|
164
|
+
'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36',
|
|
165
|
+
},
|
|
166
|
+
})
|
|
167
|
+
if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${url}`)
|
|
168
|
+
return res.text()
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
// Written into print.css's own directory, not a generic temp dir - print.css's own
|
|
172
|
+
// font/logo `url(...)` references are relative to wherever the stylesheet file itself
|
|
173
|
+
// ends up (see its own top comment), so moving the combined file elsewhere would break
|
|
174
|
+
// them. Real site.css's own url()s are already absolute (served from a CDN), so they're
|
|
175
|
+
// unaffected either way. Named per-process so two concurrent builds sharing this same
|
|
176
|
+
// install (unusual, but not impossible) can't clobber each other's file mid-write.
|
|
177
|
+
async function buildStylesheet () {
|
|
178
|
+
const ownCss = fs.readFileSync(PRINT_CSS, 'utf8')
|
|
179
|
+
let realCss
|
|
180
|
+
try {
|
|
181
|
+
realCss = await fetchRealSiteCss()
|
|
182
|
+
} catch (err) {
|
|
183
|
+
// A docset's own content is still perfectly buildable without the real site's
|
|
184
|
+
// styling - degrade to this package's own (much thinner) print-only rules rather
|
|
185
|
+
// than failing the whole PDF over a transient network blip, the same tradeoff
|
|
186
|
+
// in-document `link:` targets failing to resolve would get in a live HTML build.
|
|
187
|
+
console.error(`::warning::Could not fetch the real site.css (${err.message}) - falling back to this package's own print-only styles, which cover far less (no admonition/label/table/example colors, etc.)`)
|
|
188
|
+
realCss = ''
|
|
189
|
+
}
|
|
190
|
+
let fontCss = ''
|
|
191
|
+
try {
|
|
192
|
+
fontCss = await fetchGoogleFontCss()
|
|
193
|
+
} catch (err) {
|
|
194
|
+
// Same degrade-gracefully tradeoff as site.css above - Public Sans not loading
|
|
195
|
+
// falls back to real site.css's own fallback stack (Helvetica/Arial), not a broken
|
|
196
|
+
// build.
|
|
197
|
+
console.error(`::warning::Could not fetch the Public Sans font CSS (${err.message}) - falling back to real site.css's own fallback font stack`)
|
|
198
|
+
}
|
|
199
|
+
const combined = realCss
|
|
200
|
+
? `/* ---- Public Sans (fetched at build time - see fetchGoogleFontCss's own comment) ---- */\n${fontCss}\n\n/* ---- real site.css (fetched at build time) ---- */\n${realCss}\n\n/* ---- print.css (paged-media overrides) ---- */\n${ownCss}`
|
|
201
|
+
: ownCss
|
|
202
|
+
const outPath = path.join(path.dirname(PRINT_CSS), `.combined-stylesheet.${process.pid}.css`)
|
|
203
|
+
fs.writeFileSync(outPath, combined)
|
|
204
|
+
return outPath
|
|
205
|
+
}
|
|
206
|
+
|
|
121
207
|
function readStdin () {
|
|
122
208
|
const chunks = []
|
|
123
209
|
return new Promise((resolve, reject) => {
|
|
@@ -171,49 +257,68 @@ function linkPrefix () {
|
|
|
171
257
|
return null
|
|
172
258
|
}
|
|
173
259
|
}
|
|
174
|
-
// roles-labels-postprocessor.js
|
|
175
|
-
// behavior of their own (see those
|
|
176
|
-
// remote-include-adapter.js wrap the real
|
|
177
|
-
// added here, __dirname-computed, for the
|
|
178
|
-
// above. (table-footnotes has no equivalent
|
|
179
|
-
// see the print theme's own comment - already
|
|
180
|
-
// page its table lands on, natively, so
|
|
181
|
-
// to move.)
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
//
|
|
194
|
-
//
|
|
195
|
-
//
|
|
196
|
-
//
|
|
197
|
-
//
|
|
198
|
-
|
|
199
|
-
//
|
|
200
|
-
//
|
|
201
|
-
//
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
260
|
+
// roles-labels-postprocessor.js, colophon-postprocessor.js and
|
|
261
|
+
// doc-wrapper-postprocessor.js port/add behavior of their own (see those
|
|
262
|
+
// files); macros-adapter.js and remote-include-adapter.js wrap the real
|
|
263
|
+
// @neo4j-documentation packages - added here, __dirname-computed, for the
|
|
264
|
+
// same reason as the stylesheet above. (table-footnotes has no equivalent
|
|
265
|
+
// here: CSS `float: footnote` - see the print theme's own comment - already
|
|
266
|
+
// places a footnote on whatever page its table lands on, natively, so
|
|
267
|
+
// there's nothing for a postprocessor to move.)
|
|
268
|
+
Promise.all([buildStylesheet(), readStdin()]).then(([stylesheet, adoc]) => {
|
|
269
|
+
const extraArgs = [
|
|
270
|
+
'-a', `stylesheet=${stylesheet}`,
|
|
271
|
+
// Without this, asciidoctor-web-pdf never actually colors a code block -
|
|
272
|
+
// Antora's own template still adds class="language-x hljs" to every <code>
|
|
273
|
+
// regardless, since that's also the hook the real HTML site's client-side
|
|
274
|
+
// highlight.js looks for, but nothing in a static PDF ever runs that script.
|
|
275
|
+
// asciidoctor-web-pdf bundles its own server-side highlight.js adapter
|
|
276
|
+
// (registered under this exact name - see its own syntax-highlighter.js)
|
|
277
|
+
// that runs highlight.js in Node during conversion instead, embedding real
|
|
278
|
+
// colored spans directly in the HTML before Vivliostyle ever sees it - this
|
|
279
|
+
// pipeline has never turned it on, so no PDF it has ever produced has had
|
|
280
|
+
// real syntax highlighting, confirmed directly: plain monochrome code in
|
|
281
|
+
// every rebuild tried, with or without this package's own recent changes.
|
|
282
|
+
// Token *colors* (the `.hljs-*` rules) come from the real site.css in the
|
|
283
|
+
// combined stylesheet above, not this adapter's own bundled default theme.
|
|
284
|
+
'-a', 'source-highlighter=highlightjs',
|
|
285
|
+
// Must load before any document content is actually highlighted (asciidoctor-web-pdf
|
|
286
|
+
// loads every `--extension` up front, before conversion starts, so position in this
|
|
287
|
+
// list doesn't matter beyond that) - see cypher-language-adapter.js's own comment.
|
|
288
|
+
'--extension', CYPHER_LANGUAGE_ADAPTER,
|
|
289
|
+
'--extension', ROLES_LABELS_POSTPROCESSOR,
|
|
290
|
+
'--extension', REMOTE_INCLUDE_ADAPTER,
|
|
291
|
+
'--extension', MACROS_ADAPTER,
|
|
292
|
+
'--extension', COLOPHON_POSTPROCESSOR,
|
|
293
|
+
'--extension', ABSOLUTE_LINKS_POSTPROCESSOR,
|
|
294
|
+
'--extension', DOC_WRAPPER_POSTPROCESSOR,
|
|
295
|
+
]
|
|
296
|
+
const prefix = linkPrefix()
|
|
297
|
+
if (prefix) extraArgs.push('-a', `absolute-link-prefix=${prefix}`)
|
|
298
|
+
if (mathjaxAvailable()) extraArgs.push('--extension', MATHJAX_ADAPTER)
|
|
299
|
+
// Reading from stdin (this is piped the merged .adoc, not a real file - see
|
|
300
|
+
// below), asciidoctor-web-pdf invents a fictive input path rooted at
|
|
301
|
+
// `--base-dir`/`-B` if given, else its own cwd (lib/cli.js's
|
|
302
|
+
// _convertFromStdin), and writes its temporary intermediate HTML file next
|
|
303
|
+
// to THAT path (lib/converter.js's getTemporaryHtmlFile), not next to the
|
|
304
|
+
// real docdir the assembler passes via `-a docdir=...`. Without `-B`, that
|
|
305
|
+
// temp HTML ends up sitting in whatever directory this script itself was
|
|
306
|
+
// invoked from (the docset's own root, since that's antora's cwd) - one or
|
|
307
|
+
// more levels away from `-a docdir`/`-a imagesoutdir`. Every image target,
|
|
308
|
+
// resolved correctly as relative to the real docdir (e.g. `../_images/
|
|
309
|
+
// foo.png`), then resolves relative to the WRONG directory when the
|
|
310
|
+
// browser loads that temp HTML via file://, so every image in the PDF is
|
|
311
|
+
// silently broken. Passing the same docdir here as `-B` puts the temp HTML
|
|
312
|
+
// file where the image paths actually expect it to be.
|
|
313
|
+
const docdirIdx = args.findIndex((arg) => arg.startsWith('docdir='))
|
|
314
|
+
if (docdirIdx > 0 && args[docdirIdx - 1] === '-a') {
|
|
315
|
+
extraArgs.push('-B', args[docdirIdx].slice('docdir='.length))
|
|
316
|
+
}
|
|
317
|
+
const finalArgs =
|
|
318
|
+
stdinMarkerIdx === -1
|
|
319
|
+
? [...args, ...extraArgs]
|
|
320
|
+
: [...args.slice(0, stdinMarkerIdx), ...extraArgs, ...args.slice(stdinMarkerIdx)]
|
|
215
321
|
|
|
216
|
-
readStdin().then((adoc) => {
|
|
217
322
|
const child = spawn(RENDERER, finalArgs, {
|
|
218
323
|
stdio: ['pipe', 'inherit', 'inherit'],
|
|
219
324
|
env: { ...PUPPETEER_TIMEOUT_ENV, ...process.env },
|
|
@@ -222,6 +327,9 @@ readStdin().then((adoc) => {
|
|
|
222
327
|
console.error(err)
|
|
223
328
|
process.exit(1)
|
|
224
329
|
})
|
|
225
|
-
child.on('close', (status) =>
|
|
330
|
+
child.on('close', (status) => {
|
|
331
|
+
fs.rmSync(stylesheet, { force: true })
|
|
332
|
+
process.exit(status ?? 1)
|
|
333
|
+
})
|
|
226
334
|
child.stdin.end(dedupeGlossary(adoc).trimEnd() + '\n\n' + LICENSE_PAGE)
|
|
227
335
|
})
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
// asciidoctor-pdf's own highlight.js-based syntax highlighter (see its own
|
|
4
|
+
// syntax-highlighter.js - `-a source-highlighter=highlightjs` in convert.js turns it on)
|
|
5
|
+
// only colors a `[source,cypher]` block correctly if `hljs.getLanguage('cypher')` returns
|
|
6
|
+
// a real grammar; when it doesn't, that adapter's own fallback (`hljs.highlightAuto`)
|
|
7
|
+
// kicks in instead, which guesses the "best match" language per block from whichever
|
|
8
|
+
// languages stock highlight.js happens to have bundled - none of which are Cypher - and
|
|
9
|
+
// gives wildly inconsistent, mostly-wrong results block to block (reported directly:
|
|
10
|
+
// "no highlighting of any kind except 'company' and 3", immediately followed by a
|
|
11
|
+
// different block with full red/blue/orange/green from a lucky guess). Stock
|
|
12
|
+
// highlight.js has never shipped a Cypher grammar at all, so this was never going to
|
|
13
|
+
// self-resolve.
|
|
14
|
+
//
|
|
15
|
+
// The real HTML site has exactly this same problem and solves it the same way: it
|
|
16
|
+
// bundles its own highlight.js build (assets/js/vendor/highlight.js) with the
|
|
17
|
+
// community `highlightjs-cypher` grammar (github.com/highlightjs/highlightjs-cypher)
|
|
18
|
+
// registered under the name "cypher" - confirmed directly by fetching that bundle and
|
|
19
|
+
// finding this exact grammar's own keyword list inside it, byte for byte. Rather than
|
|
20
|
+
// re-deriving Cypher's grammar by hand (and inevitably drifting from what the real site
|
|
21
|
+
// actually renders, the same trap this theme's own hand-rolled CSS fell into before the
|
|
22
|
+
// real-site.css-reuse rewrite - see print.css's own top comment), vendor-languages/
|
|
23
|
+
// cypher.js is a verbatim copy of that same package, registered here against this
|
|
24
|
+
// renderer's own highlight.js instance for the same result.
|
|
25
|
+
//
|
|
26
|
+
// This can't just be *fetched* at build time the way site.css/Public Sans are (see
|
|
27
|
+
// convert.js's own fetchRealSiteCss/fetchGoogleFontCss) - the real bundle is a ~900KB
|
|
28
|
+
// minified, self-contained IIFE assigning a browser global, not a CommonJS module
|
|
29
|
+
// `require()` can load, and it bundles highlight.js's own engine too, which would mean
|
|
30
|
+
// running two separate highlight.js instances/registries in the same process rather than
|
|
31
|
+
// registering one more language against the single instance asciidoctor-pdf's own
|
|
32
|
+
// adapter already uses. A vendored copy of just the one grammar module avoids both
|
|
33
|
+
// problems.
|
|
34
|
+
//
|
|
35
|
+
// Must `require('highlight.js')` from somewhere inside vendor/ (not the consuming
|
|
36
|
+
// docset's own node_modules) to resolve the exact same singleton instance
|
|
37
|
+
// asciidoctor-pdf's own ServerHighlightJsAdapter calls `hljs.highlight()`/
|
|
38
|
+
// `hljs.getLanguage()` against - same reasoning as doc-wrapper-postprocessor.js's own
|
|
39
|
+
// `require('asciidoctor')` needing the vendor-local copy (see convert.js's top comment).
|
|
40
|
+
const hljs = require('highlight.js')
|
|
41
|
+
const cypher = require('../languages/cypher')
|
|
42
|
+
|
|
43
|
+
if (!hljs.getLanguage('cypher')) hljs.registerLanguage('cypher', cypher)
|
|
44
|
+
|
|
45
|
+
// cypher-shell wraps a `neo4j> `-prompted line as `meta`, then highlights everything
|
|
46
|
+
// after it as Cypher via subLanguage - registered by the real site alongside "cypher"
|
|
47
|
+
// itself (same bundle, same confirmation) for any `[source,cypher-shell]` block showing
|
|
48
|
+
// a REPL session rather than a bare query. Small enough to inline rather than vendor as
|
|
49
|
+
// its own file - copied verbatim from the real site's own bundle.
|
|
50
|
+
if (!hljs.getLanguage('cypher-shell')) {
|
|
51
|
+
hljs.registerLanguage('cypher-shell', function () {
|
|
52
|
+
return {
|
|
53
|
+
contains: [{
|
|
54
|
+
className: 'meta',
|
|
55
|
+
begin: '^\\s{0,3}[neo4j]',
|
|
56
|
+
end: '>',
|
|
57
|
+
starts: { end: /[\n|;]/, subLanguage: 'cypher' },
|
|
58
|
+
}],
|
|
59
|
+
}
|
|
60
|
+
})
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
// No Asciidoctor extension API hook needed - the registration above is this module's
|
|
64
|
+
// entire job, done as a side effect of being `require()`'d via `--extension` (the only
|
|
65
|
+
// way to run code inside asciidoctor-web-pdf's own process - see convert.js's own
|
|
66
|
+
// comment on why real-CSS/font fetches, which run in convert.js's own process instead,
|
|
67
|
+
// can't reach this far). Asciidoctor's own extension loader still expects a `register`
|
|
68
|
+
// function to exist on every `--extension` module, even an unused one.
|
|
69
|
+
module.exports.register = function () {}
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
// The real site's own site.css (linked wholesale - see convert.js's own comment on
|
|
4
|
+
// why) scopes content rules two different ways, neither of which plain Asciidoctor's
|
|
5
|
+
// html5 backend output (used here) has on its own:
|
|
6
|
+
// - `.doc ...` - Antora's own page template wraps real HTML output in
|
|
7
|
+
// `<article class="doc">`, a child of <body>, not <body> itself.
|
|
8
|
+
// - `body.docs ...` - a handful of rules (e.g. the page's own [abstract]/
|
|
9
|
+
// {description} block, body.docs #preamble .abstract) are instead scoped off a
|
|
10
|
+
// `docs` class the real <body> itself carries (alongside "article", which plain
|
|
11
|
+
// Asciidoctor's own <body class="article"> already has for free).
|
|
12
|
+
// Asciidoctor's html5 backend has no equivalent of Antora's nested <article> at all -
|
|
13
|
+
// just <body class="article"><div id="header">...</div><div id="content">...all
|
|
14
|
+
// sections...</div><div id="footer">...</div></body> - so rather than introduce a new
|
|
15
|
+
// wrapper element, "doc" is added directly to the existing #content div, which scopes
|
|
16
|
+
// identically for any `.doc <selector>` rule.
|
|
17
|
+
//
|
|
18
|
+
// Real site.css's own content selectors are almost all scoped `.doc <thing>` (two
|
|
19
|
+
// classes) or deeper (`.doc table.tableblock>:not(thead) th`, `.doc h2:not(.discrete)`,
|
|
20
|
+
// ...) - print.css's own rules for the same elements (h2, table.tableblock, .imageblock,
|
|
21
|
+
// .admonitionblock, ...) are plain, single-class/element selectors, which lose that
|
|
22
|
+
// specificity fight regardless of which file loads second (reported directly: headings
|
|
23
|
+
// too small, tables with no borders/stripes, malformed admonition/code-block corners -
|
|
24
|
+
// each is print.css's own intended override silently losing to real site.css's richer
|
|
25
|
+
// selector for that same property). `#pdf-export` on <body> gives print.css's own
|
|
26
|
+
// selectors (written as `#pdf-export <existing selector>`) an ID in their specificity,
|
|
27
|
+
// which beats any number of real site.css's classes outright, rather than fixing these
|
|
28
|
+
// one at a time as each is found.
|
|
29
|
+
const { Postprocessor } = require('asciidoctor')
|
|
30
|
+
|
|
31
|
+
class DocWrapperPostprocessor extends Postprocessor {
|
|
32
|
+
process (document, output) {
|
|
33
|
+
return output
|
|
34
|
+
.replace(/<body\b/, '<body id="pdf-export"')
|
|
35
|
+
.replace(/(<body\b[^>]*\bclass=")/, '$1docs ')
|
|
36
|
+
.replace(/(<div id="content"(?:\s+class="[^"]*")?)/, (match) =>
|
|
37
|
+
match.includes('class="')
|
|
38
|
+
? match.replace('class="', 'class="doc ')
|
|
39
|
+
: `${match} class="doc"`
|
|
40
|
+
)
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
module.exports.register = function (registry) {
|
|
45
|
+
registry.postprocessor(DocWrapperPostprocessor)
|
|
46
|
+
}
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Language: Cypher
|
|
3
|
+
* Contributors:
|
|
4
|
+
* Johannes Wienke <languitar@semipol.de>
|
|
5
|
+
* Gustavo Reis <gusbemacbe@gmail.com>
|
|
6
|
+
*
|
|
7
|
+
* Vendored verbatim (CC0-1.0, see this package's own LICENSE) from npm's
|
|
8
|
+
* highlightjs-cypher@1.2.0 (github.com/highlightjs/highlightjs-cypher) - this is the
|
|
9
|
+
* exact same grammar the real site itself registers as "cypher" with its own bundled
|
|
10
|
+
* highlight.js (confirmed directly: the real site's assets/js/vendor/highlight.js
|
|
11
|
+
* contains this file's own keyword list, byte for byte) - see
|
|
12
|
+
* cypher-language-adapter.js's own comment for why this PDF pipeline needs its own copy
|
|
13
|
+
* rather than inheriting the real site's registration some other way.
|
|
14
|
+
*/
|
|
15
|
+
module.exports = function (hljs)
|
|
16
|
+
{
|
|
17
|
+
return {
|
|
18
|
+
case_insensitive: true,
|
|
19
|
+
keywords:
|
|
20
|
+
{
|
|
21
|
+
keyword: 'as asc ascending and assert by call case collect commit constraint create csv cypher delete desc descending detach distinct drop else end ends explain fieldterminator for foreach from headers in index is join limit load match merge nodetach not on optional order periodic profile remove return scan set skip start starts then union unique unwind use using when where with yield',
|
|
22
|
+
literal: 'true false null',
|
|
23
|
+
$pattern: /(?<=^|\s)[a-zA-Z0-9_\.]+(?=$|\s)/ // allows to better exclude keywords-like matches to be highlighted when not acting as keywords
|
|
24
|
+
},
|
|
25
|
+
contains:
|
|
26
|
+
[
|
|
27
|
+
hljs.QUOTE_STRING_MODE,
|
|
28
|
+
hljs.APOS_STRING_MODE,
|
|
29
|
+
hljs.C_NUMBER_MODE,
|
|
30
|
+
{
|
|
31
|
+
className: 'string',
|
|
32
|
+
begin: '`',
|
|
33
|
+
end: '`',
|
|
34
|
+
illegal: '\\n',
|
|
35
|
+
contains: [hljs.BACKSLASH_ESCAPE]
|
|
36
|
+
},
|
|
37
|
+
{
|
|
38
|
+
className: 'type',
|
|
39
|
+
begin: /((-|>)?\s?\(|-\[)\w*:/,
|
|
40
|
+
excludeBegin: true,
|
|
41
|
+
end: '\\W',
|
|
42
|
+
excludeEnd: true,
|
|
43
|
+
},
|
|
44
|
+
{
|
|
45
|
+
className: 'functionCall',
|
|
46
|
+
begin: /(\s+|,)[a-zA-Z0-9_\.]+\(/,
|
|
47
|
+
end: /\)/,
|
|
48
|
+
keywords: {
|
|
49
|
+
built_in: 'all any exists isEmpty none single coalesce elementId endNode head id last length properties randomUUID size startNode timestamp toBoolean toBooleanOrNull toFloat toFloatOrNull toInteger toIntegerOrNull type valueType avg collect count max min percentileCont percentileDisc stDev stDevP sum extract filter keys labels nodes range reduce relationships reverse tail toBooleanList toFloatList toIntegerList toStringList abs ceil floor isNaN rand round sign e exp log log10 sqrt acos asin atan atan2 cos cot degrees haversin pi radians sin tan left ltrim replace reverse right rtrim split substring toLower toString toStringOrNull toUpper trim date datetime localdatetime localtime time duration duration duration duration duration point linenumber file graph db cdc char_length character_length'
|
|
50
|
+
}
|
|
51
|
+
},
|
|
52
|
+
hljs.C_BLOCK_COMMENT_MODE,
|
|
53
|
+
hljs.C_LINE_COMMENT_MODE,
|
|
54
|
+
{
|
|
55
|
+
begin: '//',
|
|
56
|
+
ends: '//',
|
|
57
|
+
}
|
|
58
|
+
]
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
|