Registry / serialization / sphinxcontrib-mermaid

sphinxcontrib-mermaid

library2.1.0pypypi✓ verified 23d ago

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.

serialization

pip install sphinxcontrib-mermaid

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · SPHINXCONTRIB-MERM

sphinxcontrib-mermaid

serializationpythonv2.1.0

Install

5.4s avg

Import

—

Disk

97MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.1.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 94.6MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 5.4s · import 0.000s · 96MB

97MB installed

● package 97MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

sphinxcontrib.mermaid

✓ extensions = ['sphinxcontrib.mermaid']

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

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!

Debug

Known issues

gotchaFor 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'`).

affects: All versions

gotchaThe 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`.

affects: All versions

gotchaKnown `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.

affects: All versions

deprecatedThe 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.

affects: 2.0.1 onwards

Upgrade

Version history

2.1.0latest on PyPI · released Jul 18, 2026

Audit

Dependencies

SphinxrequiredCore documentation generator, this is a Sphinx extension.

mermaid-clioptionalRequired for rendering Mermaid diagrams to image formats (PNG/SVG) and for PDF builds. Must be installed via npm.

myst-parseroptionalRequired for embedding Mermaid diagrams within Markdown files in Sphinx projects.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/mgaitan/sphinxcontrib-mermaid ↗

packagehttps://pypi.org/project/sphinxcontrib-mermaid/ ↗

changeloghttps://github.com/mgaitan/sphinxcontrib-mermaid/blob/master/CHANGELOG.md ↗