diff --git a/docs/_static/custom_theme.css b/docs/_static/custom_theme.css
index c0f90810a124..d5723c62a480 100644
--- a/docs/_static/custom_theme.css
+++ b/docs/_static/custom_theme.css
@@ -70,3 +70,17 @@ kbd {
 table.docutils {
   width: 100%;
 }
+
+/* The mermaid extension stretches a diagram's SVG to the width of its <pre>,
+   which scales the diagram up as readily as down. */
+pre.mermaid {
+  overflow-x: auto;
+
+  /* The extension declares both of these on the same selector, from a
+     stylesheet injected after this one, so beating it takes the !important
+     and the :root prefix for specificity. */
+  :root & > svg {
+    max-width: none !important;
+    width: auto;
+  }
+}
diff --git a/docs/conf.py b/docs/conf.py
index 828607ec7ef0..64308c23cb86 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -62,13 +62,13 @@ myst_enable_extensions = [
     "fieldlist",
 ]
 
-# sphinxcontrib-mermaid otherwise forces every diagram into a 100% x 500px box,
-# which scales tall diagrams down until their labels are unreadable and blows
-# short ones up to the full width. The cap keeps a diagram near its natural size
-# and lets it shrink with the column on a narrow screen. It has to be a definite
-# width: mermaid's SVG carries a viewBox but no intrinsic width, so a
-# content-sized box collapses to the CSS default object size of 300px.
-mermaid_width = "min(100%, 45rem)"
+# A diagram renders at the size mermaid laid it out at, which needs both
+# halves: useMaxWidth below gives the SVG an intrinsic size, without which a
+# content-sized box collapses to the CSS default object size of 300px, and
+# custom_theme.css overrides the extension's own stylesheet, which stretches
+# the SVG to the width of its container. A diagram wider than the column
+# scrolls there.
+mermaid_width = "fit-content"
 mermaid_height = "auto"
 
 # startOnLoad must stay off: the extension renders via mermaid.run() itself.
@@ -79,6 +79,14 @@ mermaid_init_config = {
     "themeVariables": {
         "fontSize": "18px",
     },
+    # useMaxWidth is configured per diagram type; these are the types the tree
+    # uses.
+    "flowchart": {"useMaxWidth": False},
+    "sequence": {"useMaxWidth": False},
+    "class": {"useMaxWidth": False},
+    "state": {"useMaxWidth": False},
+    "gantt": {"useMaxWidth": False},
+    "er": {"useMaxWidth": False},
 }
 
 # The paths are loaded from config.yml so they can be shared with a CI