SPHINXCONTRIB-MERMAID(3)

📦

version 2.0.1 · 5 versions

💖 SPHINXCONTRIB-MERMAID 💖

okay so bestie, listen — this is the manual page for sphinxcontrib-mermaid (that's SPHINXCONTRIB-MERMAID(3) if you're being formal, which we are not 💅). it's giving "let me draw you a diagram inside your docs" energy and honestly? iconic.

Note: sphinxcontrib-mermaid is actively seeking new maintainers. As the original creator, I'm no longer able to dedicate the time and attention needed. If you're interested in contributing and helping to drive this project forward, please see this issue: https://github.com/mgaitan/sphinxcontrib-mermaid/issues/148.

This extension lets you embed Mermaid graphs — https://mermaid.js.org/ — in your documents. We're talking general flowcharts, sequence diagrams, gantt diagrams and more, no cap. ✨

It adds a directive to embed mermaid markup. For example:

.. mermaid::

    sequenceDiagram
      participant Alice
      participant Bob
      Alice->John: Hello John, how are you?
      loop Healthcheck
          John->John: Fight against hypochondria
      end
      Note right of John: Rational thoughts <br/>prevail...
      John-->Alice: Great!
      John->Bob: How about you?
      Bob-->John: Jolly good!

By default, the HTML builder will simply render this as a div tag with class="mermaid", injecting the external javascript, css and initialization code to make mermaid works. okay, hand it the aux cord, it's doing everything itself. 🎀

For other builders (or if mermaid_output_format config variable is set differently), the extension will use mermaid-cli (https://github.com/mermaid-js/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. lowkey standard Sphinx behaviour, but we said it out loud so you don't have to guess. 🦋

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. she's doing a whole family tree reveal, obsessed. 🌸

Of course, these objects need to be importable to make its diagram. (no import, no glow-up, sorry 😭)

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

For example:

.. autoclasstree:: sphinx.util.DownloadFiles sphinx.errors.ExtensionError
    :full:

[graph]

Or directly the module:

.. autoclasstree:: sphinx.util

✨ INSTALLATION ✨

You can install it using pip:

pip install sphinxcontrib-mermaid

Then add sphinxcontrib.mermaid in extensions list of your project's conf.py:

extensions = [
    ...,
    'sphinxcontrib.mermaid'
]

boom. you're in. 🫶

🎀 DIRECTIVE OPTIONS 🎀

sphinxcontrib-mermaid mermaid diagrams can be configured by rst/md frontmatter:

.. mermaid::
   :name: test

   <diagram>

name: test

name — determines the image's name for HTML output. NOTE: mermaid will use this as the id of the generated svg element, which can be useful for styling with custom css: #mydiagram > svg { height: 1000px }
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.
zoom — can be used to enable zooming the diagram. For a global config see mermaid_d3_zoom below.
fullscreen — can be used to enable fullscreen modal viewing of the diagram. For a global config see mermaid_fullscreen below.
config — JSON to pass through to the mermaid configuration (https://mermaid.js.org/config/configuration.html). NOTE: The mermaid documentation uses YAML, but we must use JSON because Markdown processing of frontmatter will interfere.
title — Title to pass through to the mermaid configuration (https://mermaid.js.org/config/configuration.html)

🌈 CONFIG VALUES 🌈

`mermaid_output_format`

The output format for Mermaid when building HTML files. This must be either 'raw' 'png' or 'svg'; the default is 'raw'. mermaid-cli is required if it's not raw. (so like, default girl is raw, but if you switch it up you gotta have the cli installed, fr fr)

`mermaid_cmd`

The command name with which to invoke mermaid-cli program. The default is 'mmdc'; you may need to set this to a full path if it's not in the executable search path. If a string is specified, it is split using shlex.split to support multi-word commands. To avoid splitting, a list of strings can be specified. Examples:

mermaid_cmd = 'npx mmdc'
mermeid_cmd = ['npx', '--no-install', 'mmdc']

`mermaid_cmd_shell`

When set to true, the shell=True argument will be passed the process execution command. This allows commands other than binary executables to be executed on Windows. The default is false.

`mermaid_params`

For individual parameters, a list of parameters can be added. Refer to Examples (https://github.com/mermaid-js/mermaid-cli#usage):

mermaid_params = ['--theme', 'forest', '--width', '600', '--backgroundColor', 'transparent']

This will render the mermaid diagram with theme forest, 600px width and transparent background. slay. 💅

`mermaid_sequence_config`

Allows overriding the sequence diagram configuration. It could be useful to increase the width between actors. It needs to be a json file. Check options in the documentation (https://mermaid-js.github.io/mermaid/#/mermaidAPI?id=configuration).

`mermaid_verbose`

Use the verbose mode when call mermaid-cli, and show its output in the building process.

`mermaid_pdfcrop`

If using latex output, it might be useful to crop the pdf just to the needed space. For this, pdfcrop can be used. State binary name to use this extra function.

`mermaid_init_config`

Optional override of arguments to mermaid.initialize(), passed in as a JSON. Defaults to { "startOnLoad": True}.

`mermaid_version`

The version of mermaid that will be used to parse raw output in HTML files. This should match a version available on https://www.jsdelivr.com/package/npm/mermaid. The default is "11.12.1".

`mermaid_use_local`

Optional path to a local installation of mermaid.esm.min.mjs. By default, we will pull from jsdelivr.

`mermaid_include_elk`

Whether to download and load the ELK JavaScript extensions. Defaults to False.

`mermaid_include_zenuml`

Whether to download and load the ZenuML JavaScript extensions. Defaults to False.

`mermaid_elk_version`

The version of mermaid ELK renderer that will be used. The default is "0.2.0".

`mermaid_zenuml_version`

The version of mermaid ZenuML renderer that will be used. The default is "0.2.2".

`mermaid_elk_use_local`

Optional path to a local installation of mermaid-layout-elk.esm.min.mjs. By default, we will pull from jsdelivr.

`mermaid_zenuml_use_local`

Optional path to a local installation of mermaid-zenuml.esm.min.mjs. By default, we will pull from jsdelivr.

`d3_use_local`

Optional path to a local installation of d3.min.js. By default, we will pull from jsdelivr.

`d3_version`

The version of d3 that will be used to provide zoom functionality on mermaid graphs. The default is "7.9.0".

`mermaid_d3_zoom`

Enables zooming in all the generated Mermaid diagrams.

`mermaid_width`

Sets the default diagram width within its container. Default to 100%.

`mermaid_height`

Sets the default diagram height within its container. Default to 500px.

`mermaid_fullscreen`

Enables fullscreen modal viewing for all Mermaid diagrams. When enabled, a fullscreen button appears in the top-right corner of each diagram. Clicking it opens the diagram in a fullscreen modal overlay. The modal can be closed by pressing ESC, clicking outside the diagram, or clicking the close button. This feature is theme-agnostic and works with any Sphinx theme. (main character energy, honestly 💖)

`mermaid_fullscreen_button`

Customizes the fullscreen button icon/text. Default is "⛶". You can use any Unicode character or emoji, for example "🔍" or "⛶".

`mermaid_fullscreen_button_opacity`

Customizes the fullscreen button opacity, to avoid fully obscuring important chart content. Default is 50 (percent). You can use any value from 0 to 100. Button becomes fully opaque on hover.

🦋 MARKDOWN SUPPORT 🦋

You can include Mermaid diagrams in your Markdown documents in Sphinx. You just need to setup the markdown support in Sphinx (https://www.sphinx-doc.org/en/master/usage/markdown.html) via myst-parser (https://myst-parser.readthedocs.io/). See a minimal configuration from the tests (https://github.com/mgaitan/sphinxcontrib-mermaid/blob/master/tests/roots/test-markdown/conf.py).

Then in your .md documents include a code block as in reStructuredTexts:

sequenceDiagram participant Alice participant Bob Alice->John: Hello John, how are you?

For GitHub cross-support, you can omit the curly braces and configure myst to use the mermaid code block as a myst directive. For example, in conf.py:

myst_fence_as_directive = ["mermaid"]

🌈 BUILDING PDFS ON READTHEDOCS.IO 🎀

okay bestie, listen. getting Mermaid diagrams to actually show up in PDFs on readthedocs.io is not free — you gotta do a lil extra config sprinkling. it's three steps, no more, no less. let's go 💅

in your .readthedocs.yaml file — which must live in the root of your repository, don't get cute with it — you need a post_install command that installs the Mermaid CLI:

build:
  os: ubuntu-20.04
  tools:
    python: "3.8"
    nodejs: "16"
  jobs:
    post_install:
      - npm install -g @mermaid-js/mermaid-cli

🫶 heads up babes: if you didn't already have a .readthedocs.yaml file, you also have to specify all the targets you wanna build plus the other basic config stuff. you can't just drop in the one command and dip.

a minimal but complete example of the whole file looks like this, so you can copy-paste and be iconic:

# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
# Required
version: 2
# Set the version of Python and other tools you might need
build:
  os: ubuntu-24.04
  apt_packages:
    - libasound2t64
  tools:
    python: "3.11"
    nodejs: "20"
  jobs:
    post_install:
      - npm install -g @mermaid-js/mermaid-cli
# Build documentation in the docs/ directory with Sphinx
sphinx:
   configuration: docs/conf.py
# If using Sphinx, optionally build your docs in additional formats such as PDF
formats:
  - epub
  - pdf
python:
   install:
   - requirements: docs/requirements.txt

in your documentation directory, add a file called puppeteer-config.json with contents: :

{
 "args": ["--no-sandbox"]
}

in your documentation conf.py file, add: :

mermaid_params = ['-p', 'puppeteer-config.json']

and that's it. three lil steps and your PDFs are thriving ✨📄

🌸 Author 🌸

Martín Gaitán — king behavior fr fr 👑

💜 Copyright 💜

2017-2025, Martín Gaitán

okay that's the whole page bestie, you made it to the end, slay 💖 this was SPHINXCONTRIB-MERMAID(3), version 2.0.1, dated Jul 05, 2026. go build something gorgeous with it, ily, byeeee 🦋✨

📦 where this page comes from

ubuntu stonking: python3-sphinxcontrib-mermaid 2.0.1-2 · BSD-2-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms