vitepress-mermaid-preview

A plugin for displaying Mermaid diagrams in VitePress.

🚀 Installation

npm install vitepress-mermaid-preview
# or
yarn add vitepress-mermaid-preview
# or
pnpm add vitepress-mermaid-preview

⚙️ Configuration

Add the plugin in .vitepress/config.ts:

// .vitepress/config.ts
import { defineConfig } from 'vitepress';
import { vitepressMermaidPreview } from 'vitepress-mermaid-preview';

export default defineConfig({
  markdown: {
    config: (md) => {
      vitepressMermaidPreview(md, {
        showToolbar: false, // Global setting: whether to show toolbar by default
      });
    },
  },
});

Register the global component in .vitepress/theme/index.ts:

// .vitepress/theme/index.ts
import type { Theme } from 'vitepress';
import DefaultTheme from 'vitepress/theme';
import { initComponent } from 'vitepress-mermaid-preview/component';
import 'vitepress-mermaid-preview/dist/index.css';

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    initComponent(app);
  },
} satisfies Theme;

📖 Usage

📝 Basic Usage

You can directly use Mermaid code blocks in Markdown to create diagrams:

gantt
    title A Gantt Diagram
    dateFormat YYYY-MM-DD
    section Section
        A task          :a1, 2014-01-01, 30d
        Another task    :after a1, 20d
    section Another
        Task in Another :2014-01-12, 12d
        another task    :24d

🔧 Toolbar Control

You can control toolbar visibility using frontmatter in code blocks:

---
showToolbar: true
---
sequenceDiagram
    participant A
    participant B
    A->>B: Hello
    B-->>A: Hi

📂 Load from File

Use the PreviewMermaidPath component to load and display Mermaid diagrams from a specified file:

<!-- Basic usage (toolbar hidden by default) -->
<PreviewMermaidPath path="./other.mmd" />

<!-- Show toolbar -->
<PreviewMermaidPath path="./other.mmd" showToolbar />

⚙️ Component Options

PreviewMermaidPath Props

| Prop | Type | Default | Description | | ----------- | ------- | ------- | -------------------------------- | | path | string | - | Path to the Mermaid file to load | | showToolbar | boolean | false | Whether to show the toolbar |

📄 License

• MIT

🙏 Acknowledgments

• mermaid
• VitePress
• markdown-it

Made with ❤️ by flingyp