feat: add mermaid diagram rendering support#2943
feat: add mermaid diagram rendering support#2943rbizos wants to merge 1 commit intoprometheus:mainfrom
Conversation
Render mermaid code blocks as interactive SVG diagrams via a rehype plugin that transforms them into client-side React components. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Raphael Bizos <r.bizos@criteo.com>
| "typescript": "^5" | ||
| } | ||
| }, | ||
| "node_modules/@antfu/install-pkg": { |
There was a problem hiding this comment.
I'm not an expert for JS, but this dep feels pointless (: I assume mermaid package needs it.
Other dependencies like d3 are heavy too.
@juliusv would that be a problem?
There was a problem hiding this comment.
I'm also no real JS or JS deps expert, but I do see more data being downloaded on every documentation page, even if it does not contain a Mermaid diagram. For example, checking the total page download size for /docs/introduction/first_steps/ in the Chrome Network tab in an incognito window (building both main and the PR with npm run build-all and then npx serve out):
main: 941kB transferredfeature/mermaid: 1.1MB transferred
We definitely want to avoid that extra overhead for every page for a niche feature that's only used on one page so far.
Asked about that, Claude gives the following feedback, which might worth looking into (but again, I don't have much experience with this myself):
I was thinking server-side rendering of Mermaid diagrams would be nice, but I guess that's not supported yet (mermaid-js/mermaid#3650).
|
Looks good! 
|
bwplotka
left a comment
bwplotka
left a comment
There was a problem hiding this comment.
In our OM2 WG we also mention we are ok with static generation or text based, so other options are on the table too.
| import { useEffect, useId, useState } from "react"; | ||
|
|
||
| function initializeMermaid() { | ||
| const isDarkMode = window.matchMedia("(prefers-color-scheme: dark)").matches; |
There was a problem hiding this comment.
Could you use the useComputedColorScheme hook from Mantine here? See examples from the Prometheus codebase: https://github.com/search?q=repo%3Aprometheus%2Fprometheus%20useComputedColorScheme&type=code
And maybe the right place to do that is in the component below, and then re-init Mermaid when the color scheme changes, so the diagram is updated.
Currently the color scheme also doesn't work correctly for me, I'm always getting the light variant of the diagram, even in dark mode:
| "typescript": "^5" | ||
| } | ||
| }, | ||
| "node_modules/@antfu/install-pkg": { |
There was a problem hiding this comment.
I'm also no real JS or JS deps expert, but I do see more data being downloaded on every documentation page, even if it does not contain a Mermaid diagram. For example, checking the total page download size for /docs/introduction/first_steps/ in the Chrome Network tab in an incognito window (building both main and the PR with npm run build-all and then npx serve out):
main: 941kB transferredfeature/mermaid: 1.1MB transferred
We definitely want to avoid that extra overhead for every page for a niche feature that's only used on one page so far.
Asked about that, Claude gives the following feedback, which might worth looking into (but again, I don't have much experience with this myself):
I was thinking server-side rendering of Mermaid diagrams would be nice, but I guess that's not supported yet (mermaid-js/mermaid#3650).
This might actually be a sensible approach to this in the context of the Prometheus docs repo, unless we plan on using Mermaid diagrams in many more places? |
3 participants
Render mermaid code blocks as interactive SVG diagrams via a homemade rehype plugin with https://github.com/mermaid-js/mermaid.
This was somewhat simpler than using rehype-mermaid. The result looks like this
