Usage

Installation

npm install vitepress-mermaid-viewer mermaid

Simple setup with wrapper

Wrap your VitePress config — adds markdown plugin, Vite plugin, optimizeDeps, and module aliases automatically.

// 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

Use individual exports for full control over the configuration.

// 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
Zoom in/out	+ / - buttons, mouse wheel, pinch gesture
Pan	Click and drag
Reset	↻ button
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.