# What changed in sphinxcontrib-mermaid

> 12 changes in sphinxcontrib-mermaid 2 from its official release notes, upgrade guides and advisories: 1 new APIs and options. Each one cited. Sources checked 2026-10-19. HTML: https://unstale.sh/pypi/sphinxcontrib-mermaid/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## sphinxcontrib-mermaid 2

### New APIs and options

- Adds an option for passing a global Mermaid configuration. (2.1.0) — [release notes](https://github.com/mgaitan/sphinxcontrib-mermaid/blob/a5008d5d94228ce15f5039c66626b34195f9e5d5/CHANGELOG.md#210-july-18-2026)

### Performance

- Loads the ZenUML plugin only on pages that contain a ZenUML diagram. (2.1.0) — [release notes](https://github.com/mgaitan/sphinxcontrib-mermaid/blob/a5008d5d94228ce15f5039c66626b34195f9e5d5/CHANGELOG.md#210-july-18-2026)

### Fixes and other changes

- Generated Mermaid caption nodes preserve source metadata so Sphinx can extract them into gettext catalogs and apply normal caption translations. (2.1.1) — [release notes](https://github.com/mgaitan/sphinxcontrib-mermaid/blob/a5008d5d94228ce15f5039c66626b34195f9e5d5/CHANGELOG.md#211-july-19-2026)
- The HTML visitor passes the existing Mermaid image class through, making PNG output consistently targetable with CSS. (2.1.1) — [release notes](https://github.com/mgaitan/sphinxcontrib-mermaid/blob/a5008d5d94228ce15f5039c66626b34195f9e5d5/CHANGELOG.md#211-july-19-2026)
- Fixes d3 zoom on nested SVGs. (2.1.0) — [release notes](https://github.com/mgaitan/sphinxcontrib-mermaid/blob/a5008d5d94228ce15f5039c66626b34195f9e5d5/CHANGELOG.md#210-july-18-2026)
- Fixes fullscreen button positioning inconsistency. (2.1.0) — [release notes](https://github.com/mgaitan/sphinxcontrib-mermaid/blob/a5008d5d94228ce15f5039c66626b34195f9e5d5/CHANGELOG.md#210-july-18-2026)
- Fixes interactions between the fullscreen, zoom, and lazy-render features. (2.1.0) — [release notes](https://github.com/mgaitan/sphinxcontrib-mermaid/blob/a5008d5d94228ce15f5039c66626b34195f9e5d5/CHANGELOG.md#210-july-18-2026)
- Skips injecting Mermaid JavaScript when the output format does not support it. (2.1.0) — [release notes](https://github.com/mgaitan/sphinxcontrib-mermaid/blob/a5008d5d94228ce15f5039c66626b34195f9e5d5/CHANGELOG.md#210-july-18-2026)
- Confines the injected ZenUML stylesheet to the diagram subtree so it no longer restyles the host theme. (2.1.0) — [release notes](https://github.com/mgaitan/sphinxcontrib-mermaid/blob/a5008d5d94228ce15f5039c66626b34195f9e5d5/CHANGELOG.md#210-july-18-2026)
- Root-level pages now use a valid relative ES module specifier for local JS module imports. (2.0.3) — [release notes](https://github.com/mgaitan/sphinxcontrib-mermaid/blob/a5008d5d94228ce15f5039c66626b34195f9e5d5/CHANGELOG.md#203-july-7-2026)
- Diagrams hidden by a parent are rendered when they become visible, fixing broken SVGs. (2.0.3) — [release notes](https://github.com/mgaitan/sphinxcontrib-mermaid/blob/a5008d5d94228ce15f5039c66626b34195f9e5d5/CHANGELOG.md#203-july-7-2026)
- mmdc error messages are captured as strings for nicer error display. (2.0.3) — [release notes](https://github.com/mgaitan/sphinxcontrib-mermaid/blob/a5008d5d94228ce15f5039c66626b34195f9e5d5/CHANGELOG.md#203-july-7-2026)