Advanced Stack

Appearance

How to setup Mermaid Plugin for VitePress ​

Introduction ​

We publish this blog with VitePress and we use Mermaid for diagrams. This guide shows the shortest path to rendering Mermaid in a VitePress blog using vitepress-plugin-mermaid.

Overview ​

You will:

  • Install the Mermaid plugin and dependencies.
  • Wrap the VitePress config with withMermaid.
  • Verify rendering with three quick examples.

Prerequisites ​

  • Node 18+
  • VitePress 1.x project (we stay on 1.x because it is the stable baseline for the blog; once 2.x is stable, this guide will be updated)

Step 1: Install Mermaid + plugin ​

npm i vitepress-plugin-mermaid mermaid @mermaid-js/mermaid-mindmap -D

Working versions in this repo (latest on npm as of 2026-02-25):

jsonc
{
  // Latest versions checked on 2026-02-25.
  "devDependencies": {
    "@mermaid-js/mermaid-mindmap": "^9.3.0",
    "mermaid": "^11.12.3",
    "vitepress": "^1.6.4",
    "vitepress-plugin-mermaid": "^2.0.17"
  }
}

Step 2: Wrap the VitePress config ​

In app/.vitepress/config.mjs:

javascript
import { defineConfig } from 'vitepress'
import { withMermaid } from 'vitepress-plugin-mermaid'

export default withMermaid(
  defineConfig({
    // your VitePress config
  })
)

Step 3: Add Mermaid diagrams (3 examples) ​

Each diagram is just Mermaid source code inside a fenced block. You can write these by hand or use AI to draft the Mermaid syntax and then edit it.

Example 1: Request/response flow ​

Source:

text
graph LR
  A[Client] -->|HTTP Request| B(NGINX Frontend)
  B -->|Proxied HTTP Request| C[Upstream App Server]
  C -->|Proxied HTTP Response| B
  B -->|HTTP Response| A

Rendered:

Example 2: Sequence diagram ​

Source:

text
sequenceDiagram
  participant C as Client
  participant N as NGINX
  participant U as Upstream
  C->>N: HTTP Request
  N->>U: Proxy Request
  U-->>N: Response
  N-->>C: Response

Rendered:

Example 3: Mindmap ​

Source:

text
mindmap
  root((Infra Docs))
    VitePress
      config
      theme
    Mermaid
      flowcharts
      sequences
    Ops
      runbooks
      incidents

Rendered:

Verify it works ​

Run the dev server and open the page:

npm run docs:dev

If you see rendered diagrams instead of code fences, you are done.

Troubleshooting VitePress Uncaught SyntaxError: ambiguous indirect export: default ​

If you hit this error, it is tied to older version combinations of the plugin and VitePress:

Uncaught SyntaxError: ambiguous indirect export: default

Track the discussion here: vitepress-plugin-mermaid issue #33

The reliable fix is to add a vite section with:

  • optimizeDeps include list
  • resolve.alias for the dependency that breaks the export

If you are documenting infra and agent workflows with VitePress, these guides are often useful alongside diagrams:

Last updated: