feat(mdx): add mermaid diagram support - #9107
Open
ashrees wants to merge 1 commit into
Open
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds Mermaid diagram rendering support to the site’s MDX pipeline by transforming ```mermaid fenced blocks into a renderable form during MDX compilation and then rendering them client-side at runtime.
Changes:
- Added
rehype-mermaidto the MDX rehype plugin chain (before Shiki) and addedmermaid/rehype-mermaiddependencies. - Introduced a new
MermaidMDX component that lazy-loads Mermaid on the client and re-renders on theme changes. - Updated the
MDXCodeBox(preoverride) to route Mermaid blocks to the new Mermaid renderer instead of the standard code box.
Reviewed changes
Copilot reviewed 5 out of 6 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| pnpm-lock.yaml | Locks new dependencies pulled in by mermaid and rehype-mermaid. |
| apps/site/package.json | Adds mermaid and rehype-mermaid runtime dependencies. |
| apps/site/mdx/plugins.mjs | Inserts rehype-mermaid before Shiki to avoid Mermaid blocks being highlighted as plain code. |
| apps/site/components/MDX/Mermaid/index.tsx | New client component that loads Mermaid lazily and renders diagrams (with theme support). |
| apps/site/components/MDX/Mermaid/index.module.css | Basic layout constraints for Mermaid-rendered SVG output. |
| apps/site/components/MDX/CodeBox/index.tsx | Detects Mermaid <pre class="mermaid"> blocks and renders the Mermaid component instead of CodeBox. |
Files not reviewed (1)
- pnpm-lock.yaml: Generated file
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+23
to
+47
| const renderDiagram = async () => { | ||
| // Mermaid is heavy, so we only load it on the client when needed | ||
| const { default: mermaid } = await import('mermaid'); | ||
|
|
||
| mermaid.initialize({ | ||
| startOnLoad: false, | ||
| theme: resolvedTheme === 'dark' ? 'dark' : 'default', | ||
| }); | ||
|
|
||
| try { | ||
| const { svg } = await mermaid.render( | ||
| `mermaid-${reactId}`, | ||
| String(children).trim() | ||
| ); | ||
|
|
||
| if (!cancelled && containerRef.current) { | ||
| containerRef.current.innerHTML = svg; | ||
| } | ||
| } catch { | ||
| // If the diagram source is invalid, fall back to showing the source | ||
| if (!cancelled && containerRef.current) { | ||
| containerRef.current.textContent = String(children); | ||
| } | ||
| } | ||
| }; |
Adds rehype-mermaid (pre-mermaid strategy) to the MDX rehype chain before Shiki, and renders the resulting pre.mermaid blocks with a client-side Mermaid component that follows the site's theme. Fixes: nodejs#7540
ashrees
force-pushed
the
feat/mermaid-support
branch
from
August 14, 2026 23:45
4b6eca2 to
bc37755
Compare
Author
|
Addressed the Copilot review on the Mermaid component (head
|
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 diagram support to the MDX pipeline, as requested in #7540 (blessed there by @AugustinMauroy, with
rehype-mermaidsuggested by @flakey5).How it works
rehype-mermaid(strategypre-mermaid) is added to the rehype chain inapps/site/mdx/plugins.mjs, positioned before@node-core/rehype-shikiso```mermaidfenced blocks become<pre class="mermaid">instead of being syntax-highlighted as plain code.MDXCodeBox(thepreMDX override) detects themermaidclass and renders a newMermaidclient component instead of a code box.Mermaidcomponent lazy-loads themermaidlibrary on the client (keeping it out of the initial bundle) and re-renders on theme change vianext-themes(default/darkthemes).Testing
```mermaidblocks emit<pre class="mermaid">with the diagram source intact, while regular code blocks still go through Shiki highlighting.eslintandstylelintpass on all changed files.Happy to switch to a build-time strategy (
inline-svg) if preferred — I chose client-side rendering to avoid adding a heavy build-time dependency (Playwright/Chromium).Fixes #7540