layouts: render mermaid code blocks as diagrams#25178
Conversation
Adds a Hugo codeblock render hook that turns ```mermaid fences into <pre class="mermaid"> containers, plus a lazily-loaded mermaid bundle that only ships on pages that actually contain a diagram. Mirrors the existing YouTube embed pattern (Store flag + conditional script tag in baseof) so the main scripts.js bundle stays unchanged.
✅ Deploy Preview for docsdocker ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
github-actions
Bot
added
hugo
docker-agent
left a comment
docker-agent
left a comment
There was a problem hiding this comment.
Assessment: 🟢 APPROVE
This PR cleanly adds Mermaid diagram rendering to the Hugo docs site. The implementation is well-structured: securityLevel: 'strict' (DOMPurify) is set, the mermaid bundle is lazy-loaded only on pages that contain a diagram via .Page.Store, and defer is used correctly. No vendored files are touched, no pages are removed, and no documentation content changes are present. Two minor notes in inline comments.
| mermaid.initialize({ | ||
| startOnLoad: false, | ||
| securityLevel: 'strict', | ||
| theme: isDark() ? 'dark' : 'default', |
There was a problem hiding this comment.
[LOW] Theme is sampled once at module load; runtime theme toggles won't update Mermaid diagrams
mermaid.initialize() reads isDark() a single time when the module loads. After that, the Mermaid theme is fixed for the lifetime of the page — if a user toggles dark/light mode, existing diagrams keep the original theme until a full page reload.
The PR description acknowledges this: "Live re-painting on theme toggle is not handled in this PR." Noting it here for tracking — a follow-up could add a MutationObserver on document.documentElement's class list to call mermaid.initialize() + mermaid.run() on theme changes.
| {{ $mermaid := resources.Get "js/mermaid.js" | ||
| | js.Build (dict "minify" true "targetPath" "mermaid.js") | ||
| }} | ||
| <script defer src="{{ $mermaid.Permalink }}"></script> |
There was a problem hiding this comment.
[LOW] .Permalink produces an absolute URL for the script src; .RelPermalink is more portable
.Permalink emits the full absolute URL (e.g., https://docs.docker.com/mermaid.js). For a single canonical-domain deployment this works fine, but it can break in local development or staging environments served from a different origin or path prefix, where the absolute URL would point at the wrong host. Hugo's idiomatic convention for internal asset references is .RelPermalink, which produces a root-relative path (e.g., /mermaid.js) that adapts to any host automatically.
Consider changing to:
<script defer src="{{ $mermaid.RelPermalink }}"></script>Replaces the goat ASCII-art registry/repository/image diagram with a mermaid flowchart that uses nested subgraphs to express the same containment hierarchy. Also exercises the new mermaid codeblock hook so the layouts ship with at least one consumer.
github-actions
Bot
added
the
area/get-started
Replace the ASCII clone-mode diagram with a mermaid flowchart, per review feedback. Relies on the mermaid codeblock render hook from docker#25178. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replace the ASCII clone-mode diagram with a mermaid flowchart, per review feedback. Relies on the mermaid codeblock render hook from docker#25178. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
4 participants
Summary
Add a Hugo codeblock render hook that turns
```mermaidfences into client-rendered diagrams. The mermaid runtime is built into its ownmermaid.jsbundle (~3 MB) and loaded only on pages that actually contain a diagram, so the mainscripts.jsbundle stays unchanged. Mirrors the existing YouTube embed pattern (.Page.Storeflag + conditional<script>tag inbaseof.html).Initial theme is picked from the
darkclass on<html>on page load. Live re-painting on theme toggle is not handled in this PR.Generated by Claude Code
Example
https://deploy-preview-25178--docsdocker.netlify.app/get-started/docker-concepts/the-basics/what-is-a-registry/#registry-vs-repository
This diagram isn't really prettier than the GoAT one it replaces, but our validation job fails if we don't use templates at least once, so converting this one to dodge a CI failure, at least until mermaid diagrams are actually used (eg in #25140)