sphinxcontrib-mermaid - sphinxcontrib-mermaid documentation
This extension allows you to embed Mermaid graphs in your documents, including general flowcharts, sequence and gantt diagrams.
It adds a directive to embed mermaid markup. For example:
Alice->John: Hello John, how are you?
John->John: Fight against hypochondria
Note right of John: Rational thoughts <br/>prevail...
John->Bob: How about you?
Bob-->John: Jolly good!
For other builders (or if mermaid_output_format config variable is set differently), the extension will use mermaid-cli to render as to a PNG or SVG image, and then used in the proper code. [graph]
You can also embed external mermaid files, by giving the file name as an argument to the directive and no additional content:
.. mermaid:: path/to/mermaid-gantt-code.mmd
As for all file references in Sphinx, if the filename is not absolute, it is taken as relative to the source directory.
In addition, you can use mermaid to automatically generate a diagram to show the class inheritance using the directive autoclasstree. It accepts one or more fully qualified names to a class or a module. In the case of a module, all the class found will be included.
Of course, these objects need to be importable to make its diagram.
If an optional attribute :full: is given, it will show the complete hierarchy of each class.
The option :namespace: <value> limits to the base classes that belongs to this namespace. Meanwhile, the flag :strict: only process the classes that are strictly defined in the given module (ignoring classes imported from other modules).
.. autoclasstree:: sphinx.util.SphinxParallelError sphinx.util.ExtensionError
Or directly the module:
.. autoclasstree:: sphinx.util
You can install it using pip
pip install sphinxcontrib-mermaid
Then add sphinxcontrib.mermaid in extensions list of your project's conf.py:
extensions = [
:alt:: determines the image's alternate text for HTML output. If not given, the alternate text defaults to the mermaid code.
:align:: determines the image's position. Valid options are 'left', 'center', 'right'
:caption:: can be used to give a caption to the diagram.
If it's set to "", the lib won't be automatically included from the CDN service and you'll need to add it as a local file in html_js_files. For instance, if you download the lib to _static/js/mermaid.js, in conf.py:
html_js_files = [
Changed in version 0.7: The init code doesn't include the <script> tag anymore. It's automatically added at build time.
mermaid_params = ['--theme', 'forest', '--width', '600', '--backgroundColor', 'transparent']
This will render the mermaid diagram with theme forest, 600px width and transparent background.
You can include Mermaid diagrams in your Markdown documents in Sphinx. You just need to setup the markdown support in Sphinx via myst-parser . See a minimal configuration from the tests
Then in your .md documents include a code block as in reStructuredTexts:
Alice->John: Hello John, how are you? ```
2017-2022, Martín Gaitán
|August 11, 2022|