How to Enable Mermaid Diagram Support in Docusaurus: A Complete Configuration Guide

Enable Mermaid diagram support in Docusaurus by setting markdown.mermaid: true in your site configuration and adding the @docusaurus/theme-mermaid plugin to your plugins array.

Docusaurus, the popular open-source documentation framework maintained by Meta, provides native support for rendering Mermaid diagrams directly from markdown. Enabling Mermaid diagram support in Docusaurus requires specific configuration changes in your docusaurus.config.ts file to activate the markdown processor flag and register the official theme plugin. Once configured, fenced code blocks marked with the mermaid language automatically render as SVG diagrams that respect your site's light and dark color modes.

Step 1 — Enable the Mermaid Flag in Site Configuration

According to the source code in packages/docusaurus/src/server/configValidation.ts, the markdown.mermaid option defaults to false at line 126 and is defined in the validation schema at line 486. You must explicitly enable this flag to instruct the MDX loader to treat mermaid fenced code blocks as diagram sources.

Add the following to your docusaurus.config.ts:

export default {
  // ... other config
  markdown: {
    mermaid: true, // Enables Mermaid diagram processing
  },
  // ... rest of config
};

Step 2 — Add the Official Mermaid Theme Plugin

The @docusaurus/theme-mermaid package supplies the client-side rendering logic required to convert Mermaid syntax into SVG graphics. As implemented in the official Docusaurus repository at website/docusaurus.config.ts (line 489), you must register this plugin in your plugins array.

First, install the package:

npm install @docusaurus/theme-mermaid

Then register it in your configuration:

export default {
  plugins: [
    '@docusaurus/theme-mermaid',
    // ... other plugins
  ],
};

Step 3 — Configure Mermaid Themes and Options

The plugin exposes a themeConfig.mermaid object for customizing diagram appearance. The TypeScript definitions in packages/docusaurus-theme-mermaid/src/theme-mermaid.d.ts (lines 10-21) specify that you can configure separate themes for light and dark modes and pass any valid Mermaid-JS options.

export default {
  themeConfig: {
    mermaid: {
      theme: {
        light: 'default', // Mermaid theme for light mode
        dark: 'dark',     // Mermaid theme for dark mode
      },
      options: {
        startOnLoad: false,
        securityLevel: 'loose',
        // ... other Mermaid-JS configuration
      },
    },
  },
};

How Mermaid Rendering Works Internally

The diagram rendering process involves two distinct stages. First, the remark plugin located at packages/docusaurus-mdx-loader/src/remark/mermaid/index.ts parses markdown files and transforms fenced code blocks marked with mermaid into custom <mermaid> JSX elements with type: 'mermaidCodeBlock'.

On the client side, packages/docusaurus-theme-mermaid/src/client/loadMermaid.ts dynamically imports the mermaid library (and optionally @mermaid-js/layout-elk) and invokes mermaid.render() to generate the SVG output. The rendered diagram is injected into a container with the CSS class docusaurus-mermaid-container, which automatically adapts to the current color mode by swapping the configured Mermaid theme.

Writing Mermaid Diagrams in Markdown

Once configured, create diagrams using standard fenced code blocks with the mermaid language identifier:

# System Architecture

```mermaid
graph LR
  A[Client] --> B[Server]
  B --> C[Database]
  C --> D[Cache]

The MDX processor automatically converts this block into an interactive SVG diagram that renders during page load.

## Summary

- **Enable the markdown flag**: Set `markdown.mermaid: true` in [`docusaurus.config.ts`](https://github.com/facebook/docusaurus/blob/main/docusaurus.config.ts) (defaults to `false` per [`configValidation.ts`](https://github.com/facebook/docusaurus/blob/main/configValidation.ts))
- **Register the plugin**: Add `@docusaurus/theme-mermaid` to your `plugins` array as shown in the official website configuration
- **Customize themes**: Use `themeConfig.mermaid` to define separate light and dark themes and pass Mermaid-JS options
- **Write diagrams**: Use fenced code blocks with the `mermaid` language tag in your markdown files
- **Client-side rendering**: The remark plugin transforms blocks to JSX, and [`loadMermaid.ts`](https://github.com/facebook/docusaurus/blob/main/loadMermaid.ts) handles lazy-loading and SVG generation with automatic theme switching

## Frequently Asked Questions

### Is Mermaid support enabled by default in Docusaurus?

No. According to [`packages/docusaurus/src/server/configValidation.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus/src/server/configValidation.ts), the `markdown.mermaid` configuration option defaults to `false`. You must explicitly set it to `true` and register the theme plugin to enable diagram rendering.

### What Docusaurus plugin is required for Mermaid diagrams?

You must install and register `@docusaurus/theme-mermaid` in the `plugins` array of your [`docusaurus.config.ts`](https://github.com/facebook/docusaurus/blob/main/docusaurus.config.ts) file. This plugin provides the client-side components that render Mermaid syntax into SVG graphics.

### Can I use different Mermaid themes for light and dark mode?

Yes. The `themeConfig.mermaid.theme` object accepts separate `light` and `dark` properties where you can specify any valid Mermaid theme name (such as `default`, `dark`, `forest`, or `neutral`). The renderer automatically switches themes based on the site's current color mode.

### Why are my Mermaid code blocks rendering as plain text instead of diagrams?

This occurs when the `markdown.mermaid` flag is `false` or the `@docusaurus/theme-mermaid` plugin is not registered. Verify both configuration steps are complete and restart your development server to ensure the MDX loader processes the `mermaid` language identifier correctly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}