Problem
A Mermaid diagram that fails to parse does not fail the build. Hugo emits the fenced block, the browser's Mermaid runtime throws at render time, and the page ships with a blank space where the diagram should be. Nobody notices until a reader reports it.
That is exactly how the Gateway API traffic-path flowchart shipped broken: an edge label contained unquoted parentheses (|issues Certificate(s)|), which Mermaid's parser rejects, so the whole flowchart rendered as nothing. It was live in both the v1.5 and next snapshots until a user reported it.
Proposal
Add a CI job that extracts every ```mermaid fenced block under content/ and parses it — `mermaid-cli` (`mmdc`) in headless Chromium renders each one and exits non-zero on a parse error. Fail the build if any block does not render.
The check is cheap, needs no rendering fidelity judgement, and would have caught this defect at the point it was introduced rather than in production.
Problem
A Mermaid diagram that fails to parse does not fail the build. Hugo emits the fenced block, the browser's Mermaid runtime throws at render time, and the page ships with a blank space where the diagram should be. Nobody notices until a reader reports it.
That is exactly how the Gateway API traffic-path flowchart shipped broken: an edge label contained unquoted parentheses (
|issues Certificate(s)|), which Mermaid's parser rejects, so the whole flowchart rendered as nothing. It was live in both thev1.5andnextsnapshots until a user reported it.Proposal
Add a CI job that extracts every ```mermaid fenced block under
content/and parses it — `mermaid-cli` (`mmdc`) in headless Chromium renders each one and exits non-zero on a parse error. Fail the build if any block does not render.The check is cheap, needs no rendering fidelity judgement, and would have caught this defect at the point it was introduced rather than in production.