From fb4c81e53f1f6ac63fcaafff701c9e533a11d147 Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Mon, 25 Aug 2025 00:19:26 +0200 Subject: [PATCH 1/4] Fix display of mermaid diagrams in dark mode 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). --- .../assets/styles/extensions/_mermaid.scss | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 src/pydata_sphinx_theme/assets/styles/extensions/_mermaid.scss 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); +} From c6ff0642569708ee3d1d37a046a05cbb74a26b71 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 25 Aug 2025 15:51:50 -0500 Subject: [PATCH 2/4] install mermaid for our doc build --- docs/conf.py | 1 + pyproject.toml | 1 + 2 files changed, 2 insertions(+) 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/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", From 24d9478314a0c12d591cb0ea41a86c188c2769fc Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 25 Aug 2025 15:52:10 -0500 Subject: [PATCH 3/4] make sure the new CSS gets used --- src/pydata_sphinx_theme/assets/styles/pydata-sphinx-theme.scss | 1 + 1 file changed, 1 insertion(+) 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"; From 09d391263ff122cbc4c110f285859273f7c44620 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 25 Aug 2025 15:52:37 -0500 Subject: [PATCH 4/4] add documentation --- docs/examples/index.rst | 1 + docs/examples/mermaid.rst | 48 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 49 insertions(+) create mode 100644 docs/examples/mermaid.rst 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 `_ +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 `__ for additional examples.