diff --git a/doc/content/features.md b/doc/content/features.md
index 88a5bde5..cf46322f 100644
--- a/doc/content/features.md
+++ b/doc/content/features.md
@@ -124,3 +124,25 @@ To use them elsewhere, e.g. in Hugo templates, we provide an `svg-icon` partial.
 ```
 {{ partial "svg-icon" "my-icon" }}
 ```
+
+## Mermaid diagrams
+
+[Mermaid](https://mermaid.js.org/) diagrams are rendered from code blocks:
+
+````md
+```mermaid
+graph LR
+    A[Square Rect] -- Link text --> B((Circle))
+    A --> C(Round Rect)
+    B --> D{Rhombus}
+    C --> D
+```
+````
+
+```mermaid
+graph LR
+    A[Square Rect] -- Link text --> B((Circle))
+    A --> C(Round Rect)
+    B --> D{Rhombus}
+    C --> D
+```
diff --git a/layouts/_default/_markup/render-codeblock-mermaid.html b/layouts/_default/_markup/render-codeblock-mermaid.html
new file mode 100644
index 00000000..94ea0cad
--- /dev/null
+++ b/layouts/_default/_markup/render-codeblock-mermaid.html
@@ -0,0 +1,4 @@
+<pre class="mermaid">
+  {{- .Inner | safeHTML }}
+</pre>
+{{ .Page.Store.Set "hasMermaid" true }}
diff --git a/layouts/partials/javascript.html b/layouts/partials/javascript.html
index be10cf03..5399a055 100644
--- a/layouts/partials/javascript.html
+++ b/layouts/partials/javascript.html
@@ -36,7 +36,7 @@
 </script>
 {{ end -}}
 
-{{- if .HasShortcode "mermaid" }}
+{{- if .Page.Store.Get "hasMermaid" }}
 <script type="module">
   import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10.4.0/dist/mermaid.esm.min.mjs';
 
diff --git a/layouts/shortcodes/mermaid.html b/layouts/shortcodes/mermaid.html
deleted file mode 100644
index 842302c5..00000000
--- a/layouts/shortcodes/mermaid.html
+++ /dev/null
@@ -1,24 +0,0 @@
-{{/*
-
-doc: Generate diagrams and flowcharts from markdown.
-
-{{< mermaid >}}
-graph LR
-
-START[ ]--> |Propose| A[Accept]
-A--> |Draft| B[Endorse]
-B--> |Recommend| C[Adopt]
-
-click A callback "Steering Committee Action"
-click B callback "Core Project Action"
-click C callback "Ecosystem Action"
-
-style START fill:#FFFFFF, stroke:#FFFFFF;
-
-{{< /mermaid >}}
-
-*/}}
-
-<div class="mermaid">
-  {{.Inner}}
-</div>