mkdocs-mermaid2-plugin
A MkDocs plugin for including mermaid graphs in markdown sources
Decision gist · record as of 2026-08-14
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.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- Requires mkdocs and Python >= 3.8; the Mermaid JavaScript library must be available (fetched from unpkg by default or specified via configuration).
- 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 · maintenance · safety
MIT (permissive) — Licensed under MIT, a permissive license that allows free use, modification, and distribution with minimal restrictions—suitable for both open-source and commercial projects.
last release 2025-10-17 (301 days) · last repo commit 2026-05-14 · 286 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 1,014,204 downloads/mo, #4,505 on PyPI
Alternatives
Verify before relying
pip install mkdocs-mermaid2-plugin
Then in mkdocs.yml:
plugins:
- search
- mermaid2
In your markdown:
```mermaid
graph LR
hello --> world
```- 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.
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 on it.
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
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.
Requires mkdocs and Python >= 3.8; the Mermaid JavaScript library must be available (fetched from unpkg by default or specified via configuration).
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
```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 the current Python release >=3.8 |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | 6 packagesbeautifulsoup4jsbeautifiermkdocspymdown-extensionsrequestssetuptools |
| Maintenance | Actively maintained 301 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 1,014,204 / month, #4,505 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | Development Status :: 5 - Production/StableIntended Audience :: DevelopersIntended Audience :: Information TechnologyLicense :: OSI Approved :: MIT LicenseProgramming Language :: Python :: 3Programming Language :: Python :: 3.5Programming Language :: Python :: 3.6Programming Language :: Python :: 3.7Programming Language :: Python :: 3.8 |
Evidence: mkdocs_mermaid2_plugin-1.2.3-py3-none-any.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “mkdocs mermaid diagrams”
- mkdocs-mermaid2-pluginA MkDocs plugin that renders Mermaid diagram syntax embedded in…
- mkdocs-panzoom-pluginAdds interactive pan and zoom functionality to images and diagrams…
- mkdocs-kroki-pluginA MkDocs plugin that converts Kroki diagram syntax in Markdown code…
Give your agent the search over MCP, or paste the wish link into any chat.
More Documentation packages
Docutils converts plaintext documentation in reStructuredText format into multiple output formats including HTML, XML, and LaTeX using a modular processing system.
Sphinx generates professional documentation from reStructuredText source files, producing HTML, PDF, EPUB, and other formats with automatic cross-references, code highlighting, and hierarchical navigation.
Griffe extracts the complete structure and signatures of Python programs to generate API documentation or detect breaking changes in your project's public API.
Install it if you need to programmatically inspect Python code structure, generate API docs, or enforce API stability in CI.
A Sphinx extension that outputs documentation in serialized HTML formats (JSON and pickle) alongside standard HTML.
Alabaster is a clean, responsive Sphinx theme for documentation that requires Python 3.10 or newer and Sphinx 6.2 or newer.
A Sphinx extension that generates HTML help files from reStructuredText documentation source.
See also mkdocs-drawio · mkdocs-kroki-plugin · mkdocs-panzoom-plugin · sphinxcontrib-mermaid · mermaid-py · mermaid-builder · paracelsus · django-diagram · mkdocs-print-site-plugin · telegramify-markdown