Mermaid Markdown Preview
Render Mermaid diagrams directly in VS Code's built-in
Markdown preview (Cmd/Ctrl+Shift+V). No external services — Mermaid is bundled into the
extension, so it works fully offline.
Why
VS Code's built-in Markdown preview does not understand ```mermaid code blocks —
it just shows them as plain text. This extension hooks into the built-in preview and
renders those blocks as diagrams. It also keeps them in sync as you edit.
Features
- Renders
```mermaid fenced code blocks in the built-in Markdown preview and
preview-to-the-side.
- Live updates while you type (re-renders on document change).
- Supports per-diagram
%%{init: …}%% theming directives.
- Works in Restricted Mode and virtual workspaces.
- Self-contained: bundles Mermaid v11, no CDN / network access required.
Usage
Install the extension (see below).
Open any .md file containing a Mermaid block:
```mermaid
flowchart LR
A[Start] --> B{Decision}
B -->|yes| C[Do it]
B -->|no| D[Skip]
```
Open the preview with Cmd+Shift+V (macOS) / Ctrl+Shift+V (Windows/Linux), or
"Open Preview to the Side" (Cmd/Ctrl+K V).
Install
From a packaged .vsix:
code --install-extension mermaid-markdown-preview-0.0.1.vsix
# Cursor: cursor --install-extension mermaid-markdown-preview-0.0.1.vsix
# Windsurf: windsurf --install-extension mermaid-markdown-preview-0.0.1.vsix
Or in the editor: Extensions view → … menu → Install from VSIX…
From the Marketplace (once published): search for Mermaid Markdown Preview.
Build from source
npm install
npm run build # bundles Mermaid into media/mermaid.bundle.js
npm run package # produces mermaid-markdown-preview-<version>.vsix
How it works
The extension contributes two things to the built-in Markdown preview via
contributes.markdown.previewScripts / previewStyles:
media/mermaid.bundle.js — an esbuild IIFE bundle of Mermaid that exposes
window.mermaid.media/index.js — finds code.language-mermaid blocks in the preview DOM, renders each
with mermaid.render(...), hides the original source, and re-renders on edits via a
debounced MutationObserver.
No activation event or extension host code is needed — it's a pure preview contribution.
License
MIT
