Sphinxcontrib Mermaid

2.0.1 · active · verified Fri Apr 10

Sphinxcontrib Mermaid (version 2.0.1) is a Sphinx extension that enables embedding Mermaid.js diagrams directly into reStructuredText or Markdown documentation. It allows authors to create various diagrams like flowcharts, sequence diagrams, class diagrams, and Gantt charts using a simple text-based syntax. This approach ensures diagrams are version-controlled, easy to maintain, and rendered consistently with the Sphinx theme. The library is actively maintained, supports Python >=3.10, and is distributed via PyPI.

Warnings

gotcha For non-raw HTML output (PNG, SVG) or when building PDFs, `mermaid-cli` (an npm package) must be installed and accessible. Without it, image rendering will fail. The `mermaid_cmd` configuration option may be needed to specify its path.
Fix: Install `mermaid-cli` globally or locally via npm (`npm install -g @mermaid-js/mermaid-cli`) and optionally configure `mermaid_cmd` in `conf.py` (e.g., `mermaid_cmd = 'npx mmdc'`).
gotcha The default `mermaid_output_format` is 'raw', which renders Mermaid directly in HTML via JavaScript. If you need static images (e.g., for PDF builds or certain HTML themes), you must explicitly set `mermaid_output_format` to 'svg' or 'png' in `conf.py`.
Fix: Add `mermaid_output_format = 'svg'` (or 'png') to your `conf.py`. Remember this also requires `mermaid-cli`.
gotcha Known `requirejs` conflicts exist when using `sphinxcontrib-mermaid` alongside extensions like `nbsphinx` or `jupyter-sphinx`, leading to JavaScript errors where Mermaid may not load.
Fix: Resolve conflicts by adding `nbsphinx_requirejs_path = ''` or `jupyter_sphinx_require_url = ''` to your `conf.py` as appropriate.
deprecated The project is actively seeking new maintainers, which could impact future development and support.
Fix: Monitor the GitHub repository for updates on maintenance status and consider contributing if possible.

Install

pip install sphinxcontrib-mermaid Install latest version

Imports

sphinxcontrib.mermaid
```
extensions = ['sphinxcontrib.mermaid']
```
Add 'sphinxcontrib.mermaid' to the 'extensions' list in your project's conf.py to enable the directive.

Quickstart

After installing the package, add 'sphinxcontrib.mermaid' to your `extensions` list in `conf.py`. Then, use the `.. mermaid::` directive in your reStructuredText or Markdown files to embed Mermaid code. For image output (SVG/PNG) or PDF builds, `mermaid-cli` must also be installed via npm.

# conf.py
import os
import sys
sys.path.insert(0, os.path.abspath('.'))

project = 'My Sphinx Project'
copyright = '2026, Your Name'
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinxcontrib.mermaid',
]

# Optional: configure mermaid output for non-raw formats (requires mermaid-cli)
# mermaid_output_format = 'svg' # or 'png'
# mermaid_cmd = 'npx mmdc' # if mmdc is in node_modules/.bin or globally installed

# Optional: pin mermaid.js version
# mermaid_version = "11.12.1"

# index.rst (or any .rst file)
# Here's a simple flowchart:
#
# .. mermaid::
#    graph TD
#        A[Start] --> B{Decision};
#        B -->|One| C[Process 1];
#        B -->|Two| D[Process 2];
#        C --> E[End];
#        D --> E;
#
# And a sequence diagram:
#
# .. mermaid::
#    sequenceDiagram
#        participant Alice
#        participant Bob
#        Alice->>Bob: Hello Bob, how are you?
#        alt healthy
#            Bob->>Alice: Great!
#        else unwell
#            Bob->>Alice: Not so good :(
#        end
#        Alice->>Bob: Ok, bye!

view raw JSON →