ADR 0014: Diagrams as Mermaid, checked in CI and replaced on PyPI¶
- Status: accepted (3.0.2). Asked for by the package owner on 2026-11-11.
Context¶
The owner asked for diagrams in the documentation and the README. The README appears in three places: GitHub, the docs site (ADR 0013) and PyPI, where each release keeps its README forever (ADR 0012). GitHub and Material for MkDocs render Mermaid; PyPI does not, and would show a diagram's source.
Material renders Mermaid in the reader's browser, so mkdocs build --strict
never sees a diagram that fails to parse: the live page would show its source
in silence. A ; inside a sequence diagram label did exactly that while this
record was being written. And by default Material loads whatever Mermaid 11.x
is newest, so a diagram that parsed yesterday can break without a commit.
Decision¶
- Diagrams are Mermaid fences in Markdown, next to the text they explain:
the README (retries, magic-number scope) and
docs/architecture.md(layers, ports, request flow, concurrency). The site's palette themes them; there is no image to regenerate when the code changes. - The site pins one Mermaid release with its integrity hash in
overrides/main.html(11.17.2 from unpkg.com, Subresource Integrity as OWASP ASVS requires for externally hosted scripts). A template, becauseextra_javascriptcannot carry an integrity attribute. Material uses an already loaded Mermaid instead of fetching the newest 11.x, so a diagram changes only with a commit, and a changed file on unpkg is refused. scripts/check_diagrams.pyrenders every diagram in the README, the changelog, the migration guide anddocs/with that same file and hash, read from the template, in headless Chrome with its sandbox on. Rendering, not only parsing: some errors appear only when a diagram is laid out.docs.ymlruns it on every pull request, in a job of its own, apart from the site artifact, and the deploy waits for it. It judges every Mermaid fence where it starts, and fails when one does not parse, when one is written in a form it cannot extract (~~~, indented), and when Mermaid never loaded or fewer verdicts than diagrams came back, because then nothing was checked.scripts/replace_readme_diagrams.pyswaps each diagram for a link to its section of the README on GitHub in the publish workflow. It runs before the links are pinned (ADR 0012), so the link names the release tag and shows the diagram of that release, not the site's, which follows master. It fails on a Mermaid fence it cannot swap, and on a diagram whose match ran past its own closing fence, rather than ship a README with source in it or text missing. The CI hygiene job runs it beforetwine check, so the check covers the README that PyPI receives.scripts/mermaid_fences.pyholds the one definition of a diagram and of a code block that both scripts use, so CI cannot pass a README the publish then refuses.
We chose Mermaid over committed SVG or PNG files because an image drifts from the code it shows, and the regeneration step would need its own check. The cost is a browser in CI.
We chose a pinned URL over a copy of Mermaid in the repository because it pins the version without a vendored file of about 3 MB. The cost: readers' browsers still fetch it from unpkg.com.
We chose replacing the diagrams for PyPI over leaving the source there because a release's README cannot be fixed once it is on PyPI.
Consequences¶
- Moving to a newer Mermaid means a new URL and hash in the template, checked like any other pull request: a wrong hash fails the diagram check.
- The diagram check depends on unpkg.com being reachable from CI. When it is
not, the check fails rather than passing unchecked, and the deploy, which
waits for it, does not run: a docs fix waits until unpkg is back and the
run is repeated. We chose that over deploying unchecked diagrams, because
merges can skip the pull request checks (
--admin). - On PyPI each diagram is a one-line link to the same diagram in that release's README on GitHub.