@neo4j-antora/pdf-generator 0.1.8 → 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 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` - print stylesheet targeting Asciidoctor's standard
69
- HTML5 backend class names (`sect1`, `admonitionblock`, `listingblock`,
70
- `tableblock`, `label`, ...), using colour/font tokens copied from
71
- `docs-ui`'s `src/css/vars.css` (itself resolving to raw Needle design
72
- system tokens in `@neo4j-ndl/base`'s `tokens/css/tokens.css`) and
73
- `docs-ui`'s `src/css/labels.css`. Not a fork of the real site CSS wholesale
74
- - Asciidoctor's default HTML5 output doesn't have Antora's `.doc` wrapper
75
- markup most of the site CSS's selectors are written against, so most of
76
- it wouldn't match anything here anyway. Fonts are vendored into
77
- `pdf-theme/assets/fonts/` rather than read from a docset's own HTML
78
- build output, so this theme has no dependency on that build having
79
- already run.
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` label colours are hand-resolved from
156
- `docs-ui`'s source files, not read from them live - if the Needle tokens or
157
- `docs-ui`'s `vars.css`/`labels.css` change, this drifts until someone
158
- notices and re-syncs it by hand.
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.8",
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": {
@@ -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). Reuses brand tokens read from the real site.css
4
- (build/site/assets/css/site.css) rather than forking that file, since
5
- Asciidoctor's HTML5 backend (used by asciidoctor-web-pdf) does not produce
6
- Antora's `.doc` wrapper markup.
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
- h1, h2, h3, h4, h5, h6 {
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
- break-inside: avoid-page;
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 pre {
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
- table.tableblock thead th {
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
- tr { break-inside: avoid; }
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
- .admonitionblock table { width: 100%; border: none; }
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,34 @@ tr { break-inside: avoid; }
334
511
  display: block;
335
512
  margin-bottom: 3pt;
336
513
  }
337
- .admonitionblock.warning td.content,
338
- .admonitionblock.caution td.content {
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 td.content {
345
- border-left-color: var(--brand-danger);
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 td.content,
350
- .admonitionblock.tip td.content {
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
- .admonitionblock.tip td.content > .title { color: var(--brand-primary-strong); }
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); }
356
542
 
357
543
  /* quoteblocks - includes a page's own [abstract]/{description} block (every page
358
544
  authors `[abstract]\n{description}` right after its own title), which Asciidoctor
@@ -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 STYLESHEET = path.join(__dirname, '../pdf-theme/print.css')
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 and colophon-postprocessor.js port/add
175
- // behavior of their own (see those files); macros-adapter.js and
176
- // remote-include-adapter.js wrap the real @neo4j-documentation packages -
177
- // added here, __dirname-computed, for the same reason as the stylesheet
178
- // above. (table-footnotes has no equivalent here: CSS `float: footnote` -
179
- // see the print theme's own comment - already places a footnote on whatever
180
- // page its table lands on, natively, so there's nothing for a postprocessor
181
- // to move.)
182
- const extraArgs = [
183
- '-a', `stylesheet=${STYLESHEET}`,
184
- '--extension', ROLES_LABELS_POSTPROCESSOR,
185
- '--extension', REMOTE_INCLUDE_ADAPTER,
186
- '--extension', MACROS_ADAPTER,
187
- '--extension', COLOPHON_POSTPROCESSOR,
188
- '--extension', ABSOLUTE_LINKS_POSTPROCESSOR,
189
- ]
190
- const prefix = linkPrefix()
191
- if (prefix) extraArgs.push('-a', `absolute-link-prefix=${prefix}`)
192
- if (mathjaxAvailable()) extraArgs.push('--extension', MATHJAX_ADAPTER)
193
- // Reading from stdin (this is piped the merged .adoc, not a real file - see
194
- // below), asciidoctor-web-pdf invents a fictive input path rooted at
195
- // `--base-dir`/`-B` if given, else its own cwd (lib/cli.js's
196
- // _convertFromStdin), and writes its temporary intermediate HTML file next
197
- // to THAT path (lib/converter.js's getTemporaryHtmlFile), not next to the
198
- // real docdir the assembler passes via `-a docdir=...`. Without `-B`, that
199
- // temp HTML ends up sitting in whatever directory this script itself was
200
- // invoked from (the docset's own root, since that's antora's cwd) - one or
201
- // more levels away from `-a docdir`/`-a imagesoutdir`. Every image target,
202
- // resolved correctly as relative to the real docdir (e.g. `../_images/
203
- // foo.png`), then resolves relative to the WRONG directory when the
204
- // browser loads that temp HTML via file://, so every image in the PDF is
205
- // silently broken. Passing the same docdir here as `-B` puts the temp HTML
206
- // file where the image paths actually expect it to be.
207
- const docdirIdx = args.findIndex((arg) => arg.startsWith('docdir='))
208
- if (docdirIdx > 0 && args[docdirIdx - 1] === '-a') {
209
- extraArgs.push('-B', args[docdirIdx].slice('docdir='.length))
210
- }
211
- const finalArgs =
212
- stdinMarkerIdx === -1
213
- ? [...args, ...extraArgs]
214
- : [...args.slice(0, stdinMarkerIdx), ...extraArgs, ...args.slice(stdinMarkerIdx)]
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) => process.exit(status ?? 1))
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
+