Adding Mermaid Diagrams to Docusaurus Documentation

Introduction

Docusaurus is a popular documentation framework built by Meta, used by many open-source projects and companies. Adding Mermaid diagrams to your Docusaurus site enhances documentation with visual architecture overviews, API flows, and system diagrams — all maintained as code.

This guide covers the complete setup process, from installing the plugin to advanced theming and practical examples.

Setting Up the Mermaid Plugin

Docusaurus has an official Mermaid theme package that integrates seamlessly with its MDX-based content system.

Step 1: Install the Package

npm install @docusaurus/theme-mermaid

Or if you're using yarn:

yarn add @docusaurus/theme-mermaid

Step 2: Configure docusaurus.config.js

Add the Mermaid theme to your configuration:

// docusaurus.config.js
module.exports = {
  // Enable Mermaid markdown support
  markdown: {
    mermaid: true,
  },
  // Add the Mermaid theme
  themes: ['@docusaurus/theme-mermaid'],
  // Optional: configure Mermaid
  themeConfig: {
    mermaid: {
      theme: {
        light: 'neutral',
        dark: 'dark',
      },
      options: {
        maxTextSize: 50000,
      },
    },
  },
};

Step 3: Restart Your Dev Server

npm run start

That's it! Mermaid diagrams will now render in your documentation.

Using Mermaid in MDX Files

Once configured, use Mermaid in any .md or .mdx file with standard code fences:

## System Architecture

graph TB

Client --> API

API --> Database

API --> Cache

The diagram renders automatically in both development and production builds.

In MDX Components

You can also use Mermaid inside MDX components:

import Mermaid from '@theme/Mermaid';

export const ArchitectureDiagram = () => (
  <Mermaid
    value={`
      graph TD
        A[Frontend] --> B[API Gateway]
        B --> C[Service A]
        B --> D[Service B]
    `}
  />
);

Practical Examples for Documentation

API Reference with Sequence Diagrams

In your API documentation, show request flows:

sequenceDiagram
    participant Client
    participant Gateway as API Gateway
    participant Auth as Auth Service
    participant API as Core API
    participant DB as Database

    Client->>Gateway: POST /api/v1/users
    Gateway->>Auth: Validate API key
    Auth-->>Gateway: Valid
    Gateway->>API: Forward request
    API->>DB: INSERT user
    DB-->>API: Created
    API-->>Gateway: 201 Created
    Gateway-->>Client: 201 + User object

Architecture Overview

For your project's landing documentation page:

graph TB
    subgraph "Client Applications"
        Web[Web Dashboard]
        CLI[CLI Tool]
        SDK[SDKs]
    end
    subgraph "API Layer"
        Gateway[API Gateway]
        RateLimit[Rate Limiter]
    end
    subgraph "Services"
        UserSvc[User Service]
        DataSvc[Data Service]
        NotifSvc[Notification Service]
    end
    subgraph "Data Stores"
        PG[(PostgreSQL)]
        Redis[(Redis)]
        S3[(S3 Storage)]
    end

    Web & CLI & SDK --> Gateway
    Gateway --> RateLimit
    RateLimit --> UserSvc & DataSvc & NotifSvc
    UserSvc --> PG
    DataSvc --> PG & S3
    NotifSvc --> Redis

Database Schema Documentation

Document your data model in the schema reference section:

erDiagram
    ORGANIZATION ||--o{ TEAM : has
    TEAM ||--o{ USER : contains
    USER ||--o{ API_KEY : owns
    USER ||--o{ PROJECT : creates
    PROJECT ||--o{ RESOURCE : manages

    ORGANIZATION {
        uuid id PK
        string name
        string plan
        datetime created_at
    }
    USER {
        uuid id PK
        string email UK
        string role
        uuid org_id FK
    }
    API_KEY {
        uuid id PK
        string key_hash UK
        string name
        datetime expires_at
        uuid user_id FK
    }

Plugin Architecture

Document your plugin or extension system:

classDiagram
    class PluginManager {
        +register(plugin) void
        +unregister(name) void
        +getPlugin(name) Plugin
        +executeHook(hook, data) any
    }
    class Plugin {
        <<interface>>
        +name: string
        +version: string
        +initialize() void
        +destroy() void
    }
    class AuthPlugin {
        +name: "auth"
        +initialize() void
        +validateToken(token) bool
    }
    class LoggingPlugin {
        +name: "logging"
        +initialize() void
        +log(level, message) void
    }

    PluginManager "1" --> "*" Plugin : manages
    Plugin <|.. AuthPlugin
    Plugin <|.. LoggingPlugin

Theming Mermaid Diagrams

Matching Docusaurus Themes

Docusaurus supports light and dark modes, and the Mermaid plugin can automatically switch themes:

themeConfig: {
  mermaid: {
    theme: {
      light: 'neutral',
      dark: 'dark',
    },
  },
},

Available Mermaid themes:

• default — Blue and gray palette
• neutral — Monochrome, professional (recommended for docs)
• dark — Dark background (for dark mode)
• forest — Green palette
• base — Minimal, customizable with CSS variables

Custom Theme Variables

For brand-aligned diagrams:

themeConfig: {
  mermaid: {
    theme: {
      light: 'base',
      dark: 'dark',
    },
    options: {
      themeVariables: {
        primaryColor: '#4f46e5',
        primaryTextColor: '#ffffff',
        primaryBorderColor: '#3730a3',
        lineColor: '#6366f1',
        secondaryColor: '#e0e7ff',
        tertiaryColor: '#f5f3ff',
      },
    },
  },
},

Per-Diagram Themes

Override the global theme for specific diagrams:

%%{init: {'theme': 'forest'}}%%
graph TD
    A[This diagram] --> B[uses forest theme]
    B --> C[regardless of global config]

Advanced Configuration

Custom Fonts

Match your documentation's font:

mermaid: {
  options: {
    fontFamily: 'Inter, system-ui, sans-serif',
    fontSize: 14,
  },
},

Security Configuration

For documentation sites that accept user-contributed content:

mermaid: {
  options: {
    securityLevel: 'strict',
    maxTextSize: 10000,
  },
},

Security levels:

• strict — HTML tags are encoded (recommended for public docs)
• loose — HTML tags are allowed in labels
• antiscript — HTML tags allowed but script tags removed
• sandbox — Maximum security, renders in iframe

Handling Large Diagrams

For documentation with complex architecture diagrams:

mermaid: {
  options: {
    maxTextSize: 100000,
    flowchart: {
      useMaxWidth: true,
      htmlLabels: true,
      curve: 'basis',
    },
    sequence: {
      useMaxWidth: true,
      wrap: true,
    },
  },
},

Versioned Documentation

Docusaurus supports documentation versioning, which works perfectly with Mermaid diagrams. Since diagrams are text-based, they're automatically included in version snapshots.

When your architecture changes between versions, the corresponding diagrams in each version remain accurate:

- docs/v1.0/architecture.md → Old architecture diagram

- docs/v2.0/architecture.md → Updated architecture diagram

Each version maintains its own diagrams without any extra configuration.

Performance Considerations

Build Time

Mermaid diagrams are rendered client-side (in the browser), not during the build process. This means:

- Build times aren't affected by the number of diagrams.

- Diagrams render after page load, which may cause a brief flash.

- Complex diagrams may take a moment to render on slower devices.

Lazy Loading

For pages with many diagrams, consider using Docusaurus's tab components to lazy-load diagram sections:

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="overview" label="Overview">
    Overview diagram here
  </TabItem>
  <TabItem value="detailed" label="Detailed">
    Detailed diagram here
  </TabItem>
</Tabs>

Common Issues

Diagram Not Rendering

1. Ensure markdown.mermaid: true is set in your config.
2. Verify @docusaurus/theme-mermaid is in the themes array.
3. Check that the code fence language is exactly mermaid.
4. Restart the dev server after configuration changes.

Theme Mismatch

If diagrams look wrong in dark mode, make sure you've configured both light and dark themes in your config. The neutral and dark combination works well for most documentation sites.

Syntax Errors

Mermaid will show an error message if the syntax is invalid. Test your diagrams in an online Mermaid editor before adding them to your docs.

Best Practices for Docusaurus Documentation

1. Use the neutral theme for light mode — it's the most professional-looking for documentation.

1. Place architecture diagrams early in your docs. The "Overview" or "Getting Started" page should include a high-level system diagram.

1. Add diagrams to API references. Sequence diagrams showing request/response flows are invaluable for API consumers.

1. Document your database schema with ER diagrams. Keep them in a dedicated "Data Model" page.

1. Use consistent styling. Pick a Mermaid theme and stick with it across all your documentation pages.

1. Add text descriptions. Don't rely solely on diagrams. Include text explaining what the diagram shows for accessibility and SEO.

1. Keep diagrams up to date. Since they're text-based and live in your docs repo, update them in the same PR that changes the code.

Conclusion

Mermaid diagrams in Docusaurus transform technical documentation from walls of text into visual, scannable references. The setup is straightforward, theming is flexible, and because diagrams are code, they version and review just like any other documentation change. Start with an architecture overview diagram and expand to API flows, data models, and state machines as your documentation grows.

Test your Mermaid diagrams in our free online editor →