---
id: mkdocs-mermaid2-plugin
version: "1.2.3"
license: MIT
license_treatment: permissive
maintenance: active
---

# mkdocs-mermaid2-plugin — A MkDocs plugin for including mermaid graphs in markdown sources

License: permissive · Maintenance: active · Downloads: 1.0M/mo

## What it is and what it does

mkdocs-mermaid2-plugin is a MkDocs extension that lets you write Mermaid diagram syntax directly in your markdown source files and have them render as interactive diagrams in the final HTML documentation. It handles inserting the Mermaid JavaScript library and processing the diagram blocks automatically during the MkDocs build.

The plugin works by detecting code blocks marked with the `mermaid` language identifier and converting them into rendered diagrams. It supports all diagram types available in the Mermaid library (flowcharts, sequence diagrams, state diagrams, timelines, and more) and can be configured to use specific versions of the Mermaid library. When used with the Material theme, diagrams automatically adapt their colors to match the site's theme and palette.

Use it for:

- Add flowcharts and architecture diagrams to API documentation without external image files.
- Include sequence diagrams in technical specifications or process documentation.
- Embed state machines or timeline diagrams in software design documents.
- Create class diagrams or entity-relationship diagrams inline within markdown pages.
- Build interactive documentation that renders diagrams on-the-fly in the browser.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A MkDocs plugin that renders Mermaid diagram syntax embedded in markdown into interactive flowcharts, sequence diagrams, pie charts, and other diagram types.

Yes. The plugin is actively maintained, carries no known vulnerabilities, has low install friction, and solves a clear problem—embedding diagrams in markdown documentation. It integrates cleanly with MkDocs and the Material theme. Install it if you want to include Mermaid diagrams in your documentation without managing separate image files.

## Install

pip install mkdocs-mermaid2-plugin
uv add mkdocs-mermaid2-plugin
poetry add mkdocs-mermaid2-plugin

## Installing mkdocs-mermaid2-plugin

Before you install: Low install friction with a pure-Python wheel distribution. The package is actively maintained with a recent commit on 2026-05-14 and carries 286 repository stars, indicating steady community use.

License in practice: Licensed under MIT, a permissive license that allows free use, modification, and distribution with minimal restrictions—suitable for both open-source and commercial projects.

Quickstart:

pip install mkdocs-mermaid2-plugin

Then in mkdocs.yml:
plugins:
  - search
  - mermaid2

In your markdown:
```mermaid
graph LR
    hello --> world
```

Requires mkdocs and Python >= 3.8; the Mermaid JavaScript library must be available (fetched from unpkg by default or specified via configuration).

Verify before relying:

- Whether all diagram types supported by Mermaid versions > 10 are fully functional in practice.
- Performance impact when rendering many diagrams in a single documentation site.
- Compatibility with custom MkDocs themes beyond Material theme.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 1.0M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

mkdocs mermaid diagrams, markdown diagram rendering, mermaid plugin mkdocs, flowchart markdown documentation, embed diagrams in mkdocs, mermaid syntax support, documentation diagram generation, diagram-rendering, documentation-tools, markdown-extension

[View on SkillFed](https://skillfed.io/packages/mkdocs-mermaid2-plugin) · [View on PyPI](https://pypi.org/project/mkdocs-mermaid2-plugin/)