ADR-072: Bundle Mermaid with the generated documentation
Date: 2026-10-18 Status: Accepted Author: Rômulo Febasi Issue: SYN-342 (#347)
Context
The published release-pipeline chapter contains a Mermaid code fence but no Mermaid runtime. Plain mdBook syntax highlighting cannot render that diagram. Canonical tracked Markdown already serves GitHub and the generated book, so maintaining separate hand-rendered copies would introduce drift.
Decision
Keep mdBook 0.5.4 and use official mdbook-mermaid 0.17.1, which uses the mdBook 0.5 preprocessor API. Verify each pinned release archive SHA-256 before running its executable. Configure the generated book with the standard preprocessor and run its standard installer to bundle the unmodified runtime and initializer. Serve these assets from the generated site, with no runtime CDN.
flowchart TB
A[Tracked canonical Markdown] --> B[Generated book]
P[Pinned verified official tools] --> C[Mermaid preprocessor]
B --> C
C --> D[HTML and bundled local scripts]
D --> E[Publication structure and asset gate]
E --> F[Browser SVG and layout check]
Require every diagram chapter to preserve its diagram count, contain no raw Mermaid code fence, and load the pinned local runtime before its initializer. The verifier checks actual generated HTML, source Markdown and script bytes. Existing source coverage, search, privacy and editorial checks remain required.
Consequences
The same diagram source serves GitHub and Pages without a runtime network request to a third-party CDN. Tool upgrades require explicit archive and bundled asset digest updates plus the full publication suite. The plugin adds JavaScript to the generated book; runtime errors and visual quality still require browser acceptance. Structural checks alone do not prove SVG rendering or layout.
Alternatives considered
- Plain mdBook leaves diagrams as raw code and does not meet publication needs.
- Runtime CDN scripts add a network dependency and mutable external delivery.
- A custom renderer or duplicated SVG snapshots add a second authoring path.
References
Browser acceptance
Actual local generated-site review rendered all four diagrams across three chapters with no raw Mermaid fence or renderer error. The knowledge flow now uses a vertical layout and wrapped labels while preserving all 17 directed relations. Its labels render at the normal 16-pixel scale in the reviewed book column, compared with approximately 3.8 pixels before. Wrapped sequence labels retain all five participants and eight messages. This is local browser evidence; hosted Pages deployment remains a separate gate. See the browser receipt.