<div align="center">
# Mkdocs-Mermaid2
[](https://opensource.org/licenses/MIT)
[](https://pypi.org/project/mkdocs-mermaid2-plugin/)
An [MkDocs](https://www.mkdocs.org/) plugin that renders [Mermaid](https://mermaid-js.github.io/mermaid) text descriptions into diagrams (flow charts, sequence diagrams, pie charts, etc.).
</div>
---
* **See the [mkdocs-mermaid2 documentation on Read The Docs](https://mkdocs-mermaid2.readthedocs.io).**
* See the [package on Pypi](https://pypi.org/project/mkdocs-mermaid2-plugin/).
* View the [general Mkdocs documentation](https://www.mkdocs.org/)
> As of version 1.0.0, this plugin works with versions of the Mermaid library > 10,
> **and** with lower versions.
<!-- To update the toc, run the following command:
markdown-toc -i README.md
-->
<!-- toc -->
- [Mkdocs-Mermaid2](#mkdocs-mermaid2)
- [Introduction](#introduction)
- [Installation](#installation)
- [Automatic](#automatic)
- [Manual](#manual)
- [Test](#test)
- [Configuration](#configuration)
- [Basic configuration](#basic-configuration)
- [Specifying the version of the Mermaid library](#specifying-the-version-of-the-mermaid-library)
- [Additional settings for the Material theme](#additional-settings-for-the-material-theme)
- [For more information](#for-more-information)
<!-- tocstop -->
## Introduction
Mermaid2 allows you to insert mermaid markup in the markdown
of your mkdocs pages.
For example, a markdown page containing the following diagram:
```mermaid
graph LR
hello --> world
world --> again
again --> hello
```
will then be displayed in the final HTML page as:
```mermaid
graph LR
hello --> world
world --> again
again --> hello
```
The diagram will be rendered on the fly by the web browser,
with the use of the mermaid javascript library.
mkdocs-mermaid2 takes care of inserting the javascript library into
the html page.
> You can use all the diagrams types supported by the version of the Mermaid
> javascript library that you are using (flowchart, class, state, timeline,
> etc.).
## Installation
### Automatic
```bash
pip install mkdocs-mermaid2-plugin
```
### Manual
Clone this repository in a local directory and install the package:
```bash
python setup.py install
```
### Test
For running the examples the `test` directory,
you will also need the mkdocs-material theme. You may
[install it directly](https://squidfunk.github.io/mkdocs-material/getting-started/),
or use the following command to install the whole package:
```bash
pip install mkdocs-mermaid2-plugin[test]
```
## Configuration
### Basic configuration
To enable this plugin, you need to declare it in your [mkdocs config file](https://www.mkdocs.org/user-guide/configuration/)
(`mkdocs.yml`).
In order to work, the plugin also requires the
[mermaid](https://www.npmjs.com/package/mermaid) javascript
library (in the example below, it fetched from the last version
from the [unpkg](https://unpkg.com/) repository; change the version
no as needed).
```yaml
plugins:
- search
- mermaid2
```
> **Note:** If you declare plugins, you need to declare _all_ of them,
> including `search` (which would otherwise have been installed by default.)
### Specifying the version of the Mermaid library
By default, the plugin selects a version of the Mermaid javascript library
that is known to work (some versions work better than others).
You may specify a different version of the Mermaid library, like so:
```yaml
plugins:
- search
- mermaid2:
version: 10.0.2
```
The plugin will insert the correct call to the javascript library
inside the final HTML page.
### Additional settings for the Material theme
> The [Material theme](https://squidfunk.github.io/mkdocs-material/),
> developed by [squidfunk](https://github.com/squidfunk)
> is not mandatory, but recommended.
**Mermaid diagrams will automatically adapt their colors to the theme
and palette.**
Here are the _additional_ recommended settings in the configuration file:
```yaml
markdown_extensions:
- pymdownx.superfences:
# make exceptions to highlighting of code:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:mermaid2.fence_mermaid_custom
```
> Do not use these additional settings for other themes,
> as diagrams will probably **not** be displayed correctly.
## For more information
See the [documentation on ReadTheDocs](https://mkdocs-mermaid2.readthedocs.io).
Raw data
{
"_id": null,
"home_page": null,
"name": "mkdocs-mermaid2-plugin",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "markdown, mermaid, mkdocs, python",
"author": "Laurent Franceschetti",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/2a/6d/308f443a558b6a97ce55782658174c0d07c414405cfc0a44d36ad37e36f9/mkdocs_mermaid2_plugin-1.2.3.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n# Mkdocs-Mermaid2\n\n\n[](https://opensource.org/licenses/MIT) \n[](https://pypi.org/project/mkdocs-mermaid2-plugin/)\n\n\n\n\nAn [MkDocs](https://www.mkdocs.org/) plugin that renders [Mermaid](https://mermaid-js.github.io/mermaid) text descriptions into diagrams (flow charts, sequence diagrams, pie charts, etc.).\n\n</div>\n\n---\n\n* **See the [mkdocs-mermaid2 documentation on Read The Docs](https://mkdocs-mermaid2.readthedocs.io).**\n* See the [package on Pypi](https://pypi.org/project/mkdocs-mermaid2-plugin/).\n* View the [general Mkdocs documentation](https://www.mkdocs.org/)\n\n\n> As of version 1.0.0, this plugin works with versions of the Mermaid library > 10,\n> **and** with lower versions.\n\n\n<!-- To update the toc, run the following command:\nmarkdown-toc -i README.md \n-->\n\n<!-- toc -->\n\n- [Mkdocs-Mermaid2](#mkdocs-mermaid2)\n - [Introduction](#introduction)\n - [Installation](#installation)\n - [Automatic](#automatic)\n - [Manual](#manual)\n - [Test](#test)\n - [Configuration](#configuration)\n - [Basic configuration](#basic-configuration)\n - [Specifying the version of the Mermaid library](#specifying-the-version-of-the-mermaid-library)\n - [Additional settings for the Material theme](#additional-settings-for-the-material-theme)\n - [For more information](#for-more-information)\n\n<!-- tocstop -->\n\n## Introduction\n\nMermaid2 allows you to insert mermaid markup in the markdown \nof your mkdocs pages.\n\nFor example, a markdown page containing the following diagram:\n\n ```mermaid\n graph LR\n hello --> world\n world --> again\n again --> hello\n ```\n\nwill then be displayed in the final HTML page as:\n\n```mermaid\ngraph LR\n hello --> world\n world --> again\n again --> hello\n```\n\nThe diagram will be rendered on the fly by the web browser,\nwith the use of the mermaid javascript library. \nmkdocs-mermaid2 takes care of inserting the javascript library into\nthe html page.\n\n> You can use all the diagrams types supported by the version of the Mermaid \n> javascript library that you are using (flowchart, class, state, timeline, \n> etc.).\n\n\n## Installation\n\n### Automatic\n\n\n```bash\npip install mkdocs-mermaid2-plugin\n```\n\n### Manual\nClone this repository in a local directory and install the package:\n\n```bash\npython setup.py install\n```\n\n### Test\nFor running the examples the `test` directory, \nyou will also need the mkdocs-material theme. You may \n[install it directly](https://squidfunk.github.io/mkdocs-material/getting-started/),\nor use the following command to install the whole package:\n\n```bash\npip install mkdocs-mermaid2-plugin[test]\n```\n\n\n\n\n\n## Configuration\n\n### Basic configuration\nTo enable this plugin, you need to declare it in your [mkdocs config file](https://www.mkdocs.org/user-guide/configuration/)\n(`mkdocs.yml`).\n\nIn order to work, the plugin also requires the\n[mermaid](https://www.npmjs.com/package/mermaid) javascript\nlibrary (in the example below, it fetched from the last version\nfrom the [unpkg](https://unpkg.com/) repository; change the version\nno as needed).\n\n```yaml\nplugins:\n - search\n - mermaid2\n```\n> **Note:** If you declare plugins, you need to declare _all_ of them, \n> including `search` (which would otherwise have been installed by default.)\n\n\n### Specifying the version of the Mermaid library\n\n\nBy default, the plugin selects a version of the Mermaid javascript library\nthat is known to work (some versions work better than others).\n\nYou may specify a different version of the Mermaid library, like so:\n\n```yaml\nplugins:\n - search\n - mermaid2:\n version: 10.0.2\n```\n\nThe plugin will insert the correct call to the javascript library\ninside the final HTML page.\n\n### Additional settings for the Material theme\n\n\n> The [Material theme](https://squidfunk.github.io/mkdocs-material/), \n> developed by [squidfunk](https://github.com/squidfunk)\n> is not mandatory, but recommended.\n\n**Mermaid diagrams will automatically adapt their colors to the theme\nand palette.**\n\nHere are the _additional_ recommended settings in the configuration file:\n\n```yaml\nmarkdown_extensions:\n - pymdownx.superfences:\n # make exceptions to highlighting of code:\n custom_fences:\n - name: mermaid\n class: mermaid\n format: !!python/name:mermaid2.fence_mermaid_custom\n\n```\n\n> Do not use these additional settings for other themes, \n> as diagrams will probably **not** be displayed correctly. \n\n\n## For more information\nSee the [documentation on ReadTheDocs](https://mkdocs-mermaid2.readthedocs.io).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A MkDocs plugin for including mermaid graphs in markdown sources",
"version": "1.2.3",
"project_urls": {
"Homepage": "https://github.com/fralau/mkdocs-mermaid2-plugin"
},
"split_keywords": [
"markdown",
" mermaid",
" mkdocs",
" python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1a4b6fd6dd632019b7f522f1b1f794ab6115cd79890330986614be56fd18f0eb",
"md5": "bdb14067390ff2e1630d5e7aab366c18",
"sha256": "33f60c582be623ed53829a96e19284fc7f1b74a1dbae78d4d2e47fe00c3e190d"
},
"downloads": -1,
"filename": "mkdocs_mermaid2_plugin-1.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bdb14067390ff2e1630d5e7aab366c18",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 17299,
"upload_time": "2025-10-17T19:38:51",
"upload_time_iso_8601": "2025-10-17T19:38:51.874116Z",
"url": "https://files.pythonhosted.org/packages/1a/4b/6fd6dd632019b7f522f1b1f794ab6115cd79890330986614be56fd18f0eb/mkdocs_mermaid2_plugin-1.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2a6d308f443a558b6a97ce55782658174c0d07c414405cfc0a44d36ad37e36f9",
"md5": "ee0300c623f5eb521c9af9b6e7455c1e",
"sha256": "fb6f901d53e5191e93db78f93f219cad926ccc4d51e176271ca5161b6cc5368c"
},
"downloads": -1,
"filename": "mkdocs_mermaid2_plugin-1.2.3.tar.gz",
"has_sig": false,
"md5_digest": "ee0300c623f5eb521c9af9b6e7455c1e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 16220,
"upload_time": "2025-10-17T19:38:53",
"upload_time_iso_8601": "2025-10-17T19:38:53.047304Z",
"url": "https://files.pythonhosted.org/packages/2a/6d/308f443a558b6a97ce55782658174c0d07c414405cfc0a44d36ad37e36f9/mkdocs_mermaid2_plugin-1.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-17 19:38:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fralau",
"github_project": "mkdocs-mermaid2-plugin",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-mermaid2-plugin"
}
JSON
