Markdown Mermaid Zoom (Fixed)

Adds Mermaid diagram and flowchart support with zoom, pan, and fullscreen capabilities to VS Code's built-in Markdown preview.

All functionality runs entirely client-side inside the VS Code webview -- no server or external services required.

This extension is an MIT-licensed fork of Markdown Mermaid Zoom by Hanzla Mateen. Version 0.4.1 fixes a fullscreen lifecycle bug where zooming out in fullscreen could make the inline diagram disappear after exit, and prevents fullscreen event handlers from accumulating across repeated use.

Features

• Mermaid Rendering -- Renders mermaid diagrams inline in VS Code's built-in Markdown preview
• Zoom In / Out -- Zoom via buttons, Alt+scroll wheel, pinch-to-zoom on trackpad, or Alt+click
• Pan -- Click-and-drag to pan around large diagrams (Alt+drag by default, configurable)
• Fullscreen Mode -- Expand any diagram to a fullscreen overlay for detailed exploration
• Vertical Resize -- Drag the bottom edge of any diagram to adjust its height
• Light/Dark Theme Support -- Automatically uses appropriate Mermaid theme based on VS Code's color theme
• Configurable Controls -- Show/hide navigation controls, adjust mouse behavior, set max height

Supported Diagram Types

Flowchart, Sequence, Gantt, Class, State, Pie, Entity Relationship, Mindmap, Git Graph, C4, User Journey, and all other Mermaid-supported diagram types.

Installation

From VS Code Marketplace

1. Open VS Code
2. Go to the Extensions view (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "Markdown Mermaid Zoom (Fixed)"
4. Click Install

From VSIX

1. Obtain the .vsix package from the publisher
2. In VS Code, open the Command Palette (Ctrl+Shift+P) and run Extensions: Install from VSIX...
3. Select the downloaded .vsix file

Usage

Mermaid Code Fences

Create diagrams in Markdown using fenced code blocks with the mermaid language identifier:

```mermaid
graph TD;
    A[Start] --> B{Decision};
    B -->|Yes| C[OK];
    B -->|No| D[Cancel];
```

Colon Blocks

You can also use ::: blocks:

::: mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
:::

Navigating Diagrams

Zooming

• Zoom controls -- Use the + and - buttons in the control bar
• Scroll wheel -- Hold Alt (Option on Mac) and scroll to zoom
• Pinch-to-zoom -- Use a trackpad pinch gesture
• Click zoom -- Alt+click to zoom in, Alt+Shift+click to zoom out

Panning

• Click and drag -- Hold Alt and click-drag to pan
• Pan mode -- Click the pan mode button (move icon) to enable free panning without holding Alt

Fullscreen

• Click the fullscreen button (expand icon) in the control bar to enter fullscreen mode
• In fullscreen, you get dedicated zoom/pan controls and a reset button
• Press Escape or click the exit fullscreen button to return to inline view

Resizing

• Drag the bottom edge of any diagram to resize it vertically
• Useful when combined with markdownMermaidZoom.maxHeight

Configuration

All settings are under the markdownMermaidZoom namespace.

Example Settings

{
  "markdownMermaidZoom.darkModeTheme": "forest",
  "markdownMermaidZoom.mouseNavigation": "always",
  "markdownMermaidZoom.controls.show": "always",
  "markdownMermaidZoom.maxHeight": "500px"
}

Development

Prerequisites

• Node.js >= 18
• VS Code >= 1.75.0

Setup

# Install dependencies
npm ci

# Build the extension
npm run build

Running & Debugging

1. Open the project in VS Code
2. Press F5 to launch the Extension Development Host
3. Open any Markdown file with mermaid code blocks to test

Build Scripts

Project Structure

src/
  extension/        Extension host (registers markdown-it plugin)
    index.ts        activate() entry point
    config.ts       Config reader and injector
  preview/          Markdown preview webview
    index.ts        Initializes mermaid, renders diagrams
  shared/           Shared between extension and preview
    markdownItMermaid.ts   markdown-it plugin
    mermaidRenderer.ts     Mermaid rendering logic
    diagramManager.ts      Pan/zoom/fullscreen manager
    diagramStyles.css      Styles for controls and overlays
    config.ts              Shared config types
build/              esbuild build scripts
test/               Test suite and fixtures

Packaging

npm ci
npm run lint
npm run compile-tests
npm test
npm run build
npx @vscode/vsce package

Troubleshooting

Diagrams fail to render after switching files

If diagrams render correctly the first time but show errors like "No diagram type detected" on subsequent previews, you most likely have a conflicting Mermaid extension installed.

Known conflicting extensions:

These extensions inject their own Mermaid.js instance into the same markdown preview webview. Two Mermaid instances running in the same webview corrupt each other's internal diagram detector registry, causing renders to fail after a few previews.

Fix: Disable or uninstall the conflicting extension. Only one Mermaid preview extension should be active at a time.

To check which extensions might conflict:

1. Open the Command Palette (Ctrl+Shift+P)
2. Run "Extensions: Show Installed Extensions"
3. Search for mermaid
4. Disable any other Mermaid-related preview extensions

Controls (zoom/pan/fullscreen) not appearing

If diagrams render but the control buttons are missing, ensure the setting markdownMermaidZoom.controls.show is not set to "never". The default value "onHoverOrFocus" shows controls when you hover over a diagram.

Acknowledgments

Original extension: Markdown Mermaid Zoom by Hanzla Mateen.

Inspired by:

• vscode-markdown-mermaid by Matt Bierner
• vscode-mermaid-chart by Mermaid Chart
• mermaid by the Mermaid.js team

License

MIT License. Copyright (c) 2026 Hanzla Mateen. This fork preserves the original license and attribution; see the bundled LICENSE and CHANGELOG.md files for details.