feat(mdx): add mermaid diagram support by ashrees · Pull Request #9107 · nodejs/nodejs.org

ashrees · 2026-08-14T20:19:01Z

Adds Mermaid diagram support to the MDX pipeline, as requested in #7540 (blessed there by @AugustinMauroy, with rehype-mermaid suggested by @flakey5).

How it works

rehype-mermaid (strategy pre-mermaid) is added to the rehype chain in apps/site/mdx/plugins.mjs, positioned before @node-core/rehype-shiki so ```mermaid fenced blocks become <pre class="mermaid"> instead of being syntax-highlighted as plain code.
MDXCodeBox (the pre MDX override) detects the mermaid class and renders a new Mermaid client component instead of a code box.
The Mermaid component lazy-loads the mermaid library on the client (keeping it out of the initial bundle) and re-renders on theme change via next-themes (default / dark themes).
Invalid diagram sources fall back to rendering the raw source text.

Testing

Verified the rehype chain ordering in isolation: ```mermaid blocks emit <pre class="mermaid"> with the diagram source intact, while regular code blocks still go through Shiki highlighting.
eslint and stylelint pass 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

vercel · 2026-08-14T20:19:07Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nodejs-org	Ready	Preview	Aug 18, 2026 4:24am

Copilot

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-mermaid to the MDX rehype plugin chain (before Shiki) and added mermaid/rehype-mermaid dependencies.
Introduced a new Mermaid MDX component that lazy-loads Mermaid on the client and re-renders on theme changes.
Updated the MDXCodeBox (pre override) 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.

+    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);
+        }
+      }
+    };


ashrees · 2026-08-14T23:45:58Z

Addressed the Copilot review on the Mermaid component (head bc37755):

the dynamic import('mermaid') now sits inside the try block, so a failed chunk load falls back gracefully
securityLevel: 'strict' is set on mermaid.initialize
bindFunctions from mermaid.render() is invoked, enabling diagram interactions
the error fallback now renders the source inside a <pre> to preserve whitespace

avivkeller · 2026-08-15T13:51:21Z

 import rehypeShikiji from '@node-core/rehype-shiki/plugin';
 import remarkHeadings from '@vcarl/remark-headings';
 import rehypeAutolinkHeadings from 'rehype-autolink-headings';
+import rehypeMermaid from 'rehype-mermaid';


Doesn't this dramatically slow down builds since it requires initializing a whole browser instance?

No — with strategy: 'pre-mermaid' no browser is ever started at build time. Verified in the dependency source:

createMermaidRenderer() only creates a lazy browserPromise (browserPromise ||= getBrowser(...) inside the returned render function in mermaid-isomorphic) — nothing launches at plugin setup.

rehype-mermaid never calls that render function for pre-mermaid; it only rewrites the AST (<pre><code class="language-mermaid"> → <pre class="mermaid">). The package comments this exact path as "No need to start a browser in this case."

Playwright (peer dep) is only exercised by the inline-svg / img-* strategies.

So build cost is a single AST walk per document, and rendering happens client-side — with the mermaid library itself lazy-loaded via dynamic import(), so it stays out of the initial bundle too.

Happy to switch to inline-svg if the team prefers zero client-side JS — that's the trade-off (build-time Chromium vs. client rendering).

Can you do some benchmarks and compare building site previously and after? + adding an example storybook with mermaid content so we can render/test?

both done. stories are in packages/ui-components/src/MDX/Mermaid/index.stories.tsx (flowchart, sequence, dark, invalid-source). for the benchmark i compiled 25 real blog posts through the production chain, with vs without the plugin, 3 warmed runs — 5.62 vs 5.19 ms/doc, so no measurable build cost (pre-mermaid is ast-only, no browser involved).

ovflowd · 2026-08-17T16:53:48Z

  [rehypeAutolinkHeadings, { behavior: 'wrap' }],
+  // Transforms ```mermaid code blocks into renderable diagrams;
+  // must run before Shiki so they are not highlighted as plain code
+  [rehypeMermaid, { strategy: 'pre-mermaid' }],


If we're using rehype-mermaid, do we need to add mermaid support on code boxes? Or what exactly this rehype plugin does?

it's pretty minimal — the plugin just rewrites ```mermaid fenced blocks into
at compile time. MDXCodeBox routes those to the mermaid component instead of a code box, and regular code blocks are untouched. so no, no extra codebox support needed.

ovflowd · 2026-08-17T16:56:49Z

+  const { resolvedTheme } = useTheme();
+  const reactId = useId().replace(/:/g, '-');
+
+  useEffect(() => {


So we're doing mermaid rendering solely on the client-side? Is this what we'd like to have, @avivkeller?

BTW, @ashrees could you extract this effect into a dedicated hook, so we can unit test the Mermaid specific API within an unit testable hook?

I saw some people made browserless versions of Mermaid, e.g.:
https://github.com/1jehuang/mermaid-rs-renderer

I can write bindings for it?

Define bindings? 👀

Looks like they already exist at https://www.npmjs.com/package/@mermanjs/web

That looks nice, @ashrees can you update your PR?

yes, client-side only. the effect is extracted into useMermaid now (packages/ui-components/src/hooks/useMermaid.ts) with an injectable loader so tests can stub the wasm renderer — unit tests live in test/useMermaid.test.jsx, 2/2 passing locally. if you'd rather have build-time rendering (inline-svg) instead, happy to explore that.

done — rendering now goes through @mermanjs/web (wasm), so the 500kb mermaid.js is out of the client bundle entirely.

ashrees · 2026-08-18T04:14:57Z

Updated the PR per the review (head 99db225):

@ovflowd's asks:

Dedicated, unit-testable hook — the effect now lives in useMermaid (packages/ui-components/src/hooks/useMermaid.ts) with an injectable loader for test stubbing. Unit tests in __test__/useMermaid.test.jsx (node:test + testing-library): 2/2 pass.
Storybook story — packages/ui-components/src/MDX/Mermaid/index.stories.tsx with flowchart, sequence, dark-theme, and invalid-source variants.
Benchmarks — compiled 25 real blog posts through the production rehype chain (slug → autolink → shiki), with vs. without the plugin, 3 warmed runs: 5.62ms/doc vs 5.19ms/doc — no measurable build-time impact (delta within run variance), because pre-mermaid is AST-only and never starts a browser.

Renderer switch (@avivkeller): rendering now uses @mermanjs/web (Merman WASM) instead of mermaid.js — so even the client-side path drops the ~500KB JS dependency. Theme-aware (light/dark via next-themes in the site wrapper), invalid sources fall back to a <pre> with the raw source.

What the rehype plugin does (clarifying question): it only rewrites ```mermaid fenced blocks into <pre class="mermaid"> at compile time; the MDXCodeBox override then routes those to the Mermaid component. Code boxes are otherwise untouched — no separate codebox support needed.

The component lives in @node-core/ui-components (alongside the other MDX components) with a thin next-themes wrapper in apps/site.

Adds rehype-mermaid (pre-mermaid strategy) to the MDX rehype chain before Shiki. Diagrams render client-side through a dedicated useMermaid hook (@node-core/ui-components) backed by the @mermanjs/web WASM renderer — no browser at build time and no heavy mermaid.js bundle. - useMermaid hook with injectable loader + node:test unit tests (2/2 pass) - Mermaid component with light/dark themes and <pre> source fallback - Storybook stories (flowchart, sequence, dark, invalid source) - Benchmarked against 25 real blog docs: no measurable compile-time impact (within run variance) Fixes: nodejs#7540

avivkeller

Can't we make a remark plugin to do the transform?

avivkeller · 2026-08-18T05:05:48Z

@ashrees Please familiarize yourself with Node.js's AI Policy, and review the code you write. Your comments do not match the actual code, which makes it seem as though you don't understand what you've written. If that's the case, it's okay, but be transparent.

codecov · 2026-08-18T06:57:53Z

Codecov Report

❌ Patch coverage is 98.14815% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 86.21%. Comparing base (707dd00) to head (4459c03).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
packages/ui-components/src/hooks/useMermaid.ts	98.14%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #9107      +/-   ##
==========================================
+ Coverage   86.05%   86.21%   +0.15%     
==========================================
  Files          86       87       +1     
  Lines        6046     6100      +54     
  Branches      358      361       +3     
==========================================
+ Hits         5203     5259      +56     
+ Misses        839      837       -2     
  Partials        4        4

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

github-actions · 2026-08-18T07:05:28Z

📦 Build Size Comparison

Summary

Metric	Value
Old Total First Load JS	7.06 MB
New Total First Load JS	7.06 MB
Delta	4.36 KB (+0.06%)

Changes

🔄 Modified Routes (4)

Route	Old First Load JS	New First Load JS	Delta
`/[locale]`	1.66 MB	1.66 MB	📈 1.09 KB (+0.06%)
`/[locale]/[...path]`	1.66 MB	1.66 MB	📈 1.09 KB (+0.06%)
`/[locale]/blog/[...path]`	1.66 MB	1.66 MB	📈 1.09 KB (+0.06%)
`/[locale]/download/archive/[version]`	1.66 MB	1.66 MB	📈 1.09 KB (+0.06%)

ashrees requested a review from a team as a code owner August 14, 2026 20:19

Copilot AI lite review requested due to automatic review settings August 14, 2026 20:19

ashrees requested a review from a team as a code owner August 14, 2026 20:19

Copilot started reviewing on behalf of ashrees August 14, 2026 20:19 View session

vercel Bot deployed to Preview August 14, 2026 20:20 View deployment

Copilot AI reviewed Aug 14, 2026

View reviewed changes

ashrees force-pushed the feat/mermaid-support branch from 4b6eca2 to bc37755 Compare August 14, 2026 23:45

vercel Bot deployed to Preview August 14, 2026 23:46 View deployment

avivkeller reviewed Aug 15, 2026

View reviewed changes

ovflowd reviewed Aug 17, 2026

View reviewed changes

ashrees force-pushed the feat/mermaid-support branch from bc37755 to 99db225 Compare August 18, 2026 04:14

vercel Bot deployed to Preview August 18, 2026 04:15 View deployment

ashrees force-pushed the feat/mermaid-support branch from 99db225 to 4459c03 Compare August 18, 2026 04:22

vercel Bot deployed to Preview August 18, 2026 04:24 View deployment

avivkeller requested changes Aug 18, 2026

View reviewed changes

ashrees had a problem deploying to Storybook August 18, 2026 06:55 — with GitHub Actions Failure

Uh oh!

Conversation

ashrees commented Aug 14, 2026

How it works

Testing

Uh oh!

vercel Bot commented Aug 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

ashrees commented Aug 14, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ashrees commented Aug 18, 2026

Uh oh!

avivkeller left a comment

Choose a reason for hiding this comment

Uh oh!

avivkeller commented Aug 18, 2026

Uh oh!

codecov Bot commented Aug 18, 2026

Codecov Report

Uh oh!

github-actions Bot commented Aug 18, 2026

📦 Build Size Comparison

Summary

Changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

vercel Bot commented Aug 14, 2026 •

edited

Loading