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

> Easily enable Mermaid diagram support in Docusaurus. Follow our complete guide to configure mermaid true and add the Docusaurus mermaid plugin for stunning visual documentation.

- Repository: [Meta/docusaurus](https://github.com/facebook/docusaurus)
- Tags: how-to-guide
- Published: 2026-03-04

---

**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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/docusaurus.config.ts):

```typescript
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`](https://github.com/facebook/docusaurus/blob/main/website/docusaurus.config.ts) (line 489), you must register this plugin in your `plugins` array.

First, install the package:

```bash
npm install @docusaurus/theme-mermaid

```

Then register it in your configuration:

```typescript
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`](https://github.com/facebook/docusaurus/blob/main/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.

```typescript
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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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:

```markdown

# 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.