sphinxcontrib-mermaid

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

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:

  1. 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 = ''
    
  2. 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 = ''