Added documentation for native Mermaid integration (experimental)

Author: squidfunk

docs/assets/screenshots/diagram.png

@@ -104,6 +104,7 @@ The following features are currently exclusively available to sponsors:
 - [x] [Versioning][14]
 - [x] [Site language selection][13]
 - [x] [Sticky navigation tabs][19]
+- [x] [Native Mermaid.js integration][21]
 - [x] [Admonition inline blocks][12]
 - [x] [Search suggestions][16]
 - [x] [Search highlighting][17]
@@ -162,9 +163,15 @@ the public for general availability.
   [19]: setup/setting-up-navigation.md#sticky-navigation-tabs
   [20]: setup/setting-up-the-footer.md#remove-generator
 
+#### $ 5,000 - Aji Panca
+
+- [x] [Native Mermaid.js integration][21]
+
+  [21]: reference/diagrams.md
+
 #### Future
 
-- [ ] [Material for MkDocs Live Edit][21]
+- [ ] [Material for MkDocs Live Edit][22]
 - [ ] Improved search result summaries
 - [ ] List of last searches
 - [ ] Table of contents follows active anchor
@@ -174,7 +181,7 @@ the public for general availability.
 - [ ] New layouts and styles (e.g. vertical)
 - [ ] ... and much more ...
 
-  [21]: https://twitter.com/squidfunk/status/1338252230265360391
+  [22]: https://twitter.com/squidfunk/status/1338252230265360391
 
 ### Goals completed
 
@@ -210,10 +217,10 @@ implemented behind feature flags; all configuration changes are
 backward-compatible. This means that your users will be able to build the
 documentation locally with Material for MkDocs and when they push their changes,
 it can be built with Insiders (e.g. as part of GitHub Actions). Thus, it's
-recommended to [install Insiders][22] only in CI, as you don't want to expose
+recommended to [install Insiders][23] only in CI, as you don't want to expose
 your `GH_TOKEN` to users.
 
-  [22]: publishing-your-site.md#github-pages
+  [23]: publishing-your-site.md#github-pages
 
 ### Terms
 
@@ -222,7 +229,7 @@ commercial project. Can we use Insiders under the same terms and conditions?_
 
 Yes. Whether you're an individual or a company, you may use _Material for MkDocs
 Insiders_ precisely under the same terms as Material for MkDocs, which are given
-by the [MIT license][23]. However, we kindly ask you to respect the following
+by the [MIT license][24]. However, we kindly ask you to respect the following
 guidelines:
 
 - Please __don't distribute the source code__ of Insiders. You may freely use
@@ -233,7 +240,7 @@ guidelines:
 - If you cancel your subscription, you're removed as a collaborator and will
   miss out on future updates of Insiders. However, you may __use the latest
   version__ that's available to you __as long as you like__. Just remember that
-  [GitHub deletes private forks][24].
+  [GitHub deletes private forks][25].
 
-  [23]: license.md
-  [24]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository
+  [24]: license.md
+  [25]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository

docs/insiders.md

@@ -0,0 +1,99 @@
+---
+template: overrides/main.html
+---
+
+# Diagrams
+
+Diagrams help to communicate complex relationships and interconnections between
+different technical components, and are a great addition to project
+documentation. Material for MkDocs integrates with [Mermaid.js][1], a very
+popular and flexible solution for drawing diagrams.
+
+  [1]: https://mermaid-js.github.io/mermaid/
+
+## Configuration
+
+### SuperFences
+
+[:octicons-file-code-24: Source][2] ·
+:octicons-beaker-24: Experimental ·
+[:octicons-heart-fill-24:{: .tx-heart } Insiders only][2]{: .tx-insiders }
+
+The [SuperFences][3] extension, which is part of [Python Markdown
+Extensions][4], allows for adding __custom fences__, which can be used to
+render [Mermaid.js][1] diagrams with zero effort:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.superfences
+      custom_fences:
+        - name: mermaid
+          class: mermaid-experimental
+          format: !!pymdownx.superfences.fence_code_format
+```
+
+No further configuration is necessary. Material for MkDocs will automatically
+load and initialize the [Mermaid.js][1] runtime when a page includes a [fenced
+`mermaid` block][5]. Furthermore:
+
+- [x] Works with [instant loading][6] without any additional effort
+- [x] Diagrams automatically use fonts and colors defined in `mkdocs.yml`[^1]
+- [x] Fonts and colors can be customized with [additional stylesheets][7]
+- [x] Support for both, light and dark color schemes
+
+_While it's also possible to integrate [Mermaid.js][1] using existing
+third-party solutions[^2], the new native integration is recommended as it
+ensures interoperability with all Material for MkDocs features._
+
+  [^1]:
+    While all [Mermaid.js][1] features should work out-of-the-box, Material for
+    MkDocs will currently only adjust the fonts and colors for flow charts,
+    class and state diagrams. Support for further diagram types will be added
+    gradually.
+
+  [^2]:
+    If you don't want to use the native integration, [mkdocs-mermaid2-plugin][8]
+    might be a good alternative. However, note that this plugin cannot be used
+    in conjunction with the [mkdocs-minify-plugin][9] and doesn't integrate
+    natively.
+
+  [2]: ../insiders.md
+  [3]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
+  [4]: https://facelessuser.github.io/pymdown-extensions/
+  [5]: #usage
+  [6]: ../setup/setting-up-navigation.md#instant-loading
+  [7]: ../customization.md#additional-css
+  [8]: https://github.com/fralau/mkdocs-mermaid2-plugin
+  [9]: https://github.com/byrnereese/mkdocs-minify-plugin
+
+## Usage
+
+### Using diagrams
+
+Mermaid diagrams are written as [code blocks][10] with the help of the
+[SuperFences][11] extension. They must be enclosed with two separate lines
+containing three backticks:
+
+_Example_:
+
+```` markdown
+``` mermaid
+graph LR
+  A[Start] --> B{Error?};
+  B -->|Yes| C[Hmm...];
+  C --> D[Debug];
+  D --> B;
+  B ---->|No| E[Yay!];
+```
+````
+
+_Result_:
+
+[![Diagram][12]{: style="width: 100%; max-width: 594px" }][12]
+
+_See the [official documentation][1] to learn about all available diagram 
+types._
+
+  [10]: code-blocks.md
+  [11]: #superfences
+  [12]: ../assets/screenshots/diagram.png

docs/reference/diagrams.md

@@ -67,7 +67,7 @@ information._
 !!! tip "Using MathJax with [instant loading][9]"
 
     There's no additional effort necessary to integrate _MathJax 3_ with
-    [instant loading][7] – it's expected to work straight away. However, a
+    [instant loading][9] – it's expected to work straight away. However, a
     previous version of this document explained how to integrate Material for
     MkDocs with _MathJax 2_, which doesn't exhibit this behavior. It's therefore
     highly recommended to switch to _MathJax 3_.

docs/reference/mathjax.md

@@ -1,6 +1,6 @@
 {
-  "assets/javascripts/bundle.js": "assets/javascripts/bundle.ab328eb8.min.js",
-  "assets/javascripts/bundle.js.map": "assets/javascripts/bundle.ab328eb8.min.js.map",
+  "assets/javascripts/bundle.js": "assets/javascripts/bundle.83e5331e.min.js",
+  "assets/javascripts/bundle.js.map": "assets/javascripts/bundle.83e5331e.min.js.map",
   "assets/javascripts/vendor.js": "assets/javascripts/vendor.93c04032.min.js",
   "assets/javascripts/vendor.js.map": "assets/javascripts/vendor.93c04032.min.js.map",
   "assets/javascripts/worker/search.js": "assets/javascripts/worker/search.8c7e0a7e.min.js",

material/assets/javascripts/bundle.ab328eb8.min.js renamed to material/assets/javascripts/bundle.83e5331e.min.js

@@ -185,7 +185,7 @@ <h1>{{ page.title | d(config.site_name, true)}}</h1>
     </div>
     {% block scripts %}
       <script src="{{ 'assets/javascripts/vendor.93c04032.min.js' | url }}"></script>
-      <script src="{{ 'assets/javascripts/bundle.ab328eb8.min.js' | url }}"></script>
+      <script src="{{ 'assets/javascripts/bundle.83e5331e.min.js' | url }}"></script>
       {%- set translations = {} -%}
       {%- for key in [
         "clipboard.copy",

material/assets/javascripts/bundle.83e5331e.min.js.map

@@ -176,6 +176,7 @@ nav:
     - Code blocks: reference/code-blocks.md
     - Content tabs: reference/content-tabs.md
     - Data tables: reference/data-tables.md
+    - Diagrams: reference/diagrams.md
     - Footnotes: reference/footnotes.md
     - Formatting: reference/formatting.md
     - Icons + Emojis: reference/icons-emojis.md