Getting Started

Get up and running with VitePress Mermaid in minutes.

Choose Your Starting Point

Scenario	Recommended Approach	Description
Creating a new project	CLI Tool	Scaffold a pre-configured project with sample diagrams
Existing VitePress project	Manual Integration	Install and configure the plugin in your existing project

Option 1: Scaffold with CLI

Use the create-vitepress-mermaid CLI tool to create a new pre-configured project:

pnpm

pnpm create @unify-js/vitepress-mermaid

npm

npm create @unify-js/vitepress-mermaid

yarn

yarn create @unify-js/vitepress-mermaid

After creation, follow the instructions to install dependencies and start the dev server:

cd <project-name>
npm install  # or pnpm install, yarn
npm run dev  # or pnpm dev, yarn dev

The generated project includes sample Mermaid diagrams and complete TypeScript configuration.

Option 2: Integrate into Existing Project

Installation

Install the plugin using your preferred package manager:

pnpm

pnpm add -D @unify-js/vitepress-mermaid

npm

npm install -D @unify-js/vitepress-mermaid

yarn

yarn add -D @unify-js/vitepress-mermaid

Dependency Requirements

This custom theme requires the following dependencies to work properly. Please make sure they are installed:

pnpm add -D vitepress mermaid

Configuration

Step 1: Configure VitePress Config

Create or edit your .vitepress/config.ts file:

import { defineConfig } from 'vitepress';
import vitepressMermaidConfig from '@unify-js/vitepress-mermaid/config';

export default defineConfig({
  extends: vitepressMermaidConfig,
  // Your VitePress config
});

Step 2: Configure the Theme

Create or edit your .vitepress/theme/index.ts file:

import type { Theme } from 'vitepress';
import { MermaidTheme } from '@unify-js/vitepress-mermaid';
import '@unify-js/vitepress-mermaid/style.css';

export default {
  extends: MermaidTheme,
} satisfies Theme;

Usage

Once configured, you can use Mermaid diagrams in your Markdown files:

```mermaid
graph TD
  A[Start] --> B{Decision}
  B -->|Yes| C[Action 1]
  B -->|No| D[Action 2]
  C --> E[End]
  D --> E
```

This will render as:

Loading diagram...

Click on the diagram above to open the fullscreen preview!

Interactive Preview

How to Use

1. Click on any diagram in your documentation
2. The diagram opens in fullscreen mode
3. Use your mouse wheel or keyboard to zoom
4. Drag to pan around the diagram
5. Press ESC or click the X to close

Example: Complex Diagram

Try interacting with this larger diagram:

Loading diagram...

Click the diagram above to explore it in fullscreen!

Show Source Code

Use mermaid-example to display both the diagram and its source:

```mermaid-example
graph LR
    A[Input] --> B[Process]
    B --> C[Output]
```

Loading diagram...

graph LR
    A[Input] --> B[Process]
    B --> C[Output]