diff --git a/_config.yml b/_config.yml
index 348c984..2487403 100644
--- a/_config.yml
+++ b/_config.yml
@@ -51,14 +51,15 @@ search:
   # Supports true or false (default)
   button: false
 
-# To enable support for mermaid diagrams (https://mermaid-js.github.io/mermaid/),
-# uncomment the `mermaid` and `version` keys below
-# mermaid:
-#   # Version of mermaid library
-#   # Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/
-#   version: "9.1.3"
-#   # Put any additional configuration, such as setting the theme, in _includes/mermaid_config.js
-#   # See also docs/ui-components/code
+# To disable support for mermaid diagrams (https://mermaid-js.github.io/mermaid/),
+# comment out the `mermaid` and `version` keys below
+# By default, consuming the theme as a gem leaves mermaid disabled; it is opt-in
+mermaid:
+  # Version of mermaid library
+  # Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/
+  version: "9.1.6"
+  # Put any additional configuration, such as setting the theme, in _includes/mermaid_config.js
+  # See also docs/ui-components/code
 
 # Enable or disable heading anchors
 heading_anchors: true
diff --git a/docs/ui-components/code.md b/docs/ui-components/code.md
index a0d5707..1cac8aa 100644
--- a/docs/ui-components/code.md
+++ b/docs/ui-components/code.md
@@ -91,7 +91,7 @@ To demonstrate front end code, sometimes it's useful to show a rendered example
 
 ## Mermaid diagram code blocks
 
-[Mermaid](https://mermaid-js.github.io/mermaid/) allows you to add diagrams and visualizations using Markdown code blocks. You can turn on support for mermaid by adding a `mermaid` key to your `_config.yml`.
+[Mermaid](https://mermaid-js.github.io/mermaid/) allows you to add diagrams and visualizations using Markdown code blocks. **It is disabled by default**. However, you can turn on support for mermaid by adding a `mermaid` key to your `_config.yml`.
 
 The minimum configuration requires a `version` key (matching a version in [jsDelivr](https://cdn.jsdelivr.net/npm/mermaid/)):
 
@@ -131,3 +131,15 @@ graph TD;
     C-->D;
 ```
 {% endhighlight %}
+
+which renders:
+
+```mermaid
+graph TD;
+    A-->B;
+    A-->C;
+    B-->D;
+    C-->D;
+```
+
+*Note: for demonstration purposes, we've enabled mermaid on this site. It is still disabled by default, and users need to opt-in to use it.*