diff --git a/docs/conf.py b/docs/conf.py
index 674716a49..3007bb5c3 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -22,7 +22,7 @@
 from distutils.version import LooseVersion
 
 import sphinx
-from m2r import MdInclude
+from m2r2 import MdInclude
 from sphinx_gallery.sorting import FileNameSortKey
 
 sys.path.insert(0, os.path.abspath(os.path.pardir))
@@ -55,6 +55,7 @@
     "sphinx_gallery.gen_gallery",  # example gallery
     "sphinxarg.ext",  # argparse
     "sphinxcontrib.bibtex",  # for foot-citations
+    "sphinxcontrib.mermaid",  # for mermaid diagrams
     "recommonmark",  # markdown parser
 ]
 
@@ -227,6 +228,7 @@ def setup(app):
     app.add_config_value("m2r_parse_relative_links", False, "env")
     app.add_config_value("m2r_anonymous_references", False, "env")
     app.add_config_value("m2r_disable_inline_math", False, "env")
+    app.add_config_value("m2r_use_mermaid", True, "env")
     app.add_directive("mdinclude", MdInclude)
 
 
diff --git a/setup.cfg b/setup.cfg
index 351bd4e80..f7e2c6d2d 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -70,9 +70,9 @@ gzip =
 cbmr = 
     torch>=2.0 # for cbmr models
 doc =
-    m2r
+    m2r2
     matplotlib
-    mistune<2  # just temporary until m2r addresses this issue
+    mistune
     pillow
     recommonmark
     seaborn
@@ -82,6 +82,8 @@ doc =
     sphinx-gallery
     sphinx_rtd_theme>=1.3.0
     sphinxcontrib-bibtex
+    sphinxcontrib-mermaid
+    docutils>=0.18.1,<0.21  # https://github.com/orgs/sphinx-doc/discussions/13020
 tests =
     coverage
     coveralls