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):

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

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:

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:

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:

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

Related resources

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

• NGINX: capture upstream headers and reuse them in responses
• Disable OpenAI parallel tool calls (multi_tool_use.parallel)
• Mistral Instruct structured output (JSON mode) with llama.cpp