sphinx-gp-mermaid: build-time Mermaid diagrams as dual inline SVG

docs/_ext/package_reference.py

@@ -201,6 +201,7 @@ class PackageDocsRecord:
     "sphinx-fonts": "tokens",
     "sphinx-ux-badges": "ux",
     "sphinx-ux-autodoc-layout": "ux",
+    "sphinx-gp-mermaid": "ux",
     "sphinx-vite-builder": "build-seo",
     "sphinx-gp-opengraph": "build-seo",
     "sphinx-gp-sitemap": "build-seo",

docs/packages/sphinx-gp-mermaid/index.md

@@ -0,0 +1,6 @@
+(sphinx-gp-mermaid)=
+
+# sphinx-gp-mermaid
+
+```{package-landing} sphinx-gp-mermaid
+```

docs/redirects.txt

@@ -1,6 +1,7 @@
 extensions/sphinx-gp-opengraph packages/sphinx-gp-opengraph
 extensions/sphinx-gp-sitemap packages/sphinx-gp-sitemap
 extensions/sphinx-gp-llms packages/sphinx-gp-llms
+extensions/sphinx-gp-mermaid packages/sphinx-gp-mermaid
 extensions/gp-sphinx packages/gp-sphinx
 extensions/index packages/index
 extensions/sphinx-autodoc-argparse packages/sphinx-autodoc-argparse

packages/gp-sphinx/src/gp_sphinx/config.py

@@ -437,6 +437,17 @@ def merge_sphinx_config(
     >>> "sphinx_design" in conf["extensions"]
     False
 
+    Loading sphinx_gp_mermaid also routes plain ``mermaid`` fences to it:
+
+    >>> conf = merge_sphinx_config(
+    ...     project="test",
+    ...     version="1.0",
+    ...     copyright="2026",
+    ...     extra_extensions=["sphinx_gp_mermaid"],
+    ... )
+    >>> conf["myst_fence_as_directive"]
+    ['mermaid']
+
     Auto-computed values from source_repository and docs_url:
 
     >>> conf = merge_sphinx_config(
@@ -601,6 +612,12 @@ def merge_sphinx_config(
     if vite_root_setting is not None:
         conf["sphinx_vite_builder_root"] = vite_root_setting
 
+    # Route plain ```mermaid fences to sphinx_gp_mermaid's directive. This
+    # must happen at conf level: myst-parser snapshots myst_* config at its
+    # own config-inited, so an extension-level mutation lands too late.
+    if "sphinx_gp_mermaid" in ext_list:
+        conf["myst_fence_as_directive"] = ["mermaid"]
+
     # Apply overrides last (can override auto-computed values)
     conf.update(overrides)
 

packages/sphinx-gp-mermaid/README.md

@@ -0,0 +1,62 @@
+# 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](https://github.com/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
+
+```console
+$ pip install sphinx-gp-mermaid
+```
+
+## Usage
+
+Enable the extension in `conf.py`:
+
+```python
+extensions = ["sphinx_gp_mermaid"]
+```
+
+With gp-sphinx, opt in via `merge_sphinx_config`:
+
+```python
+config = merge_sphinx_config(
+    extra_extensions=["sphinx_gp_mermaid"],
+)
+```
+
+Author diagrams as MyST fences:
+
+````markdown
+:::{mermaid}
+:caption: How it flows.
+
+flowchart LR
+    a --> b
+:::
+````
+
+## 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:
+
+```console
+$ 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](https://gp-sphinx.git-pull.com/packages/sphinx-gp-mermaid/)
+for directive options, theming, caching, and CI setup.

packages/sphinx-gp-mermaid/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "sphinx-gp-mermaid"
+version = "0.0.1a31"
+description = "Build-time Mermaid diagrams for Sphinx — dual light/dark inline SVG rendered via mermaid-cli"
+requires-python = ">=3.10,<4.0"
+authors = [
+  {name = "Tony Narlock", email = "tony@git-pull.com"}
+]
+license = { text = "MIT" }
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: MIT License",
+  "Framework :: Sphinx",
+  "Framework :: Sphinx :: Extension",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Documentation",
+  "Topic :: Documentation :: Sphinx",
+  "Typing :: Typed",
+]
+readme = "README.md"
+keywords = ["sphinx", "mermaid", "diagrams", "documentation", "svg"]
+dependencies = [
+  "sphinx>=8.1",
+]
+
+[project.urls]
+Repository = "https://github.com/git-pull/gp-sphinx"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sphinx_gp_mermaid"]