vitepress-plugin-mermaid

The plugin provides the following capabilities for VitePress users:

• Mermaid, Diagram and charting tools: Create diagrams and visualizations using text and code.
• Built-in Dark theme support: Automatically detects theme changes and switches between dark and light modes.
• Image support: Since it utilizes the Mermaid API, you can include images within your diagrams.
• Per-page theme configuration: You can set specific themes for individual pages using frontmatter options.

You can specify a unique Mermaid theme for an individual page using the mermaidTheme parameter in the Markdown frontmatter.

Note: This setting is only valid when the site is in light mode.

---
mermaidTheme: forest
title: A more complex example
---

Once configured, you can render Mermaid diagrams in your Markdown files using two different code block language identifiers:

• mmd
• mermaid

flowchart LR
  Start --> Stop

flowchart LR
  Start --> Stop

You can customize the appearance of Mermaid diagrams (such as themes and colors) by using the %%{init: {...}}%% directive at the beginning of your Mermaid code block. This allows you to pass configuration objects directly to the Mermaid engine within your VitePress documentation.

Commonly used keys within the init object include:

• theme: Sets the visual theme (e.g., 'base').
• themeVariables: An object containing specific style overrides, such as 'primaryColor'.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#ff0000'}}}%%
graph TD
  A[Christmas] --> B(Go shopping)

Wrap your existing Vitepress configuration with the withMermaid function from vitepress-plugin-mermaid. You can provide a mermaid configuration object to customize the mermaid rendering.

Note on Themes: The plugin automatically detects dark themes by looking for the string dark in the body class name. Because dark mode is forced when a dark theme is detected, you should provide your mermaid configuration intended for dark mode inside the mermaid key. The configuration provided here will effectively serve as the theme for dark mode, while light mode uses default settings.

// .vitepress/config.js
import { withMermaid } from "vitepress-plugin-mermaid";

export default withMermaid({
  // your existing vitepress config...
  mermaid: {
    // mermaidConfig !theme here works for light mode since dark theme is forced in dark mode
  },
  // ...
});

To use mermaid diagrams in Vitepress, you need to install both the plugin and the mermaid library as development dependencies.

Using npm:

npm i vitepress-plugin-mermaid mermaid -D

Using pnpm:

pnpm install --shamefully-hoist

Gantt charts can be created using the gantt keyword. You can define date formats, sections, and tasks with specific durations or dependencies (e.g., after [task_id]).

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

The plugin supports Mermaid mindmap diagrams. You can define a root node and nested branches, including the use of icons via the ::icon() syntax.

mindmap
  root((mindmap))
    Origins
      Long history
      ::icon(fa fa-book)
      Popularisation
        British popular psychology author Tony Buzan
    Research
      On effectiveness<br/>and features
      On Automatic creation
        Uses
            Creative techniques
            Strategic planning
            Argument mapping
    Tools
      Pen and paper
      Mermaid

You can render Pie charts using the pie keyword, defining a title and then providing data in the format "Label" : value.

pie title Pets adopted by volunteers
  "Dogs" : 386
  "Cats" : 85
  "Rats" : 15

Once the plugin is configured, you can render mermaid diagrams by using standard markdown code blocks with the mermaid language identifier.

flowchart TD
  Start --> Stop