Fix display of mermaid diagrams in dark mode (#2250)

Closes: #2249

The handling is completely analoguous to the existing handling of
graphviz
[here](https://github.com/pydata/pydata-sphinx-theme/blob/main/src/pydata_sphinx_theme/assets/styles/extensions/_graphviz.scss).

sphinxcontrib-mermaid generates the following HTML

<img width="323" height="118"
alt="475613612-a34f1441-ca54-4f31-a51c-668731175b41"
src="https://github.com/user-attachments/assets/fa926e53-eb55-4bed-9500-301b73bb35f9"
/>

Therefore, the selector `pre.mermaid > svg` is suitable.

---------

Co-authored-by: Daniel McCloy <dan@mccloy.info>

Author: timhoffm

docs/conf.py

@@ -47,6 +47,7 @@
     "myst_parser",
     "ablog",
     "jupyter_sphinx",
+    "sphinxcontrib.mermaid",
     "sphinxcontrib.youtube",
     "nbsphinx",
     "numpydoc",

docs/examples/index.rst

@@ -19,6 +19,7 @@ See the sections in the primary sidebar and below to explore.
     pydata
     execution
     graphviz
+    mermaid
 
 
 .. Note: the caption below is intentionally long in order to test out what long captions look like.

docs/examples/mermaid.rst

@@ -0,0 +1,48 @@
+========
+Mermaid
+========
+
+If you use `sphinxcontrib-mermaid <https://github.com/mgaitan/sphinxcontrib-mermaid>`_
+to generate flowcharts or diagrams, and you output the diagrams in "raw" format,
+they will automatically adapt to this theme's light or dark mode.
+
+To use this feature, you'll need to install `sphinxcontrib-mermaid`_ and add it to your
+list of extensions in ``conf.py``:
+
+.. code-block:: python
+
+    # conf.py
+    extensions = [
+        ...,
+        "sphinxcontrib.mermaid",
+    ]
+
+This will enable the ``.. mermaid::`` directive. For example:
+
+.. begin-example-mermaid
+.. mermaid::
+
+    gitGraph:
+        commit
+        branch newbranch
+        checkout newbranch
+        commit id:"1111"
+        commit tag:"test"
+        checkout main
+        commit type: HIGHLIGHT
+        commit
+        merge newbranch
+        commit
+        branch b2
+        commit
+.. end-example-mermaid
+
+is generated by the following code:
+
+.. include:: ./mermaid.rst
+    :start-after: begin-example-mermaid
+    :end-before: .. end-example-mermaid
+    :code: rst
+    :class: highlight
+
+See the `Mermaid documentation <https://mermaid.js.org/syntax/examples>`__ for additional examples.

pyproject.toml

@@ -73,6 +73,7 @@ doc = [
   "sphinx-design",
   "sphinx-togglebutton",
   "jupyterlite-sphinx",
+  "sphinxcontrib-mermaid",
   "sphinxcontrib-youtube>=1.4.1",
   "sphinx-favicon>=1.0.1",
   "ipykernel",

src/pydata_sphinx_theme/assets/styles/extensions/_mermaid.scss

@@ -0,0 +1,9 @@
+/**
+ * sphinxcontrib-mermaid
+ * ref: https://github.com/mgaitan/sphinxcontrib-mermaid
+ */
+
+/* Style the diagram such that it has a dark mode */
+html[data-theme="dark"] pre.mermaid > svg {
+  filter: brightness(0.8) invert(0.82) contrast(1.2);
+}

src/pydata_sphinx_theme/assets/styles/pydata-sphinx-theme.scss

@@ -78,6 +78,7 @@
 @import "./extensions/execution";
 @import "./extensions/gallery_grid";
 @import "./extensions/graphviz";
+@import "./extensions/mermaid";
 @import "./extensions/pydata";
 @import "./extensions/sphinx_design";
 @import "./extensions/togglebutton";