diff --git a/docs/conf.py b/docs/conf.py
index 691a0c223d..c66bf0b8ee 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -102,6 +102,12 @@
 myst_enable_extensions = ("fieldlist",)
 
 
+# -- Options for sphinxcontrib.mermaid
+# https://pypi.org/project/sphinxcontrib-mermaid/
+
+extensions.append("sphinxcontrib.mermaid")
+
+
 # -- Options for sphinx_last_updated_by_git
 # https://pypi.org/project/sphinx-last-updated-by-git/
 
diff --git a/docs/source/dev/docs.md b/docs/source/dev/docs.md
index e4e8efda9a..41d34ccdf9 100644
--- a/docs/source/dev/docs.md
+++ b/docs/source/dev/docs.md
@@ -57,6 +57,8 @@ sphinx-build -M html docs/source docs/build -c docs
 
 The theme used is [*furo*](https://pypi.org/project/furo/).
 
+### Markup
+
 The default markup language for Sphinx is
 [*reStructuredText*](https://docutils.sourceforge.io/rst.html).
 The [usage of *Markdown*](https://www.sphinx-doc.org/en/master/usage/markdown.html)
@@ -68,6 +70,8 @@ To learn how to use these features in Markdown documents,
 one should refer to the MyST documentation.
 The docstrings in Python code are still to be written with Restructuredtext syntax, though.
 
+### Python code
+
 The documentation system is configured to generate {doc}`API documentation </dev/api>`
 based on the Python code.
 The Sphinx extension used to do this is
@@ -79,3 +83,41 @@ The
 extension is enabled to handle docstrings within the Python code
 and it is configured for
 [Google-style docstrings](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings).
+
+### Diagrams
+
+The
+[*`sphinxcontrib-mermaid`*](https://pypi.org/project/sphinxcontrib-mermaid)
+extension is enabled to allow embedding [*Mermaid* diagrams](https://mermaid.js.org/)
+in the documentation.
+
+For example the following code in a Markdown document:
+
+~~~markdown
+```{mermaid}
+sequenceDiagram
+participant Alice
+participant Bob
+Alice->John: Hello John, how are you?
+```
+~~~
+
+or the following in a ReStructuredText document:
+
+```restructuredtext
+.. mermaid::
+
+    sequenceDiagram
+    participant Alice
+    participant Bob
+    Alice->John: Hello John, how are you?
+```
+
+produce the following diagram:
+
+```{mermaid}
+sequenceDiagram
+participant Alice
+participant Bob
+Alice->John: Hello John, how are you?
+```
diff --git a/poetry.lock b/poetry.lock
index 5c65db08f2..1d8d6cad37 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -2281,6 +2281,17 @@ files = [
 [package.extras]
 test = ["flake8", "mypy", "pytest"]
 
+[[package]]
+name = "sphinxcontrib-mermaid"
+version = "0.9.2"
+description = "Mermaid diagrams in yours Sphinx powered docs"
+optional = false
+python-versions = ">=3.7"
+files = [
+    {file = "sphinxcontrib-mermaid-0.9.2.tar.gz", hash = "sha256:252ef13dd23164b28f16d8b0205cf184b9d8e2b714a302274d9f59eb708e77af"},
+    {file = "sphinxcontrib_mermaid-0.9.2-py3-none-any.whl", hash = "sha256:6795a72037ca55e65663d2a2c1a043d636dc3d30d418e56dd6087d1459d98a5d"},
+]
+
 [[package]]
 name = "sphinxcontrib-qthelp"
 version = "1.0.3"
@@ -2561,4 +2572,4 @@ tango = ["PyTango"]
 [metadata]
 lock-version = "2.0"
 python-versions = ">=3.8,<3.11"
-content-hash = "067aba2ba09ae4acef333b31b15ca53601a4d8597290c03b7fb13812e4ce7cf8"
+content-hash = "8eeb0d01d4197325547e93827e9299b7d1ab7ef85be7a0a183e07383a5776b6e"
diff --git a/pyproject.toml b/pyproject.toml
index dee65aba3e..6bfbb2612e 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -62,6 +62,7 @@ furo = "^2023.9.10"
 myst-parser = "^2.0.0"
 sphinx = "<7.2"
 sphinx-last-updated-by-git = "^0.3.7"
+sphinxcontrib-mermaid = "^0.9.2"
 
 [tool.poetry.extras]
 tango = ["PyTango"]