How to Use Mermaid.js in MkDocs and MkDocs Material (2026 Guide)

# How to Use Mermaid.js in MkDocs and MkDocs Material (2026 Guide)

MkDocs is one of the most popular static-site generators for technical documentation. Combine it with the MkDocs Material theme and you get a polished, searchable docs site with almost zero configuration. Add Mermaid.js to that stack and every diagram you write stays in your repo, version-controlled, and auto-rendered in the browser — no image exports, no external tools.

This guide covers every way to enable Mermaid in MkDocs, including the recommended plugin approach, dark mode support, and solutions to the most common rendering problems.

Two Ways to Enable Mermaid in MkDocs

There are two main approaches:

1. MkDocs Material built-in support (recommended — zero extra dependencies if you're already on Material)
2. mkdocs-mermaid2-plugin (works with any MkDocs theme)

Choose based on which theme you're using. If you're on Material, use the built-in approach. If you're on a different theme, use the plugin.

Approach 1 — MkDocs Material Built-In (Recommended)

MkDocs Material (version 8.2+) ships with native Mermaid support. You don't need any extra packages.

Step 1: Install MkDocs Material

pip install mkdocs-material

If you're starting fresh:

pip install mkdocs-material
mkdocs new my-docs
cd my-docs

Step 2: Enable SuperFences in mkdocs.yml

MkDocs Material renders Mermaid via the SuperFences extension from PyMdown Extensions. Enable it in your mkdocs.yml:

site_name: My Docs
theme:
  name: material

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

That's it. You can now use Mermaid diagrams in any Markdown file.

Step 3: Add a Diagram to Your Docs

In any .md file:

graph TD
    A[User] --> B[MkDocs Site]
    B --> C[Documentation]
    C --> D[Happy Developer]

Run mkdocs serve and open your browser — the diagram renders live.

Approach 2 — mkdocs-mermaid2-plugin

If you're using a different theme (like ReadTheDocs or a custom theme), install the dedicated plugin:

pip install mkdocs-mermaid2-plugin

Then add to mkdocs.yml:

site_name: My Docs

plugins:
  - search
  - mermaid2

Write diagrams in fenced code blocks just as you would anywhere else:

sequenceDiagram
    Alice->>Bob: Hello
    Bob-->>Alice: Hi there!

Dark Mode Support (MkDocs Material)

MkDocs Material supports automatic light/dark mode switching. Mermaid diagrams need to match. Material handles this automatically when you configure color schemes correctly — but there's one thing you must not do.

What to Avoid

Do not load Mermaid via a custom JavaScript snippet or CDN import in extra_javascript. If you do, you break Material's automatic color-scheme switching and diagrams will be stuck in light mode even when dark mode is active.

The built-in SuperFences integration detects the active color scheme and passes the correct Mermaid theme automatically.

Configure Light + Dark Schemes

theme:
  name: material
  palette:
    - scheme: default
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

With this config, diagrams in light mode use Mermaid's default theme, and diagrams in dark mode use the dark theme automatically.

Custom Mermaid Themes Per Diagram

Override the theme for individual diagrams using the %%{init}%% directive:

%%{init: {"theme": "forest"}}%%
graph LR
    A --> B --> C

Available themes: default, dark, forest, neutral, base.

For base (most customizable):

%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#1a73e8", "primaryTextColor": "#fff", "primaryBorderColor": "#174ea6"}}}%%
graph TD
    A[Custom Styled Diagram]

Real-World Diagram Examples for Documentation Sites

API Request Flow (Sequence Diagram)

Place this directly in your API reference docs, right next to the endpoint description:

sequenceDiagram
    participant Client
    participant API
    participant DB

    Client->>API: GET /api/users
    API->>DB: SELECT * FROM users
    DB-->>API: Rows
    API-->>Client: JSON response

System Architecture (Flowchart)

graph TB
    subgraph Frontend
        UI[React App]
    end
    subgraph Backend
        API[FastAPI]
        Worker[Celery Worker]
        Cache[Redis]
    end
    subgraph Data
        DB[(PostgreSQL)]
        S3[S3 Storage]
    end

    UI -->|HTTPS| API
    API --> Cache
    API --> DB
    API --> Worker
    Worker --> S3

Data Model (ER Diagram)

erDiagram
    USER ||--o{ POST : creates
    POST ||--o{ COMMENT : has
    USER ||--o{ COMMENT : writes

    USER {
        int id PK
        string email
        string username
        datetime created_at
    }
    POST {
        int id PK
        int user_id FK
        string title
        text body
        datetime published_at
    }
    COMMENT {
        int id PK
        int user_id FK
        int post_id FK
        text content
    }

Deployment Pipeline (Gantt Chart)

gantt
    title Release Pipeline
    dateFormat YYYY-MM-DD
    axisFormat %b %d

    section Build
    Lint and Type Check   :done, a1, 2026-06-01, 1d
    Unit Tests            :done, a2, after a1, 1d
    Build Docker Image    :done, a3, after a2, 1d

    section Deploy
    Staging Deploy        :active, b1, after a3, 2d
    Smoke Tests           :b2, after b1, 1d
    Production Deploy     :crit, b3, after b2, 1d

Organizing Diagrams in a Larger Docs Site

Put Diagrams Close to Their Content

Don't create a separate "diagrams" page. Embed diagrams directly in the relevant documentation section. A sequence diagram for the auth flow belongs in the auth documentation page — not in a "diagrams gallery."

Use a Text Description Above Each Diagram

Make diagrams accessible and scannable:

The following diagram shows the OAuth 2.0 token exchange flow:

Store Complex Diagrams as .mmd Files

For very complex diagrams that appear in multiple places, store them in a docs/diagrams/ folder as .mmd files and include them via a custom macro or MkDocs plugin. This avoids copy-paste drift when diagrams need updating.

Full mkdocs.yml Reference (MkDocs Material + Mermaid)

Here's a production-ready mkdocs.yml with Mermaid, search, and navigation configured:

site_name: My Project Docs
site_url: https://docs.myproject.com
repo_url: https://github.com/myorg/myproject

theme:
  name: material
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  features:
    - navigation.tabs
    - navigation.sections
    - toc.integrate
    - search.highlight

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.highlight:
      anchor_linenums: true
  - admonition
  - toc:
      permalink: true

plugins:
  - search

Troubleshooting Common Issues

Diagrams Show as Raw Code

Cause: The pymdownx.superfences extension is missing from markdown_extensions, or the custom_fences block is misconfigured.

Fix: Double-check the YAML indentation — it's whitespace-sensitive and a single misplaced space breaks the whole block. Use a YAML linter to validate your config.

Diagrams Render in Light Mode Only (Dark Mode Broken)

Cause: You loaded Mermaid via extra_javascript in addition to the SuperFences config, creating a conflict.

Fix: Remove any Mermaid CDN script from extra_javascript. The SuperFences integration is fully self-contained.

`!!python/name:` Causes a YAML Error

Cause: Some YAML parsers reject the !!python/name: tag when the module path is not importable.

Fix: Ensure pymdownx is installed: pip install pymdownx. The import path must be exactly pymdownx.superfences.fence_code_format.

New Mermaid Syntax Not Rendering

Cause: The mkdocs-mermaid2-plugin bundles a specific Mermaid version and newer syntax (like block-beta or packet) may not be available.

Fix: Pin a newer Mermaid version in your mkdocs.yml:

plugins:
  - mermaid2:
      version: 11.0.0

Deploying MkDocs with Mermaid Diagrams

MkDocs builds to static HTML, deployable to GitHub Pages, Netlify, Vercel, or Cloudflare Pages.

GitHub Actions Deploy

name: Deploy Docs
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install mkdocs-material pymdownx
      - run: mkdocs gh-deploy --force

Mermaid diagrams render client-side in JavaScript, so no special build step is needed. The HTML output includes fenced code blocks with the mermaid class, and the Mermaid library renders them in the visitor's browser.

Why MkDocs + Mermaid Is the Best Docs-as-Code Setup

Other approaches either lock diagrams in binary image files (PNG exports) or require an external tool account (Lucidchart, draw.io Cloud). The MkDocs + Mermaid combination gives you:

• Diagrams as code — version-controlled in the same repo as your docs
• Automatic dark mode — Material theme handles it with zero extra config
• Native Markdown syntax — no shortcodes, no plugins, no learning curve
• Static output — fast, cacheable, deployable anywhere
• Git-friendly — diffs are readable, reviews are meaningful, history is preserved

For developer-facing documentation — APIs, internal tools, open-source libraries — this is one of the highest-leverage documentation setups you can adopt in 2026.

Conclusion

Adding Mermaid to MkDocs takes about five minutes: install Material, add the SuperFences config block to mkdocs.yml, and start writing `mermaid code fences. Every architecture decision, API flow, data model, and deployment pipeline you document becomes a maintainable, version-controlled asset.

Before embedding diagrams in your docs, prototype them in a live editor to see the output instantly.

Try Mermaid diagrams live in our free editor →