Mermaid JS diagrams do not display correctly when switching slides

[takanory]

What happened?

To reproduce

Steps to reproduce the behavior:

• The mermaid js diagrams does not display correctly when switching pages.

• Reloading the browser displays it correctly.

• sample slide: https://slides.takanory.net/slides/20260108bpstyle/#/4/5

• This is likely because the initialization code for mermaid js isn't being loaded when switching slides.

• The following issue appears to have the same cause.

• Diagram not rendering if it's in an unopened tab from sphinx-design's tab-set mgaitan/sphinxcontrib-mermaid#126

Expected behavior

• Mermaid JS diagrams display correctly when switching slides.

Screenshots

If applicable, add screenshots to help explain your problem.

Operating system

macOS

Python runtime and version

Python 3.13

Sphinx version

8.2.3

Library version

3.2.1

Extra context

No response

[drillan]

Root Cause

I ran into the same issue and traced it to a fundamental incompatibility between Reveal.js and Mermaid's client-side rendering.

Reveal.js hides non-active slides (display: none equivalent). When Mermaid runs mermaid.run(), it tries to measure text pixel dimensions to calculate node placement and edge routing. For elements on hidden slides, the browser returns 0 for all measurements, causing Mermaid's layout engine (dagre/ELK) to fail with:

Could not find a suitable point for the distance

This manifests as either "Syntax error in text" or broken SVGs with viewBox="-8 -8 16 16" (essentially 16×16px). All diagrams on non-visible slides are affected, not just the first one. Reloading works because the currently visible slide's DOM is not hidden at that moment.

Solution: Server-side SVG rendering

The fix is to switch sphinxcontrib-mermaid from client-side (raw) to server-side (svg) rendering. This uses mmdc (Mermaid CLI) to pre-render SVGs at build time in a headless browser where all elements are visible.

# conf.py
mermaid_output_format = "svg"
mermaid_cmd = ["npx", "-y", "@mermaid-js/mermaid-cli@latest"]
mermaid_cmd_shell = False
mermaid_params = ["-b", "transparent"]

The -b transparent flag ensures SVGs have transparent backgrounds, so they blend with your slide theme.

Additional: CSS for <object> tags

In SVG mode, sphinxcontrib-mermaid embeds diagrams via <object> tags. These can overflow the slide area, so you need CSS to constrain them. Important: this CSS must be in a separate file loaded via revealjs_css_files, not in the SCSS theme — browsers silently drop object selectors in certain CSS contexts.

/* _static/mermaid-fix.css */
.reveal .slides section > object {
  display: block;
  max-height: 500px;
  width: 100%;
  margin: 0 auto;
}

# conf.py
revealjs_css_files = [
    "mermaid-fix.css",
]

Related

• sphinxcontrib-mermaid#126 — same underlying cause

[drillan]

Update: I've opened a PR on sphinxcontrib-mermaid to fix this at the source:

• Fix broken diagrams in hidden containers (Reveal.js, tabs) mgaitan/sphinxcontrib-mermaid#227

It uses IntersectionObserver to defer rendering of hidden elements until they become visible, so mermaid_output_format = "raw" (client-side rendering) would work correctly with Reveal.js without needing to switch to server-side SVG rendering.