Diagram engines (bake vs client) :: Antora Supplemental Docs

Antora itself does not force a diagram bake. The antora-supplemental / Facto stack treats two strategies as supported options (plus hybrid).

Packaged extensions (antora-diagram-engines)

Selectable monorepo (not a monolith): antora-supplemental/antora-diagram-engines.

Package Role

Package	Role
`@antora-supplemental/mermaid-client`	Asciidoctor client hosts + Antora UI inject. CDN-first Mermaid runtime (pinned jsDelivr); optional `cdn: false` + local script for air-gap. Light/dark re-render (no dual SVG forks).
`@antora-supplemental/diagram-lightbox`	Zoom / lightbox assets (chassis patterns).
`@antora-supplemental/diagram-engines`	Optional meta bundle wiring Mermaid client + lightbox defaults.

@antora-supplemental/mermaid-client

Asciidoctor client hosts + Antora UI inject. CDN-first Mermaid runtime (pinned jsDelivr); optional cdn: false + local script for air-gap. Light/dark re-render (no dual SVG forks).

@antora-supplemental/diagram-lightbox

Zoom / lightbox assets (chassis patterns).

@antora-supplemental/diagram-engines

Optional meta bundle wiring Mermaid client + lightbox defaults.

Mermaid + lightbox only (playbook sketch)

antora:
  extensions:
    - require: '@antora-supplemental/mermaid-client/antora'
      # cdn: 'https://cdn.jsdelivr.net/npm/[email protected]/dist/mermaid.min.js'  # default
      # cdn: false
      # localScript: 'js/vendor/mermaid.min.js'
    - require: '@antora-supplemental/diagram-lightbox'
asciidoc:
  extensions:
    - asciidoctor-kroki   # PlantUML / other bake formats
  attributes:
    mermaid-client: ''
    mermaid-client-mode: client
    kroki-fetch-diagram: true

PlantUML stays on Kroki (does not auto-retheme like Mermaid). DevCentr Themed SVG / bake pipeline remains live but unmaintained.

Option A — Bake SVG at build

Extension: asciidoctor-kroki with kroki-fetch-diagram: true.
Formats: Mermaid + PlantUML (and other Kroki types) become SVG during antora.
Theme: raw Kroki <img> is fixed-color. For dark-mode toggle without dual forks, post-process with @dev-centr/mermaid-svg-css-vars / plantuml-svg-css-vars into Themed SVG and serve [.themed-svg].
Dark-text WARN / borrow-from-light: see the DevCentr how-to (linked below).

When to use

Default for hubs, PlantUML, offline/print, and figures that must work with JS disabled.

Option B — Client render engines (Mermaid first)

Prefer @antora-supplemental/mermaid-client (CDN runtime + UI inject), or continue shipping hub supplemental site-mermaid.js + site-mermaid.css.
Leave Mermaid source in the HTML; SVG ids appear only after JS (DeepWiki-style).
Theme with Mermaid theme / themeVariables and CSS tokens — no dual checked-in SVG.
PlantUML-in-browser is harder and not shipped as a Facto default.

When to use

Mermaid that must follow light/dark without a Themed SVG generate step.

Hybrid

Keep Kroki for PlantUML (and baked Mermaid you want stable). For a client Mermaid figure on the same site, author a listing Kroki will not claim:

[.mermaid-client]
[source,text]

flowchart TD A[Client source] -→ B[SVG after JS]

Or + <pre class="mermaid">…</pre>. Hub site-mermaid.js collects .mermaid-client / pre.mermaid and re-runs on SoftNav.

Diagram zoom / lightbox

Chassis package: diagram-zoom.

Enable

Prefer @antora-supplemental/diagram-lightbox (injects site-diagram-lightbox.js/css), or copy chassis js/site-diagram-zoom.js and css/site-diagram-zoom.css into supplemental-ui/.
Link the stylesheet in head-meta.hbs; load the script after SoftNav in the footer partial.
No AsciiDoc role required — attaches to .doc .imageblock and client Mermaid hosts.

In-article: zoom in/out/reset + expand. Lightbox: drag-pan, wheel-zoom, Esc/close. Uses --adt-* tokens.

Canonical how-to

DevCentr authors: Antora diagram formats (Option A/B/hybrid steps, Kroki self-host, WARN policy, zoom).

Compose pack: facto-stack (Valentus stays lean; Kroki is Facto, not Valentus core).