sphinxcontrib-mermaid

sphinxcontrib-mermaid is a Sphinx extension that lets you embed Mermaid diagrams, including flowcharts, sequence diagrams, gantt charts, class diagrams, and more, directly inside your documentation source. You write plain Mermaid markup in a directive and the extension renders it in the generated output.

For the HTML builder it emits a div and injects the Mermaid JavaScript and initialization code so diagrams render in the browser, while other builders can produce static images. It also offers helpers like automatic class-diagram generation from Python modules, giving technical writers a lightweight, text-based way to keep diagrams in version control alongside their docs.

What You Get

• A mermaid directive for embedding flowcharts, sequence, gantt, class, and state diagrams in docs
• HTML output that injects the Mermaid JS runtime and initialization automatically
• Automatic class-diagram generation from Python modules via the autoclassdiag helper
• Configuration hooks for Mermaid version, init parameters, output format, and CSS

Common Use Cases

• Documenting system architecture and workflows with text-based diagrams in Sphinx docs
• Keeping diagram definitions under version control instead of binary image files
• Auto-generating UML class diagrams from a Python codebase’s modules
• Publishing interactive diagrams on Read the Docs and other Sphinx HTML sites

Under The Hood

Architecture - The extension lives under sphinxcontrib/mermaid, with the core in init.py (about 616 lines) defining the Mermaid node, the mermaid directive, and visitor methods for each Sphinx builder that emit either a client-rendered div or a generated image. Jinja2 templates (default.js.j2, default.css.j2, fullscreen.css.j2) supply the injected runtime and styles, autoclassdiag.py builds class diagrams by introspecting Python modules, and exceptions.py defines the extension’s error types. Sphinx discovers it through the standard setup entry point that registers the directive, nodes, and config values.

Tech Stack - Pure Python (3.10+) packaged with Hatchling, depending on sphinx, jinja2, and pyyaml. Rendering in HTML relies on the external Mermaid JavaScript library injected at build time; roughly a third of the repo is Jinja templates for that runtime glue.

Code Quality - The project is mature and actively maintained (355+ commits, about 17 per month) with a tests suite (test_html.py plus fixture roots and a conftest) validating the HTML builder output. Code is organized cleanly by concern across the package modules.

API Design - Authoring is a single intuitive directive, so writers add diagrams with minimal syntax and no code. Configuration is exposed through conventional Sphinx conf.py settings, and the demo docs on Read the Docs plus a thorough README make onboarding straightforward for anyone already using Sphinx.