diff --git a/package-lock.json b/package-lock.json
index 65e3bf561..81d5d9af4 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -15,6 +15,7 @@
         "lodash": "^4.18.1"
       },
       "devDependencies": {
+        "@sntke/antora-mermaid-extension": "^0.0.12",
         "broken-link-checker": "^0.7.8",
         "http-server": "^14.1.1"
       }
@@ -577,6 +578,13 @@
         "node": ">=14"
       }
     },
+    "node_modules/@sntke/antora-mermaid-extension": {
+      "version": "0.0.12",
+      "resolved": "https://registry.npmjs.org/@sntke/antora-mermaid-extension/-/antora-mermaid-extension-0.0.12.tgz",
+      "integrity": "sha512-k0RcVs2BsQplecc2+Bih3s85rGi5JLvcZ1nVNG6PiOYJckEOIfVBUaEmNB8x1nrdTuhNQQTG/fXeLUx+nTfpkw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/node": {
       "version": "24.7.0",
       "resolved": "https://registry.npmjs.org/@types/node/-/node-24.7.0.tgz",
diff --git a/package.json b/package.json
index 40f7924fb..d0b22aadd 100644
--- a/package.json
+++ b/package.json
@@ -23,12 +23,13 @@
     "lodash": "^4.18.1"
   },
   "devDependencies": {
+    "@sntke/antora-mermaid-extension": "^0.0.12",
     "broken-link-checker": "^0.7.8",
     "http-server": "^14.1.1"
   },
   "overrides": {
     "asciidoctor-opal-runtime": {
       "glob": "~10.4"
+    }
   }
 }
-}
diff --git a/site.yml b/site.yml
index ca5966e60..787cd01cc 100644
--- a/site.yml
+++ b/site.yml
@@ -91,6 +91,11 @@ antora:
       printsitemapfound: true
       printcontent: false
       enabled: true
+    - require: '@sntke/antora-mermaid-extension'
+      mermaid_library_url: https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs # minified + br encoded, only ~150k to download
+      script_stem: header-scripts
+      mermaid_initialize_options:
+      start_on_load: true
     # for testing only, prints out attributes used
     # use only one or the other, output can be big
     #- ./ext-antora/attributes-used-in-site-yml.js