sphinxcontrib-mermaid¶

This extension allows you to embed Mermaid graphs in your documents, including general flowcharts, sequence diagrams, gantt diagrams and more.

Documentation: https://sphinxcontrib-mermaid-demo.readthedocs.io/
Source Code: https://github.com/mgaitan/sphinxcontrib-mermaid

Install¶

pip install sphinxcontrib-mermaid

Then, add the extension to your conf.py:

conf.py¶

extensions = [
    # ...
    "sphinxcontrib.mermaid",
]

Usage¶

It adds a mermaid directive to embed mermaid markup. For example:

.. mermaid::

  sequenceDiagram
      participant Alice
      participant Bob
      Alice->John: Hello John, how are you?
      loop Healthcheck
          John->John: Fight against hypochondria
      end
      Note right of John: Rational thoughts <br/>prevail...
      John-->Alice: Great!
      John->Bob: How about you?
      Bob-->John: Jolly good!

sequenceDiagram participant Alice participant Bob Alice->John: Hello John, how are you? loop Healthcheck John->John: Fight against hypochondria end Note right of John: Rational thoughts <br/>prevail... John-->Alice: Great! John->Bob: How about you? Bob-->John: Jolly good!

Theming¶

To theme your diagrams you can use mermaid_init_js setting:

conf.py¶

mermaid_init_js = """
mermaid.initialize({theme:"forest"});
"""

You can find all the options for mermaid.initialize method with Mermaid Config Schema.

To see the python configuration options checkout: Sphinx Mermaid Config values.

Mermaid not working¶

You may encounter an error of:

Uncaught ReferenceError: mermaid is not defined

Here are some possible fixes:

There will be a requirejs conflict with nbsphinx extension, you can use nbsphinx_requirejs_path setting to resolve the issue:
conf.py¶
```
nbsphinx_requirejs_path = ''
```
Mermaid extension is conflict with jupyter-sphinx too, you can resolve the issue with jupyter_sphinx_require_url setting:
conf.py¶
```
jupyter_sphinx_require_url = ''
```