How to migrate from sphinxcontrib-mermaid

Replace the extension

Follow the installation instructions, then replace sphinxcontrib.mermaid with sphinx_pele in conf.py:

extensions = ["sphinx_pele"]

Keep any other extensions your documentation uses. For MyST Markdown, keep myst_parser enabled. Do not enable both Mermaid extensions: they register the same directive name.

Keep the Mermaid source

Start with your existing inline and file-based directives:

.. mermaid:: diagrams/publishing.mmd
   :caption: Publishing flow
   :name: publishing-flow

Ordinary Markdown mermaid fences also work. Rebuild HTML and inspect the pages in a browser. Pele renders the Mermaid source, but layouts and support for individual Mermaid settings can differ.

Move configuration

Use this table to replace settings that affect the diagrams:

Existing setting or feature	Action
mermaid_init_config	Move supported Mermaid defaults into pele_options["config"].
Mermaid light/dark theme settings	Set Pele CSS variables; see styling.
D3 zoom settings	Use pele_options = {"zoom": "auto"} or directive :zoom:.
Mermaid CDN version or local JS path	Remove it; the wheel supplies the pinned Pele bundle.
mermaid_output_format, CLI arguments, or PDF export	Keep another rendering/export workflow if you need image files. This extension renders HTML in the browser.
Fullscreen, icon packs, or autoclasstree	Review these uses individually; there is no matching extension feature.

For example:

pele_options = {
    "zoom": "auto",
    "config": {"flowchart": {"nodeSpacing": 40, "rankSpacing": 50}},
}

Remove obsolete mermaid_* and D3 settings after moving the values you need. A successful build does not verify whether an unused setting affected the output.

Check the output you publish

Build with warnings treated as errors:

python -m sphinx -W -b html docs docs/_build/html

Open pages containing each diagram type you use. Check captions, figure links, fonts, and a narrow viewport. Browser rendering errors do not fail the Sphinx build, so inspect the rendered diagrams as well as the build log.

If you publish LaTeX or text output, build those formats too. They contain literal Mermaid source with this extension. See rendering and output for the reason and troubleshooting for common failures.