vitepress-plugin-mermaid

vitepress-plugin-mermaid wraps the mermaid.js diagramming library into a VitePress-native experience: wrap your VitePress config in withMermaid(), drop a fenced ```mermaid code block into any markdown page, and it renders as an interactive SVG diagram at build time via a bundled Vue component and a markdown-it fence override.

The plugin auto-detects VitePress’s dark-mode toggle (any theme class containing “dark”) and re-renders the diagram with mermaid’s dark theme, so flowcharts, sequence diagrams, Gantt charts, and class diagrams stay legible without any theme-switching logic in your own docs code.

What You Get

• A withMermaid() config wrapper that patches your VitePress markdown-it and Vite config in one call
• A globally-registered Vue Mermaid.vue component that renders diagrams client-side via mermaid.js
• Automatic dark-mode detection tied to VitePress’s dark theme class, with no manual theme wiring
• A pre-configured Vite plugin handling optimizeDeps and aliasing for mermaid’s transitive dependencies (dayjs, cytoscape, etc.)
• Support for every Mermaid diagram type (flowcharts, sequence, class, state, Gantt, mindmap, C4, ZenUML) through a single fenced code block syntax

Common Use Cases

• Architecture docs - Engineering teams documenting system architecture in a VitePress knowledge base embed flowcharts and sequence diagrams directly in markdown instead of maintaining separate image exports.
• API/runbook docs - Platform teams writing operational runbooks use Gantt and state diagrams to describe deployment pipelines and incident-response flows without leaving their docs repo.
• Open-source project docs - Maintainers of OSS projects that already publish docs via VitePress add mermaid diagrams (e.g. dependency graphs, contribution flow) with a single config wrapper and no extra build step.

Under The Hood

Architecture: The library is a thin integration layer with five source files totaling under 200 lines. withMermaid() (src/index.ts) is the sole public entry point; it mutates a caller-supplied VitePress UserConfig object in place, injecting a markdown-it config hook (MermaidMarkdown, src/mermaid-markdown.ts) that overrides the fence renderer to intercept ```mermaid code blocks and emit a <Suspense>-wrapped <Mermaid> component tag with the diagram source URL-encoded into a graph prop, and pushing a Vite plugin (MermaidPlugin, src/mermaid-plugin.ts) that injects a Mermaid component registration into VitePress’s client bootstrap by string-patching the transformed vitepress/dist/client/app/index.js, and exposes user-supplied MermaidConfig through a virtual module (virtual:mermaid-config). At render time Mermaid.vue calls init()/render() (src/mermaid.ts), thin wrappers around mermaid.js’s registerExternalDiagrams/mermaid.render, and re-renders on any class mutation of document.documentElement via a MutationObserver, which is how it reacts to VitePress’s dark-mode toggle.

Tech Stack: TypeScript (72%) plus a single Vue 3 SFC (28%), built with Vite in library mode (vite.config.ts) producing ES and UMD bundles plus .d.ts typings via vite-plugin-dts, with vite-plugin-static-copy shipping Mermaid.vue/mermaid.ts as raw source alongside the compiled bundle so VitePress’s own toolchain can transform them. mermaid (v10/11) and vitepress (v1.x) are declared as peerDependencies rather than bundled, keeping the plugin thin and letting consumers control both versions independently; @mermaid-js/mermaid-mindmap is an optionalDependency for mindmap support.

Code Quality: There are no automated tests anywhere in the repository — no test runner configured, no *.test.*/*.spec.* files — so correctness relies entirely on manual verification against the docs site. Error handling is minimal: mermaid.ts’s init() catches and silently logs registerExternalDiagrams failures, and mermaid-markdown.ts catches render-time fence errors and falls back to a raw <pre>{err}</pre>. The client-injection strategy in mermaid-plugin.ts — string-splicing a component-registration line into VitePress’s compiled app/index.js by searching for the substring "app.component" — is a real fragility risk tied to VitePress’s internal build output; the repo’s inactive activity status and 0 commits/month reflect this hasn’t been revisited recently. Naming and typing are otherwise consistent, with explicit MermaidPluginConfig/MermaidPluginOptions interfaces.

API Design: The entire integration surface is a single withMermaid(config) wrapper that mutates and returns a standard VitePress UserConfig, so adoption requires one import and one function call around an existing config. Diagram authoring reuses the ```mermaid fence syntax already familiar from GitHub-flavored markdown, plus an mmd alias for syntax-highlighting-only blocks. Configuration splits cleanly into mermaid (passed straight to mermaid.js) and mermaidPlugin (plugin-specific options like a custom CSS class). The main DX rough edge is that dark-theme behavior is implicit and global — any dark-named class flips every diagram to mermaid’s dark theme — with only a single per-page mermaidTheme frontmatter escape hatch, and there’s no dedicated API reference beyond the “Getting Started”/“More examples” guide pages.