Documentation

docs/reference/diagrams.md

@@ -283,3 +283,34 @@ we don't consider them a good choice, mostly as they don't work well on mobile.
   [user journeys]: https://mermaid.js.org/syntax/userJourney.html
   [git graphs]: https://mermaid.js.org/syntax/gitgraph.html
   [requirement diagrams]: https://mermaid.js.org/syntax/requirementDiagram.html
+
+## Customization
+
+If you want to customize Mermaid.js, e.g. to bring in support for [ELK layouts],
+you can do so by adding a custom JavaScript file to your `mkdocs.yml`:
+
+=== ":octicons-file-code-16: `docs/javascripts/mermaid.mjs`"
+
+    ``` js
+    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
+    import elkLayouts from 'https://cdn.jsdelivr.net/npm/@mermaid-js/layout-elk@0/dist/mermaid-layout-elk.esm.min.mjs';
+
+    mermaid.registerLayoutLoaders(elkLayouts);
+    mermaid.initialize({
+      startOnLoad: false,
+      securityLevel: "loose",
+      layout: "elk",
+    });
+
+    // Important: necessary to make it visible to Material for MkDocs
+    window.mermaid = mermaid;
+    ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+    ``` yaml
+    extra_javascript:
+      - javascripts/mermaid.mjs
+    ```
+
+  [ELK layouts]: https://www.npmjs.com/package/@mermaid-js/layout-elk