mkdocs-mermaid2-plugin

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 on this page — 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

mkdocs-mermaid2-plugin on PyPI

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

Evidence: mkdocs_mermaid2_plugin-1.2.3-py3-none-any.whl

Keywords: markdown, mermaid, mkdocs, python

Tags

More Documentation packages