Add asciidoctor-kroki to render Mermaid diagrams at build time (agent integration pages)

[jexp]

Summary

Mermaid diagrams on the agent-integration pages are currently baked into pre-encoded kroki.io image URLs at Markdown→AsciiDoc conversion time. This works, but it makes every diagram a third-party runtime dependency at page-view time and leaves the diagram source unreadable in the .adoc. Adding the asciidoctor-kroki extension with kroki-fetch-diagram would render diagrams at build time into local site assets instead.

Current state

The pages under genai-ecosystem/genai-frameworks/ are generated from Markdown READMEs in neo4j-labs/neo4j-agent-integrations by scripts/publish-to-labs.py. Mermaid fenced blocks are deflate+base64-encoded into a URL:

image::https://kroki.io/mermaid/svg/eNp1UE1LAzEQvfsrhjltkcWLRymse1VbLJ5CD9lmaiNpZkk...[Diagram,align="center"]

Neither developer.yml nor labs.yml registers a diagram extension today — only remote-include and macros — so this pre-encoding is what makes the diagrams work at all.

Pages currently relying on it (5):

Page	Source README
microsoft-foundry.adoc	microsoft-foundry/README.md
microsoft-agent-framework.adoc	microsoft-agent-framework/README.md
microsoft-agent-framework-multi-agent.adoc	microsoft-agent-framework/examples/multi-agent/README.md
datarobot.adoc	datarobot/README.md
microsoft-copilot-studio.adoc	microsoft-copilot-studio/README.md

Why change it

1. Runtime dependency on kroki.io. The reader's browser fetches each SVG from kroki.io on page load. If it is down, rate-limiting, or blocked by a corporate network, diagrams silently vanish from published docs.
2. Diagram source is not in the .adoc. The encoded blob is opaque — not reviewable in a PR diff, not greppable, not editable without re-running the converter.
3. No control over rendering. No theming, and the SVG is whatever kroki.io's current mermaid version produces, which can change under us without a docs change.

Proposed change

1. package.json — add to devDependencies:

"asciidoctor-kroki": "^0.18.1"

Important

Pin to the 0.18.x line — do not use latest. asciidoctor-kroki@1.0.1 declares peerDependencies: { "@asciidoctor/core": ">=4.0.0 <5.0.0" }, but Antora 3.1 resolves @asciidoctor/core: ~2.2. Only 0.18.1 (>=2.2 <4.0) is compatible with the current Antora version. This becomes upgradable when the repo moves to Antora 4.x.

2. developer.yml and labs.yml — both source labs-pages@publish, so both need it:

asciidoc:
  extensions:
  - ./extensions/remote-include/remote-include-processor
  - ./extensions/macros/macros
  - asciidoctor-kroki          # <-- add
  attributes:
    experimental: ''
    kroki-fetch-diagram: true  # <-- fetch at build time, no runtime dependency
    kroki-default-format: svg
    # kroki-server-url: https://kroki.io   # default; set to self-hosted if desired

3. Paired change in neo4j-agent-integrations (separate PR, I'll handle it): change the converter to emit real diagram blocks instead of pre-encoded URLs:

[mermaid,my-diagram,svg]
....
flowchart LR
    user["User"] --> agent["Copilot Studio agent"]
....

Sequencing

The two changes are not independent — [mermaid] blocks render as literal text if the extension isn't registered. Order:

1. Merge this docs-refresh change first (harmless on its own: no page uses [mermaid] blocks yet, so it's a no-op).
2. Then merge the converter change in neo4j-agent-integrations.

Rollback is symmetric: revert the converter change and the pre-encoded URLs come back.

Verification

npm install
npx antora --fetch developer.yml
# then confirm, for each of the 5 pages above:
#  - diagram <img> src is a LOCAL path, not https://kroki.io/...
#  - the SVG file exists in build/site/
#  - no "kroki" warnings in build output

Worth confirming during review: with kroki-fetch-diagram: true, the build machine needs outbound access to kroki.io at build time (it already needs network for npm install and Antora's content fetch). If that's unacceptable, the alternative is a self-hosted kroki via kroki-server-url.

Alternatives considered

Option	Verdict
Keep pre-encoded kroki URLs (status quo)	Works, zero build deps. Costs a page-view-time third-party dependency and unreviewable diagram source
asciidoctor-kroki + kroki-fetch-diagram (this proposal)	Build-time render, local assets, readable source. Costs one dev dependency + version pin
asciidoctor-diagram	Rejected — needs mermaid-cli and headless Chrome on the build machine
Client-side mermaid.js	Rejected — requires a change to the shared UI bundle, plus CSP considerations

---

Filed from work on the agent-integration publication pipeline. Happy to open the PR for both repos if this direction is agreed.