sphinx-gp-mermaid

Build-time Mermaid diagrams for Sphinx. Fenced mermaid blocks render to inline <svg> during the build via mmdc (@mermaid-js/mermaid-cli): no client-side mermaid runtime, no asynchronous pop-in, no layout shift.

Each diagram is rendered twice — a light and a dark variant — and both are inlined, toggled by CSS on body[data-theme]. Diagrams paint with the page, follow the theme toggle without JavaScript, and survive SPA navigation as live DOM.

Install

$ pip install sphinx-gp-mermaid

Usage

Enable the extension in conf.py:

extensions = ["sphinx_gp_mermaid"]

With gp-sphinx, opt in via merge_sphinx_config:

config = merge_sphinx_config(
    extra_extensions=["sphinx_gp_mermaid"],
)

Author diagrams as MyST fences:

:::{mermaid}
:caption: How it flows.
:alt: a request flowing through two steps
:name: request-flow
:responsive: fit

flowchart LR
    a --> b
:::

fit is the default responsive policy: the rendered SVG scales down to the content column. Use :responsive: preserve when a dense diagram should keep its intrinsic width and scroll horizontally instead of shrinking labels.

Renderer toolchain

Rendering shells out to mmdc, resolved from the mermaid_cmd config value, then <confdir>/node_modules/.bin/mmdc, then PATH. Install it in the docs toolchain:

$ pnpm add -D @mermaid-js/mermaid-cli

When the renderer is unavailable the build still succeeds: diagrams degrade to their source text with a single warning.

Documentation

See the full documentation for directive options, theming, caching, and CI setup.