sphinxcontrib-mermaid

What it is and what it does

sphinxcontrib-mermaid is a Sphinx extension that lets you write Mermaid diagram syntax directly in your reStructuredText or Markdown documentation and have them render as interactive diagrams in the final HTML output. It integrates with Sphinx's build pipeline and depends on Jinja2, PyYAML, and Sphinx itself to process and embed the diagrams.

The extension is useful when you want to include flowcharts, sequence diagrams, Gantt charts, and other visual representations in technical documentation without manually creating image files. You write the diagram definition in plain text using Mermaid's syntax, and the extension handles conversion to rendered graphics during the Sphinx build.

Use it for:

• Add flowcharts and process diagrams to API documentation or architecture guides.
• Include sequence diagrams in technical specifications or protocol documentation.
• Embed Gantt charts in project planning or timeline documentation.
• Create state machine diagrams for explaining system behavior or workflows.
• Build interactive diagrams that render consistently across all documentation builds.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Embeds Mermaid diagrams (flowcharts, sequence diagrams, Gantt charts, and more) directly into Sphinx-generated documentation.

Yes. The package is actively maintained, has low install friction, carries no known vulnerabilities, uses a permissive license, and solves a clear documentation need. It is well-suited for any Sphinx-based project that benefits from embedded diagrams. Install it if you are using Sphinx and want to include Mermaid diagrams without managing separate image files.

Install

sphinxcontrib-mermaid on PyPI

pip install sphinxcontrib-mermaid

uv add sphinxcontrib-mermaid

poetry add sphinxcontrib-mermaid

Installing sphinxcontrib-mermaid

Before you install

Low install friction with three straightforward runtime dependencies. Actively maintained with a recent release 27 days ago and ongoing commits; the repository has 409 stars and is not archived.

License in practice

BSD-2-Clause is permissive, allowing commercial and private use with minimal restrictions beyond retaining the license notice.

Quickstart

pip install sphinxcontrib-mermaid

# In conf.py:
extensions = ['sphinxcontrib.mermaid']

# In your .rst file:
.. mermaid::

   graph LR
      A --> B

Requires Python 3.10 or later; Sphinx must be installed and configured in your documentation project.

Verify before relying

• Whether Mermaid JavaScript library is automatically bundled or requires separate installation in the build environment.
• Support for all Mermaid diagram types (e.g., state diagrams, class diagrams, entity-relationship diagrams) beyond those mentioned in the description.

Package facts

Evidence: sphinxcontrib_mermaid-2.1.0-py3-none-any.whl

Keywords: diagrams, documentation, mermaid, sphinx

Tags

More Utilities packages