sdpython · sdpython · May 4, 2026 · May 4, 2026 · May 4, 2026 · May 4, 2026
diff --git a/_doc/api/index.rst b/_doc/api/index.rst
@@ -16,6 +16,7 @@ Extensions
     epkg
     gdot
     quote
+    runmermaid
     runpython
     tools
     rst_builder

diff --git a/_doc/api/runmermaid.rst b/_doc/api/runmermaid.rst
@@ -0,0 +1,77 @@
+==========
+runmermaid
+==========
+
+This directive displays `Mermaid <https://mermaid.js.org/>`_ diagrams in the documentation.
+Diagrams are rendered client-side in *HTML* output via the Mermaid JavaScript library
+and as verbatim text in *LaTeX* / *RST* output.
+
+Usage
+=====
+
+In *conf.py*:
+
+::
+
+    extensions = [ ...
+        'sphinx_runpython.runmermaid',
+    ]
+
+One example:
+
+::
+
+    .. runmermaid::
+
+        graph LR
+            A --> B --> C
+
+Which gives:
+
+.. runmermaid::
+
+    graph LR
+        A --> B --> C
+
+The diagram source can also be produced by a Python script.
+Option *script* must be specified:
+
+::
+
+    .. runmermaid::
+        :script:
+
+        print("""
+        graph LR
+            A --> B
+        """)
+
+.. runmermaid::
+    :script:
+
+    print("""
+    graph LR
+        A --> B
+    """)
+
+When *script* is a non-empty string it is used as a split token: only
+the output **after** the first occurrence of that string is interpreted
+as Mermaid source:
+
+::
+
+    .. runmermaid::
+        :script: AFTER-THIS
+
+        print("preamble")
+        print("AFTER-THIS")
+        print("graph TD")
+        print("    P --> Q")
+
+Finally, the option ``:process:`` can be used to run the script in
+a separate process.
+
+Directive
+=========
+
+.. autoclass:: sphinx_runpython.runmermaid.sphinx_runmermaid_extension.RunMermaidDirective
diff --git a/_doc/conf.py b/_doc/conf.py
@@ -25,6 +25,7 @@
     "sphinx_runpython.docassert",
     "sphinx_runpython.gdot",
     "sphinx_runpython.epkg",
+    "sphinx_runpython.runmermaid",
     "sphinx_runpython.quote",
     "sphinx_runpython.runpython",
     "sphinx_runpython.sphinx_rst_builder",
@@ -120,6 +121,7 @@
     "git": "https://git-scm.com/",
     "Graphviz": "https://graphviz.org/",
     "HTML": "https://simple.wikipedia.org/wiki/HTML",
+    "Mermaid": "https://mermaid.js.org/",
     "nested_parse_with_titles": "https://www.sphinx-doc.org/en/master/extdev/markupapi.html#parsing-directive-content-as-rest",
     "numpy": (
         "https://www.numpy.org/",

diff --git a/_unittests/ut_runmermaid/test_runmermaid_extension.py b/_unittests/ut_runmermaid/test_runmermaid_extension.py
@@ -0,0 +1,127 @@
+import unittest
+import logging
+from sphinx_runpython.process_rst import rst2html
+from sphinx_runpython.ext_test_case import (
+    ExtTestCase,
+    ignore_warnings,
+)
+
+
+class TestRunMermaidExtension(ExtTestCase):
+    def setUp(self):
+        logger = logging.getLogger("runmermaid")
+        logger.disabled = True
+
+    @ignore_warnings(PendingDeprecationWarning)
+    def test_runmermaid_inline_rst(self):
+        """Inline runmermaid diagram is round-tripped through the RST writer."""
+        content = """
+before
+
+.. runmermaid::
+
+    graph LR
+        A --> B --> C
+
+after
+"""
+        content = rst2html(
+            content, writer_name="rst", new_extensions=["sphinx_runpython.runmermaid"]
+        )
+        self.assertIn("graph LR", content)
+        self.assertIn("A --> B --> C", content)
+
+    @ignore_warnings(PendingDeprecationWarning)
+    def test_runmermaid_inline_html(self):
+        """Inline runmermaid diagram produces a <pre class="mermaid"> element."""
+        content = """
+before
+
+.. runmermaid::
+
+    graph LR
+        A --> B
+
+after
+"""
+        html = rst2html(
+            content, writer_name="html", new_extensions=["sphinx_runpython.runmermaid"]
+        )
+        self.assertIn('class="mermaid"', html)
+        self.assertIn("graph LR", html)
+        self.assertIn("A --&gt; B", html)
+
+    @ignore_warnings(PendingDeprecationWarning)
+    def test_runmermaid_script(self):
+        """Script-generated runmermaid diagram is included in the RST output."""
+        content = """
+before
+
+.. runmermaid::
+    :script:
+
+    print(\"\"\"graph LR
+    X --> Y\"\"\")
+
+after
+"""
+        content = rst2html(
+            content, writer_name="rst", new_extensions=["sphinx_runpython.runmermaid"]
+        )
+        self.assertIn("graph LR", content)
+        self.assertIn("X --> Y", content)
+
+    @ignore_warnings(PendingDeprecationWarning)
+    def test_runmermaid_script_split(self):
+        """When :script: has a value it is used as a split token."""
+        content = """
+before
+
+.. runmermaid::
+    :script: BEGIN
+
+    print("preamble")
+    print("BEGIN")
+    print("graph TD")
+    print("    P --> Q")
+
+after
+"""
+        content = rst2html(
+            content, writer_name="rst", new_extensions=["sphinx_runpython.runmermaid"]
+        )
+        self.assertNotIn("preamble", content)
+        self.assertNotIn("BEGIN", content)
+        self.assertIn("graph TD", content)
+        self.assertIn("P --> Q", content)
+
+    @ignore_warnings(PendingDeprecationWarning)
+    def test_runmermaid_script_cache(self):
+        """Identical scripts produce the same output and are cached."""
+        script_body = 'print("graph LR\\n    A --> B")'
+        content = f"""
+before
+
+.. runmermaid::
+    :script:
+
+    {script_body}
+
+middle
+
+.. runmermaid::
+    :script:
+
+    {script_body}
+
+after
+"""
+        content = rst2html(
+            content, writer_name="rst", new_extensions=["sphinx_runpython.runmermaid"]
+        )
+        count = content.count("graph LR")
+        self.assertEqual(count, 2, f"Expected diagram code twice, got {count}")
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)
diff --git a/sphinx_runpython/runmermaid/__init__.py b/sphinx_runpython/runmermaid/__init__.py
@@ -0,0 +1,3 @@
+from .sphinx_runmermaid_extension import setup
+
+__all__ = ["setup"]
-Original file line number
+Diff line change
@@ Expand Up / @@ -16,6 +16,7 @@ Extensions @@
         epkg
         gdot
         quote
+        runmermaid
         runpython
         tools
         rst_builder
@@ Expand Down @@
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		from .sphinx_runmermaid_extension import setup

		__all__ = ["setup"]