VitePress Mermaid Viewer

Diagrams that you can actually read.

Mermaid diagrams for VitePress with interactive zoom, pan, and fullscreen viewing.

Features

• Renders ```mermaid code blocks as diagrams
• Click any diagram to open fullscreen viewer
• Zoom: buttons, mouse wheel (cursor-centered), pinch-to-zoom (touch)
• Pan/drag with mouse or touch
• Keyboard accessible — Enter / Space to open, + / - / 0 / arrows inside the viewer, ARIA labels and focus management
• Dark/light theme reactivity
• Supports mmd alias for mermaid blocks
• Per-page theme override via mermaidTheme frontmatter

Installation

npm install vitepress-mermaid-viewer mermaid

Quick Start

Simple setup with wrapper

// docs/.vitepress/config.ts
import { defineConfig } from 'vitepress';
import { withMermaid } from 'vitepress-mermaid-viewer';

export default withMermaid(
  defineConfig({
    // your VitePress config...

    // optional mermaid config
    mermaid: {
      theme: 'default',
    },

    // optional plugin config
    mermaidPlugin: {
      class: 'mermaid',
    },
  }),
);

Manual setup

// docs/.vitepress/config.ts
import { defineConfig } from 'vitepress';
import { MermaidPlugin, MermaidMarkdown } from 'vitepress-mermaid-viewer';

export default defineConfig({
  markdown: {
    config: (md) => {
      MermaidMarkdown(md, { class: 'mermaid' });
    },
  },

  vite: {
    plugins: [
      MermaidPlugin({
        // mermaid config
        theme: 'default',
      }),
    ],

    optimizeDeps: {
      include: ['@braintree/sanitize-url', 'dayjs', 'debug', 'cytoscape-cose-bilkent', 'cytoscape'],
    },

    resolve: {
      alias: {
        'dayjs/plugin/advancedFormat.js': 'dayjs/esm/plugin/advancedFormat',
        'dayjs/plugin/customParseFormat.js': 'dayjs/esm/plugin/customParseFormat',
        'dayjs/plugin/isoWeek.js': 'dayjs/esm/plugin/isoWeek',
        'cytoscape/dist/cytoscape.umd.js': 'cytoscape/dist/cytoscape.esm.js',
      },
    },
  },
});

Viewer Controls

| Action | Input | | ------------ | ---------------------------------------------------- | | Open viewer | Click on diagram, Enter / Space when focused | | Zoom in | + button, mouse wheel up, pinch out, + / = key | | Zoom out | − button, mouse wheel down, pinch in, - key | | Pan | Click and drag, arrow keys | | Reset | ↻ button, 0 key | | Download SVG | SVG button in viewer | | Download PNG | PNG button in viewer | | Close | ✕ button, Escape key |

Frontmatter Options

Override mermaid theme per page:

---
mermaidTheme: forest
---

API

withMermaid(config: UserConfig): UserConfig

Wraps VitePress config — adds markdown plugin, Vite plugin, optimizeDeps, and module aliases.

MermaidMarkdown(md, options?)

Markdown-it plugin. Intercepts ```mermaid fences and renders them as <Mermaid> components.

Options:

• class — CSS class for diagram container (default: 'mermaid')

MermaidPlugin(config?)

Vite plugin. Injects <Mermaid> component globally and serves mermaid config via virtual module.

Accepts mermaid configuration object.

Additional options:

• download — show Download SVG button in viewer (default: true)
• downloadPng — show Download PNG button in viewer (default: true)

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

License

MIT