<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/3e/1a/f580733da1924ebc9b4bb04a34ca63ae62a50b0e62eeb016e78d9dee6d69/mkdocs_mermaid2_plugin-1.2.1.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.1",
"project_urls": {
"Homepage": "https://github.com/fralau/mkdocs-mermaid2-plugin"
},
"split_keywords": [
"markdown",
" mermaid",
" mkdocs",
" python"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "24cec8a41cb0f3044990c8afbdc20c853845a9e940995d4e0cffecafbb5e927b",
"md5": "6efb527fac58dd9ab170e49b469ac546",
"sha256": "22d2cf2c6867d4959a5e0903da2dde78d74581fc0b107b791bc4c7ceb9ce9741"
},
"downloads": -1,
"filename": "mkdocs_mermaid2_plugin-1.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6efb527fac58dd9ab170e49b469ac546",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 17260,
"upload_time": "2024-11-02T06:27:34",
"upload_time_iso_8601": "2024-11-02T06:27:34.652277Z",
"url": "https://files.pythonhosted.org/packages/24/ce/c8a41cb0f3044990c8afbdc20c853845a9e940995d4e0cffecafbb5e927b/mkdocs_mermaid2_plugin-1.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3e1af580733da1924ebc9b4bb04a34ca63ae62a50b0e62eeb016e78d9dee6d69",
"md5": "f71a9477c9e429151710215d5c92621c",
"sha256": "9c7694c73a65905ac1578f966e5c193325c4d5a5bc1836727e74ac9f99d0e921"
},
"downloads": -1,
"filename": "mkdocs_mermaid2_plugin-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "f71a9477c9e429151710215d5c92621c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 16104,
"upload_time": "2024-11-02T06:27:36",
"upload_time_iso_8601": "2024-11-02T06:27:36.302098Z",
"url": "https://files.pythonhosted.org/packages/3e/1a/f580733da1924ebc9b4bb04a34ca63ae62a50b0e62eeb016e78d9dee6d69/mkdocs_mermaid2_plugin-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-02 06:27:36",
"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
