Install & Compatibility
Where this runs
tested against v1.2.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 43.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.4s · import 0.000s · 45MB
45MB installed
● package 45MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
mermaid2
✓ Configured in mkdocs.yml under 'plugins'
✗ from mkdocs_mermaid2_plugin import ...
This is an MkDocs plugin and is configured in the `mkdocs.yml` file, not imported directly in Python code for typical use. MkDocs loads and uses the plugin internally.
To enable the plugin, add 'mermaid2' to your `plugins` list in `mkdocs.yml`. If you declare any plugin, you must explicitly list all of them, including `search`. For best integration, especially with Material for MkDocs, it's recommended to also configure `pymdownx.superfences` to handle `mermaid` custom fences.
Then, in your Markdown files, use a `mermaid` fenced code block to embed your diagrams.
### mkdocs.yml
plugins:
- search
- mermaid2
markdown_extensions:
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:mermaid2.fence_mermaid_custom
### docs/index.md
# My Project Documentation
Here's a simple flowchart:
```mermaid
graph TD
A[Start] --> B{Process?};
B --> C{Decision};
C --> D[End];
```
Debug
Known issues
deprecatedThe `extra_javascript` parameter in `mkdocs.yml` for specifying the Mermaid JavaScript library is deprecated as the primary method.fixUse the `javascript` parameter directly under the `mermaid2` plugin configuration to specify the URL or path to the Mermaid JS library (e.g., `plugins: - mermaid2: javascript: https://unpkg.com/mermaid/dist/mermaid.min.js`). The plugin will automatically insert the correct calls. `extra_javascript` now serves as a failsafe mechanism only.
affects: >= 1.1.0
gotchaWhen explicitly declaring plugins in `mkdocs.yml`, you must list *all* desired plugins, including default ones like `search`, which would otherwise be implicitly enabled. Failing to do so will deactivate `search`.fixEnsure your `plugins` section explicitly includes all necessary plugins, for example: `plugins: - search - mermaid2`.
affects: All versions
gotchaThe `mkdocs-mermaid2-plugin` is not compatible with `mkdocs-minify-plugin`.fixAvoid using both plugins simultaneously. If minification is critical, consider alternative approaches or themes that offer built-in Mermaid support.
affects: All versions
breakingConfiguration arguments for Mermaid.js versions >= 10.0.0 did not work correctly in plugin versions prior to 1.0.8.fixUpgrade to `mkdocs-mermaid2-plugin` version 1.0.8 or newer to ensure proper handling of Mermaid.js configuration arguments, especially when using Mermaid.js version 10 or greater.
affects: < 1.0.8
gotchaMkDocs versions older than 1.5.0 may have issues correctly calling Mermaid.js ESM (ECMAScript Module) libraries.fixUpgrade your MkDocs installation to version 1.5.0 or newer to ensure proper handling of ESM-formatted Mermaid.js libraries.
affects: < 1.5.0 (MkDocs)
Upgrade
Version history
1.2.3latest on PyPI · released Oct 17, 2025
Audit
Dependencies
mkdocsrequiredCore static site generator for which this is a plugin.
pymdownx-superfencesoptionalRecommended for advanced Markdown fencing (e.g., custom code blocks for Mermaid) in themes like Material for MkDocs.