MkDocs Mermaid2 Plugin

1.2.3 · active · verified Sat Apr 11

An MkDocs plugin (current version 1.2.3) for seamlessly embedding Mermaid.js diagrams within Markdown source files, rendering them dynamically in your generated documentation. It is actively maintained with regular updates, enabling complex diagrams like flowcharts, sequence diagrams, and gantt charts directly in your MkDocs site.

Warnings

deprecated The `extra_javascript` parameter in `mkdocs.yml` for specifying the Mermaid JavaScript library is deprecated as the primary method.
Fix: Use 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.
gotcha When 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`.
Fix: Ensure your `plugins` section explicitly includes all necessary plugins, for example: `plugins: - search - mermaid2`.
gotcha The `mkdocs-mermaid2-plugin` is not compatible with `mkdocs-minify-plugin`.
Fix: Avoid using both plugins simultaneously. If minification is critical, consider alternative approaches or themes that offer built-in Mermaid support.
breaking Configuration arguments for Mermaid.js versions >= 10.0.0 did not work correctly in plugin versions prior to 1.0.8.
Fix: Upgrade 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.
gotcha MkDocs versions older than 1.5.0 may have issues correctly calling Mermaid.js ESM (ECMAScript Module) libraries.
Fix: Upgrade your MkDocs installation to version 1.5.0 or newer to ensure proper handling of ESM-formatted Mermaid.js libraries.

Install

pip install mkdocs-mermaid2-plugin Install latest version

Imports

mermaid2
```
Configured in mkdocs.yml under 'plugins'
```
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.

Quickstart

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 --&gt; C{Decision};
    C --&gt; D[End];
```

view raw JSON →