Documentation

docs/reference/diagrams.md

@@ -16,7 +16,7 @@ popular and flexible solution for drawing diagrams.
 <!-- md:version 8.2.0 -->
 
 This configuration enables native support for [Mermaid.js] diagrams. Material
-for MkDocs will automatically initialize the JavaScript runtime when a page 
+for MkDocs will automatically initialize the JavaScript runtime when a page
 includes a `mermaid` code block:
 
 ``` yaml
@@ -38,7 +38,7 @@ No further configuration is necessary. Advantages over a custom integration:
   [^1]:
     While all [Mermaid.js] features should work out-of-the-box, Material for
     MkDocs will currently only adjust the fonts and colors for flowcharts,
-    sequence diagrams, class diagrams, state diagrams and entity relationship 
+    sequence diagrams, class diagrams, state diagrams and entity relationship
     diagrams. See the section on [other diagrams] for more information why this
     is currently not implemented for all diagrams.
 
@@ -82,7 +82,7 @@ graph LR
 
 ### Using sequence diagrams
 
-[Sequence diagrams] describe a specific scenario as sequential interactions 
+[Sequence diagrams] describe a specific scenario as sequential interactions
 between multiple objects or actors, including the messages that are exchanged
 between those actors:
 
@@ -194,7 +194,7 @@ classDiagram
     +int postalCode
     +String country
     -validate()
-    +outputAsLabel()  
+    +outputAsLabel()
   }
 ```
 ````
@@ -226,7 +226,7 @@ classDiagram
     +int postalCode
     +String country
     -validate()
-    +outputAsLabel()  
+    +outputAsLabel()
   }
 ```
 
@@ -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