diff --git a/docs/source/conf.py b/docs/source/conf.py
index 428b8529..136fdb38 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -32,6 +32,7 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.githubpages",
     "sphinx.ext.napoleon",
+    "sphinxcontrib.mermaid",
 ]
 
 templates_path = ["_templates"]
@@ -59,6 +60,7 @@
 
 # MyST settings
 myst_heading_anchors = 3
+myst_fence_as_directive = ["mermaid"]
 
 # Napoleon settings
 napoleon_google_docstring = True
diff --git a/docs/source/guides/ray.md b/docs/source/guides/ray.md
index 74687aab..2a25a961 100644
--- a/docs/source/guides/ray.md
+++ b/docs/source/guides/ray.md
@@ -1,7 +1,5 @@
 # Ray Clusters & Jobs
 
----
-
 > **Audience**: You already know how to configure executors with NeMo-Run and want distributed *Ray* on either Kubernetes **or** Slurm.
 >
 > **TL;DR**: `RayCluster` manages the _cluster_; `RayJob` submits a job with an ephemeral cluster.  Everything else is syntactic sugar.
diff --git a/pyproject.toml b/pyproject.toml
index 0d43802e..7f930706 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -84,7 +84,8 @@ docs = [
     "myst-parser",
     "sphinx>=7",
     "sphinx-autoapi>=3.0.0",
-    "nvidia-sphinx-theme"
+    "nvidia-sphinx-theme",
+    "sphinxcontrib-mermaid",
 ]
 
 [build-system]