Custom AsciiDoc components

The classic asciidoctor-diagram/asciidoctor-kroki [type,target,format] positional form works alongside the named format= attribute already shown above — the second comma-separated value is a target (accepted but otherwise unused: this extension always inlines, never writes a named file to disk), the third is the format:

Any named attribute beyond the built-in set (target, width, height, format, role, title, caption, …) is a Kroki diagram-specific option, forwarded to Kroki as a Kroki-Diagram-Options-<key> HTTP header — exactly as the real asciidoctor-kroki extension forwards them. Structurizr’s view-key selects which view of a multi-view workspace to render:

Mermaid diagrams are themed to match this site automatically — square corners, black-on-white, body typography — via a %%{init: {…​}}%% directive this extension prepends to the diagram’s own source before it ever reaches Kroki, not via CSS. Write your own %%{init…​}%% as the diagram’s first line to opt out and take full control of Mermaid’s own theming instead. Every other diagram type’s font is still normalized via CSS (safe — a tool’s typeface choice carries no meaning). BPMN's own rounded task-box corners could not be un-rounded by any means found — bpmn-js hardcodes that radius; this is a real, currently-unfixed limitation, not an oversight.

The card framing a diagram follows this site’s own light/dark theme, same as any other card — but the diagram’s own canvas underneath it is always a fixed white, regardless of theme: diagram tools don’t agree on whether they draw a background at all (GraphViz bakes its own opaque white one; Mermaid and PlantUML bake none), so a fixed canvas is what makes every diagram read the same rather than depending on that inconsistency — and it means a diagram’s own colors never need inverting for dark mode, avoiding the distortion that would cause for anything genuinely colorful (a PlantUML skinparam palette, a Structurizr diagram’s own color-coded boxes, an Excalidraw scene).

[mermaid,format=png] (or any other diagram language and format Kroki’s own server accepts for it — see kroki-config.js’s `FORMAT_SUPPORT for the exact, live-verified matrix; it varies per type, not a blanket rule) renders a raster image instead of inline SVG:

Embedded as a plain <img> with a base64 data: URI — no extra file written, no extra HTTP request. Reach for this only when you actually need a raster image (an export, an email, a renderer that can’t handle inline SVG); the inline-SVG default stays sharper at every zoom level and lets a reader select/search the diagram’s own text, neither of which a raster format can do. Beyond png: jpeg (jpg also accepted), pdf (embedded as an <embed>, since a browser can’t display a PDF through <img>) and base64 all render the same way. An unsupported type/format combination, or a typo’d format= value, falls back to svg with a build warning, the same degrade-not-fail posture as an unknown kroki-diagram-types entry.

txt/atxt/utxt are different in kind, not just encoding — Kroki renders these as a literal ASCII-art-style text representation, not an image at all:

[bpmn] renders BPMN 2.0 XML (the same format bpmn.io and most process-modeling tools export). Like mermaid and excalidraw, it needs its own headless-Chrome companion container — the bundled kroki-compose.yml already includes one:

[excalidraw] renders an Excalidraw scene (the JSON a .excalidraw file, or excalidraw.com's own "Save to…​" export, contains). Unlike bpmn, this type does need its own companion — the bundled kroki-compose.yml includes an excalidraw service alongside mermaid for exactly that reason:

Any diagram — or a plain image:: block, which already gets this for free from Asciidoctor’s own role-to-class handling — marked role=zoom-in gets a click-to-zoom affordance: a zoom-in cursor and a subtle hover tint for a mouse, a small persistent badge for touch, and clicking/tapping opens a fullscreen overlay with a bigger view. Esc, the close icon, or clicking the backdrop all dismiss it — static, no pan/pinch-zoom, just a bigger still image: