{"id":4118,"library":"mkdocs-mermaid2-plugin","title":"MkDocs Mermaid2 Plugin","description":"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.","status":"active","version":"1.2.3","language":"en","source_language":"en","source_url":"https://github.com/fralau/mkdocs-mermaid2-plugin","tags":["mkdocs","mermaid","plugin","documentation","markdown"],"install":[{"cmd":"pip install mkdocs-mermaid2-plugin","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core static site generator for which this is a plugin.","package":"mkdocs"},{"reason":"Recommended for advanced Markdown fencing (e.g., custom code blocks for Mermaid) in themes like Material for MkDocs.","package":"pymdownx-superfences","optional":true}],"imports":[{"note":"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.","wrong":"from mkdocs_mermaid2_plugin import ...","symbol":"mermaid2","correct":"Configured in mkdocs.yml under 'plugins'"}],"quickstart":{"code":"### mkdocs.yml\nplugins:\n  - search\n  - mermaid2\nmarkdown_extensions:\n  - pymdownx.superfences:\n      custom_fences:\n        - name: mermaid\n          class: mermaid\n          format: !!python/name:mermaid2.fence_mermaid_custom\n\n### docs/index.md\n# My Project Documentation\n\nHere's a simple flowchart:\n\n```mermaid\ngraph TD\n    A[Start] --> B{Process?};\n    B --&gt; C{Decision};\n    C --&gt; D[End];\n```","lang":"yaml","description":"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.\n\nThen, in your Markdown files, use a `mermaid` fenced code block to embed your diagrams."},"warnings":[{"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.","message":"The `extra_javascript` parameter in `mkdocs.yml` for specifying the Mermaid JavaScript library is deprecated as the primary method.","severity":"deprecated","affected_versions":">= 1.1.0"},{"fix":"Ensure your `plugins` section explicitly includes all necessary plugins, for example: `plugins: - search - mermaid2`.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Avoid using both plugins simultaneously. If minification is critical, consider alternative approaches or themes that offer built-in Mermaid support.","message":"The `mkdocs-mermaid2-plugin` is not compatible with `mkdocs-minify-plugin`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Configuration arguments for Mermaid.js versions >= 10.0.0 did not work correctly in plugin versions prior to 1.0.8.","severity":"breaking","affected_versions":"< 1.0.8"},{"fix":"Upgrade your MkDocs installation to version 1.5.0 or newer to ensure proper handling of ESM-formatted Mermaid.js libraries.","message":"MkDocs versions older than 1.5.0 may have issues correctly calling Mermaid.js ESM (ECMAScript Module) libraries.","severity":"gotcha","affected_versions":"< 1.5.0 (MkDocs)"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}