Mermaid format not correctly Handled in Codex.

[madhava-sridhar]

Describe the bug

recently added page in Codex has mermaid format diagrams https://codex.elastic.dev/r/cp-hosted-team/components/firewall_architecture. Mermaid diagrams not correctly handled by codex .

Expected behavior

Mermaid diagrams should be correctly rendered by codex.

Steps to reproduce

NA

Tooling

• docs-builder
• migration tooling
• I'm not sure

[cotti]

AI triage

Automated investigation against the current codebase. A human still needs to confirm before any code change.

Original concern

A Codex page (/r/cp-hosted-team/components/firewall_architecture) contains Mermaid diagrams that Codex does not render correctly.

Findings

• src/Elastic.Markdown/Myst/CodeBlocks/EnhancedCodeBlockHtmlRenderer.cs:L137-L142 and :L316-L340 — Mermaid handling lives entirely in the shared Markdown renderer: a mermaid fenced block is emitted as <pre class="mermaid"> for client-side rendering. This path is identical for every build type (isolated docs, assembler, and Codex), so there is no Codex-specific Mermaid code.
• src/Elastic.Documentation.Site/Layout/_Head.cshtml:L24-L29 — for BuildType.Codex the only build-type branch is the CSS bundle (codex.css); main.js is loaded unconditionally (L29). styles.css:L22 imports markdown/mermaid.css and is also loaded for Codex. So Codex pages do ship the Mermaid JS and CSS.
• src/Elastic.Documentation.Site/Assets/main.ts:L104-L118 — initMermaid() runs on both DOMContentLoaded and htmx:load, i.e. it executes on Codex pages too.
• src/Elastic.Documentation.Site/Assets/mermaid.ts:L536 then :L561-L565 — diagrams are rendered by @theletterf/beautiful-mermaid (window.__mermaid.renderMermaid). On any render failure the catch block adds a mermaid-error class and keeps the raw Mermaid text. That fallback is the visible "not correctly handled" symptom.
• src/Elastic.Documentation.Site/package.json:L10 + :L122 — the renderer is @theletterf/beautiful-mermaid 0.1.5, a lightweight re-implementation (not full mermaid.js) copied to _static/mermaid.min.js. It supports only a subset of Mermaid syntax/diagram types, which is the most likely reason an architecture-style diagram fails.

Verdict

Needs stakeholder input

This does not appear to be a Codex bug. Codex reuses the exact same Mermaid pipeline (<pre class="mermaid"> + main.js/initMermaid + mermaid.css) as every other build, so a diagram that fails in Codex would fail the same way in an isolated/assembler build — the constraint is the client-side beautiful-mermaid 0.1.5 renderer's limited diagram support, not Codex. The repo history confirms this is a known sore spot: the renderer has been swapped repeatedly (#2586 → #2661/revert #2663 → #2720). I could not load the live codex.elastic.dev page to confirm the exact diagram syntax (it appears to be access-gated), so the precise failing construct is unverified. The proper fix is already in flight — see Proposal — but is not merged, so the issue still reproduces on main.

Proposal

This is an engineering decision rather than a contained quick fix:

• Engineering: PR #2838 ("Replace Beautiful Mermaid with Mermaider for server-side diagram rendering", commit bbfaaf5b, open, last updated 2026-06-02) replaces client-side beautiful-mermaid with server-side rendering, which would render arbitrary Mermaid syntax server-side and remove the dependency on the limited browser lib. Questions for a maintainer: (1) Is Replace Beautiful Mermaid with Mermaider for server-side diagram rendering #2838 the chosen direction and does it cover this firewall_architecture diagram? (2) If so, this issue can likely be closed by Replace Beautiful Mermaid with Mermaider for server-side diagram rendering #2838 — is there any Codex-only asset/path concern (e.g. _static/mermaid.min.js availability under /r/<repo>/...) that should be verified before then? (3) As an interim, should beautiful-mermaid be bumped/replaced, given the repeated churn?

Related issues

• Mermaid: Please add support for line breaks, other HTML #2632 (closed) — "Mermaid: Please add support for line breaks, other HTML": same root-cause family (gaps in the beautiful-mermaid renderer). Evidence of a prior decision on renderer limitations, not a duplicate.
• No open duplicate found.

Notes

• The repro likely depends on the specific diagram on the (access-gated) Codex page; a maintainer can confirm by reproducing the same fenced block in a normal docs-builder build.
• Suggested label outcome: route to engineering via ai:eng-question (fix is an architectural renderer swap already tracked in Replace Beautiful Mermaid with Mermaider for server-side diagram rendering #2838, not a one- or two-file change).