DOCS-2997: Enable Mermaid diagrams - #2952
Merged
Merged
Conversation
Add Mermaid support so structural diagrams can live in page source rather than as image files. Diagrams in the docs are currently Excalidraw exports committed to static/img. That suits diagrams that want real visual design. It suits structural figures less well, because the source is not diffable, a reviewer cannot check the topology against the prose, and only whoever holds the Excalidraw file can change it. Mermaid covers the second case. A diagram written in a fenced block sits next to the prose it illustrates, changes in the same commit, and is reviewed as text. The theme is pinned to 3.10.1 to match the other Docusaurus packages. Left on a caret range it resolves to 3.10.2 and pulls a second copy of the Docusaurus internals into the tree. No diagrams are added here. The first use is the host address placement figure in the L2 bridge networking set. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
✅ Deploy Preview for calico-docs-preview-next ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview succeeded!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
There was a problem hiding this comment.
Pull request overview
Enables Mermaid diagrams in the Docusaurus documentation site alongside existing Excalidraw assets.
Changes:
- Adds the pinned Mermaid theme dependency.
- Regenerates the Yarn lockfile.
- Enables Mermaid Markdown support and registers the theme.
Reviewed changes
Copilot reviewed 2 out of 3 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
yarn.lock |
Locks Mermaid and transitive dependencies. |
package.json |
Adds @docusaurus/theme-mermaid 3.10.1. |
docusaurus.config.js |
Enables Mermaid rendering and registers the theme. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds Mermaid support so structural diagrams can live in page source rather than as committed image files.
Diagrams in the docs today are Excalidraw exports in static/img. That suits diagrams that want real visual design, and it should stay for those. It suits structural figures less well: the source is not diffable, a reviewer cannot check a topology against the prose it sits next to, and only whoever holds the Excalidraw file can change it.
Mermaid covers the second case. A diagram in a fenced block sits beside the prose it illustrates, changes in the same commit, and is reviewed as text.
The change is three files:
No diagrams are added here, so this PR proves the build still works but does not prove a diagram renders. The first use is the host address placement figure in the L2 bridge networking set, which will land on the concept page and the prepared-bridge guide. Rendering gets demonstrated by that preview.
Worth a maintainer's view on whether Mermaid alongside Excalidraw is the direction you want, rather than standardising on one. My argument for both is that they solve different problems, but it is a repo-wide call rather than mine.