diff --git a/docs/conf.py b/docs/conf.py
index a0b9f8b8b..0bad589a2 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -47,6 +47,7 @@
     "myst_parser",
     "ablog",
     "jupyter_sphinx",
+    "sphinxcontrib.mermaid",
     "sphinxcontrib.youtube",
     "nbsphinx",
     "numpydoc",
diff --git a/docs/examples/index.rst b/docs/examples/index.rst
index ad62877e8..9cf3ca747 100644
--- a/docs/examples/index.rst
+++ b/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.
diff --git a/docs/examples/mermaid.rst b/docs/examples/mermaid.rst
new file mode 100644
index 000000000..788ff4cb2
--- /dev/null
+++ b/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.
diff --git a/pyproject.toml b/pyproject.toml
index 83198b50f..bc1b880a1 100644
--- a/pyproject.toml
+++ b/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",
diff --git a/src/pydata_sphinx_theme/assets/styles/extensions/_mermaid.scss b/src/pydata_sphinx_theme/assets/styles/extensions/_mermaid.scss
new file mode 100644
index 000000000..00627b38f
--- /dev/null
+++ b/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);
+}
diff --git a/src/pydata_sphinx_theme/assets/styles/pydata-sphinx-theme.scss b/src/pydata_sphinx_theme/assets/styles/pydata-sphinx-theme.scss
index bf4573aee..56e7adcfa 100644
--- a/src/pydata_sphinx_theme/assets/styles/pydata-sphinx-theme.scss
+++ b/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";