/``.
+
+ >>> _chrome_glob("linux")
+ '*/chrome-linux64/chrome'
+ >>> _chrome_glob("win32")
+ '*/chrome-win64/chrome.exe'
+ >>> _chrome_glob("darwin").startswith("*/chrome-mac-")
+ True
+ """
+ if platform.startswith("win"):
+ return "*/chrome-win64/chrome.exe"
+ if platform == "darwin":
+ return (
+ "*/chrome-mac-*/Google Chrome for Testing.app"
+ "/Contents/MacOS/Google Chrome for Testing"
+ )
+ return "*/chrome-linux64/chrome"
+
+
+def _discover_chrome() -> str | None:
+ """Return a Chrome installed by ``puppeteer browsers install``, if any.
+
+ Puppeteer's automatic resolution can miss the cached browser (its cache dir
+ is computed relative to the install location); pointing ``executablePath`` at
+ the discovered binary sidesteps that.
+ """
+ cache = pathlib.Path.home() / ".cache" / "puppeteer" / "chrome"
+ if not cache.is_dir():
+ return None
+ candidates = sorted(cache.glob(_chrome_glob(sys.platform)))
+ return str(candidates[-1]) if candidates else None
+
+
+def _resolve_mmdc(app: Sphinx) -> list[str] | None:
+ """Locate the ``mmdc`` executable: config, then docs-local, then ``PATH``."""
+ configured: str = app.config.mermaid_cmd
+ if configured:
+ found = shutil.which(configured)
+ if found:
+ return [found]
+ path = pathlib.Path(configured)
+ if path.exists():
+ return [str(path)]
+ local = pathlib.Path(app.confdir) / "node_modules" / ".bin" / "mmdc"
+ if local.exists():
+ return [str(local)]
+ found = shutil.which("mmdc")
+ return [found] if found else None
+
+
+def _puppeteer_config_file(app: Sphinx, tmpdir: pathlib.Path) -> pathlib.Path:
+ """Write a puppeteer config (``--no-sandbox`` + resolved Chrome) and return it.
+
+ An explicit ``mermaid_puppeteer_config`` wins; otherwise a minimal
+ config is generated, adding ``executablePath`` from
+ ``PUPPETEER_EXECUTABLE_PATH`` or a discovered cached Chrome.
+ """
+ configured: str = app.config.mermaid_puppeteer_config
+ if configured:
+ return pathlib.Path(configured)
+ data: dict[str, t.Any] = {
+ "args": ["--no-sandbox", "--disable-gpu", "--disable-dev-shm-usage"],
+ }
+ executable = os.environ.get("PUPPETEER_EXECUTABLE_PATH") or _discover_chrome()
+ if executable:
+ data["executablePath"] = executable
+ out = tmpdir / "puppeteer.json"
+ out.write_text(json.dumps(data), encoding="utf-8")
+ return out
+
+
+def _mermaid_config(theme: str) -> dict[str, t.Any]:
+ """Return the mermaid ``-c`` config: base theme + furo palette + themeCSS.
+
+ ``block.padding: 0`` tiles block-beta panes contiguously; other diagram
+ types ignore the ``block`` key.
+
+ >>> cfg = _mermaid_config("light")
+ >>> cfg["theme"], "themeVariables" in cfg, cfg["block"]["padding"]
+ ('base', True, 0)
+ """
+ return {
+ "theme": "base",
+ "block": {"padding": 0},
+ "themeVariables": _PALETTES[theme],
+ "themeCSS": _theme_css(theme),
+ }
+
+
+def _render(app: Sphinx, source: str, config_json: str) -> str:
+ """Render ``source`` to an SVG string via ``mmdc`` using ``config_json``."""
+ mmdc = _resolve_mmdc(app)
+ if mmdc is None:
+ msg = (
+ "mmdc (@mermaid-js/mermaid-cli) not found; install it in the docs "
+ "toolchain or set the mermaid_cmd config value"
+ )
+ raise MermaidRendererMissing(msg)
+ with tempfile.TemporaryDirectory(prefix="sphinx-gp-mermaid-") as td:
+ tmpdir = pathlib.Path(td)
+ in_file = tmpdir / "diagram.mmd"
+ out_file = tmpdir / "diagram.svg"
+ config_file = tmpdir / "config.json"
+ in_file.write_text(source, encoding="utf-8")
+ config_file.write_text(config_json, encoding="utf-8")
+ argv = [
+ *mmdc,
+ "-i",
+ str(in_file),
+ "-o",
+ str(out_file),
+ "-b",
+ "transparent",
+ "-c",
+ str(config_file),
+ "-p",
+ str(_puppeteer_config_file(app, tmpdir)),
+ ]
+ try:
+ subprocess.run(
+ argv,
+ check=True,
+ capture_output=True,
+ text=True,
+ timeout=180,
+ )
+ except OSError as exc: # mmdc vanished after resolve, or isn't executable
+ raise MermaidRendererMissing(str(exc)) from exc
+ except subprocess.SubprocessError as exc:
+ stderr = getattr(exc, "stderr", "") or ""
+ msg = f"mmdc failed: {exc}\n{stderr}"
+ raise MermaidRenderError(msg) from exc
+ if not out_file.is_file():
+ msg = "mmdc produced no SVG output"
+ raise MermaidRenderError(msg)
+ return out_file.read_text(encoding="utf-8")
+
+
+def _render_cached(app: Sphinx, source: str, theme: str) -> str:
+ """Return a rendered SVG, reading/writing a content-hashed on-disk cache.
+
+ The cache lives outside ``_build`` (under the confdir) so it survives the
+ ``rm -rf docs/_build`` that precedes a full build.
+ """
+ config_json = json.dumps(_mermaid_config(theme), sort_keys=True)
+ digest = _diagram_digest(source, theme, extra=config_json)
+ cache_dir = pathlib.Path(app.confdir) / "_mermaid_cache"
+ cache_file = cache_dir / f"{digest}.svg"
+ if cache_file.is_file():
+ return cache_file.read_text(encoding="utf-8")
+ svg = _render(app, source, config_json)
+ cache_dir.mkdir(parents=True, exist_ok=True)
+ cache_file.write_text(svg, encoding="utf-8")
+ return svg
+
+
+def _warn_render_failure(builder: Builder, node: nodes.Node, exc: MermaidError) -> None:
+ """Emit a single build warning when rendering is unavailable or fails.
+
+ The once-only memo lives on the builder (imgmath's pattern), so parallel
+ writer processes each warn at most once and a fresh build starts clean.
+ """
+ if getattr(builder, _WARNED_ATTR, False):
+ return
+ setattr(builder, _WARNED_ATTR, True)
+ logger.warning(
+ "mermaid render unavailable; emitting diagram source as text: %s",
+ exc,
+ location=node,
+ )
+
+
+def html_visit_mermaid_inline(self: HTML5Translator, node: mermaid_inline) -> None:
+ """Render the diagram and append dual light/dark inline SVG, then skip."""
+ source: str = node["mermaid_source"]
+ app = self.builder.app
+ try:
+ light = _render_cached(app, source, _THEME_LIGHT)
+ dark = _render_cached(app, source, _THEME_DARK)
+ except MermaidError as exc:
+ _warn_render_failure(self.builder, node, exc)
+ self.body.append(
+ ''
+ + html.escape(source)
+ + "
",
+ )
+ raise nodes.SkipNode from None
+
+ digest = _diagram_digest(source, "")
+ light = _normalize_svg(light, svg_id=_svg_element_id(digest, _THEME_LIGHT))
+ dark = _normalize_svg(dark, svg_id=_svg_element_id(digest, _THEME_DARK))
+
+ caption: str = node.get("caption", "")
+ alt = node.get("alt", "") or caption
+ aria = f' aria-label="{html.escape(alt, quote=True)}"' if alt else ""
+ ids: list[str] = node.get("ids", [])
+ fig_id = f' id="{ids[0]}"' if ids else ""
+
+ parts = [
+ f'',
+ (
+ '{light}
'
+ ),
+ (
+ '{dark}
'
+ ),
+ ]
+ if caption:
+ parts.append(f"{html.escape(caption)}")
+ parts.append("")
+ self.body.append("".join(parts))
+ raise nodes.SkipNode
+
+
+def _depart_mermaid_inline(self: HTML5Translator, node: mermaid_inline) -> None:
+ """No-op; :func:`html_visit_mermaid_inline` raises ``SkipNode``."""
+
+
+def _diagram_fallback_text(node: mermaid_inline) -> str:
+ """Return the alt-text stand-in non-HTML builders emit for a diagram.
+
+ >>> node = mermaid_inline()
+ >>> node["alt"] = "session holds windows"
+ >>> _diagram_fallback_text(node)
+ '[diagram: session holds windows]'
+ >>> _diagram_fallback_text(mermaid_inline())
+ '[diagram]'
+ """
+ alt: str = node.get("alt", "") or node.get("caption", "")
+ return f"[diagram: {alt}]" if alt else "[diagram]"
+
+
+def text_visit_mermaid_inline(self: TextTranslator, node: mermaid_inline) -> None:
+ """Emit the alt-text stand-in for the text builder, then skip."""
+ self.add_text(_diagram_fallback_text(node))
+ raise nodes.SkipNode
+
+
+def man_visit_mermaid_inline(
+ self: ManualPageTranslator,
+ node: mermaid_inline,
+) -> None:
+ """Emit the alt-text stand-in for the man builder, then skip."""
+ self.body.append(_diagram_fallback_text(node))
+ raise nodes.SkipNode
+
+
+def latex_visit_mermaid_inline(self: LaTeXTranslator, node: mermaid_inline) -> None:
+ """Emit the escaped alt-text stand-in for the LaTeX builder, then skip."""
+ self.body.append(self.encode(_diagram_fallback_text(node)))
+ raise nodes.SkipNode
+
+
+def texinfo_visit_mermaid_inline(
+ self: TexinfoTranslator,
+ node: mermaid_inline,
+) -> None:
+ """Emit the escaped alt-text stand-in for the texinfo builder, then skip."""
+ self.body.append(self.escape(_diagram_fallback_text(node)))
+ raise nodes.SkipNode
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+ """Register the directive, node, config values, and stylesheet.
+
+ Parameters
+ ----------
+ app : Sphinx
+ Sphinx application instance.
+
+ Returns
+ -------
+ ExtensionMetadata
+ Extension metadata with version and parallel-build flags.
+
+ Examples
+ --------
+ >>> from sphinx_gp_mermaid import setup
+ >>> callable(setup)
+ True
+ """
+ app.add_node(
+ mermaid_inline,
+ html=(html_visit_mermaid_inline, _depart_mermaid_inline),
+ text=(text_visit_mermaid_inline, None),
+ man=(man_visit_mermaid_inline, None),
+ latex=(latex_visit_mermaid_inline, None),
+ texinfo=(texinfo_visit_mermaid_inline, None),
+ )
+ app.add_directive("mermaid", MermaidDirective)
+ app.add_config_value("mermaid_cmd", "", "env")
+ app.add_config_value("mermaid_puppeteer_config", "", "env")
+
+ _static_dir = str(pathlib.Path(__file__).parent / "_static")
+
+ def _add_static_path(app: Sphinx) -> None:
+ if _static_dir not in app.config.html_static_path:
+ app.config.html_static_path.append(_static_dir)
+
+ def _exclude_cache_dir(app: Sphinx, config: Config) -> None:
+ # The render cache lives under the confdir (outside _build) so it
+ # survives clean builds; keep Sphinx from treating it as sources.
+ if "_mermaid_cache" not in config.exclude_patterns:
+ config.exclude_patterns.append("_mermaid_cache")
+
+ app.connect("config-inited", _exclude_cache_dir)
+ app.connect("builder-inited", _add_static_path)
+ app.add_css_file("css/sphinx_gp_mermaid.css")
+
+ return {
+ "version": _EXTENSION_VERSION,
+ "parallel_read_safe": True,
+ "parallel_write_safe": True,
+ }
diff --git a/packages/sphinx-gp-mermaid/src/sphinx_gp_mermaid/_static/css/sphinx_gp_mermaid.css b/packages/sphinx-gp-mermaid/src/sphinx_gp_mermaid/_static/css/sphinx_gp_mermaid.css
new file mode 100644
index 00000000..b2b32234
--- /dev/null
+++ b/packages/sphinx-gp-mermaid/src/sphinx_gp_mermaid/_static/css/sphinx_gp_mermaid.css
@@ -0,0 +1,71 @@
+/*
+ * Build-time mermaid diagrams (sphinx_gp_mermaid).
+ *
+ * Each diagram is inlined twice — a light and a dark SVG — and this stylesheet
+ * shows exactly one. Mermaid bakes literal colours into an id-scoped,
+ * !important a