diff --git a/assets/scss/_code.scss b/assets/scss/_code.scss
index 7f2193a887..d491beeb45 100644
--- a/assets/scss/_code.scss
+++ b/assets/scss/_code.scss
@@ -47,4 +47,9 @@
             border: 0;
         }
     }
+
+    pre.mermaid {
+        background-color: inherit;
+        font-size: 0;
+    }
 }
diff --git a/layouts/partials/scripts.html b/layouts/partials/scripts.html
index 9a308eb761..ca06e73f25 100644
--- a/layouts/partials/scripts.html
+++ b/layouts/partials/scripts.html
@@ -18,4 +18,58 @@
 <!-- scripts for prism -->
 <script src='/js/prism.js'></script>
 {{ end }}
+
+{{ with .Site.Params.mermaid }}
+{{ if .enable }}
+<!-- scripts for mermaid -->
+<script src="https://cdn.jsdelivr.net/npm/mermaid@8.8.0/dist/mermaid.min.js" integrity="sha384-OBYc88+eQm2E+Vw9J6jK9Z9rY4rcY+Mq5KlRpOzFTiHZV0Misu7O5AKmBOWGKk8j" crossorigin="anonymous"></script>
+<script>
+(function() {
+    var needMermaid = false;
+    $('.language-mermaid').parent().replaceWith(function() {
+        needMermaid = true;
+        return $('<pre class="mermaid">').text($(this).text());
+    });
+
+    if (!needMermaid)  {
+        mermaid.initialize({startOnLoad: false});
+        return;
+    }
+
+    var params = {{ . | jsonify | safeJS }};
+
+    // site params are stored with lowercase keys; lookup correct casing
+    // from Mermaid default config.
+    var norm = function(defaultConfig, params) {
+        var result = {};
+        for (const key in defaultConfig) {
+            const keyLower = key.toLowerCase();
+            if (defaultConfig.hasOwnProperty(key) && params.hasOwnProperty(keyLower)) {
+                if (typeof defaultConfig[key] === "object") {
+                    result[key] = norm(defaultConfig[key], params[keyLower]);
+                } else {
+                    result[key] = params[keyLower];
+                }
+            }
+        }
+        return result;
+    };
+    // Mermaid 8.8.0 doesn't yet expose this in defaultConfig; next release will.
+    // See https://github.com/mermaid-js/mermaid/issues/1490
+    mermaid.mermaidAPI.defaultConfig.useMaxWidth = true;
+    mermaid.mermaidAPI.defaultConfig.flowchart.useMaxWidth = true;
+    mermaid.mermaidAPI.defaultConfig.sequence.useMaxWidth = true;
+    mermaid.mermaidAPI.defaultConfig.gantt.useMaxWidth = true;
+    mermaid.mermaidAPI.defaultConfig.journey.useMaxWidth = true;
+    mermaid.mermaidAPI.defaultConfig.git.useMaxWidth = true;
+    mermaid.mermaidAPI.defaultConfig.state.useMaxWidth = true;
+    mermaid.mermaidAPI.defaultConfig.er.useMaxWidth = true;
+
+    var settings = norm(mermaid.mermaidAPI.defaultConfig, params);
+    settings.startOnLoad = true;
+    mermaid.initialize(settings);
+})();
+</script>
+{{ end }}
+{{ end }}
 {{ partial "hooks/body-end.html" . }}
diff --git a/userguide/config.toml b/userguide/config.toml
index e5942a3dd3..82eeb508e6 100644
--- a/userguide/config.toml
+++ b/userguide/config.toml
@@ -199,3 +199,7 @@ enable = false
 	# url = "https://example.org/mail"
 	# icon = "fa fa-envelope"
         # desc = "Discuss development issues around the project"
+
+[params.mermaid]
+enable = true
+theme = "default"
diff --git a/userguide/content/en/docs/Adding content/lookandfeel.md b/userguide/content/en/docs/Adding content/lookandfeel.md
index ce94413250..12fa6cca01 100644
--- a/userguide/content/en/docs/Adding content/lookandfeel.md	
+++ b/userguide/content/en/docs/Adding content/lookandfeel.md	
@@ -140,6 +140,57 @@ If the included Prism configuration is not sufficient for your requirements, and
     * Copy the Javascript file to `static/js/prism.js`
     * Copy the CSS file to `static/css/prism.css`
 
+## Diagrams with Mermaid
+
+[Mermaid](https://mermaid-js.github.io) is a Javascript library for rendering simple text definitions to useful diagrams in the browser.  It can generate a variety of different diagram types, including flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, user journey diagrams, Gantt charts and pie charts.
+
+With Mermaid support enabled in Docsy, you can include the text definition of a Mermaid diagram inside a code block, and it will automatically be rendered by the browser as soon as the page loads.
+
+The great advantage of this is anyone who can edit the page can now edit the diagram - no more hunting for the original tools and version to make a new edit.
+
+For example, the following defines a simple flowchart:
+
+````
+```mermaid
+graph LR
+  Start --> Need{"Do I need diagrams"}
+  Need -- No --> Off["Set params.mermaid.enable = false"]
+  Need -- Yes --> HaveFun["Great!  Enjoy!"]
+```
+````
+
+Automatically renders to:
+
+```mermaid
+graph LR
+  Start --> Need{"Do I need diagrams"}
+  Need -- No --> Off["Set params.mermaid.enable = false"]
+  Need -- Yes --> HaveFun["Great!  Enjoy!"]
+
+```
+
+To enable/disable Mermaid, update `config.toml`:
+
+```toml
+[params.mermaid]
+enable = true
+```
+
+You can also update settings for Mermaid, such as themes, padding, etc:
+
+```toml
+[params.mermaid]
+enable = true
+theme = "neutral"
+
+[params.mermaid.flowchart]
+diagramPadding = 6
+```
+
+See the [Mermaid documentation](https://mermaid-js.github.io/mermaid/getting-started/Setup.html#mermaidapi-configuration-defaults) for a list of defaults that can be overriden.
+
+Settings can also be overridden on a per-diagram basis by making use of the `%%init%%` header at the start of the diagram definition.  See the [Mermaid theming documentation](https://mermaid-js.github.io/mermaid/getting-started/theming.html#themes-at-the-local-or-current-level).
+
 ## Customizing templates
 
 ### Add code to head or before body end