docs(deps): bump mkdocs-material to v8.2.1 (#2422)

* docs(deps): bump mkdocs-material to v8.2.1

* feat(docs): enable mermaid integration

Configuration based on https://squidfunk.github.io/mkdocs-material/reference/diagrams/?h=mermaid#configuration

* fix: allow yaml value mapping

* chore: Adopt mkdocs-material mermaid integration support

Supported by the docs generator now, we no longer need to rely on external image generator or live editor link (both relied on large base64 encoding of mermaid markup). SVG will be rendered by docs now, although a little different style (can be fixed with custom CSS).

Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>

.github/workflows/scripts/docs/build-docs.sh

@@ -10,7 +10,7 @@ docker run \
   --user "$(id -u):$(id -g)" \
   --volume "${PWD}:/docs" \
   --name "build-docs" \
-  squidfunk/mkdocs-material:8.1.7 build --strict
+  squidfunk/mkdocs-material:8.2.1 build --strict
 
 # Remove unnecessary build artifacts: https://github.com/squidfunk/mkdocs-material/issues/2519
 # site/ is the build output folder.

docs/content/config/security/understanding-the-ports.md

@@ -21,14 +21,8 @@ Prefer Implicit TLS ports, they're more secure and if you use a Reverse Proxy, s
 
 ### What Ports Should I Use? (SMTP)
 
-[![Best Practice - Ports (SMTP)][asset-external-mermaid-smtp]][ref-mermaid-live-smtp]
+```mermaid
-
+flowchart LR
-??? "Flowchart - Mermaid.js source:"
-
-    View in the [Live Editor][ref-mermaid-live-smtp].
-
-    ```mermaid
-    flowchart LR
     subgraph your-server ["Your Server"]
         in_25(25) --> server
         in_465(465) --> server
@@ -52,7 +46,7 @@ Prefer Implicit TLS ports, they're more secure and if you use a Reverse Proxy, s
         third-party-mta("MTA<br/>friend@example.com")
         tin_25(25) --> third-party-mta
     end
-    ```
+```
 
 ---
 
@@ -100,9 +94,7 @@ Unlike with HTTP where a web browser client communicates directly with the serve
 
 Other machines that facilitate a connection that generally aren't taken into account can exist between a client and server, such as those where your connection passes through your ISP provider are capable of compromising a cleartext connection through interception.
 
-[asset-external-mermaid-smtp]: https://mermaid.ink/img/eyJjb2RlIjoiZmxvd2NoYXJ0IExSXG4gICAgc3ViZ3JhcGggeW91ci1zZXJ2ZXIgW1wiWW91ciBTZXJ2ZXJcIl1cbiAgICAgICAgaW5fMjUoMjUpIC0tPiBzZXJ2ZXJcbiAgICAgICAgaW5fNDY1KDQ2NSkgLS0-IHNlcnZlclxuICAgICAgICBzZXJ2ZXIoKFwiZG9ja2VyLW1haWxzZXJ2ZXI8YnIvPmhlbGxvQHdvcmxkLmNvbVwiKSlcbiAgICAgICAgc2VydmVyIC0tLSBvdXRfMjUoMjUpXG4gICAgICAgIHNlcnZlciAtLS0gb3V0XzQ2NSg0NjUpXG4gICAgZW5kXG5cbiAgICB0aGlyZC1wYXJ0eShcIlRoaXJkLXBhcnR5PGJyLz4oc2VuZGluZyB5b3UgZW1haWwpXCIpIC0tLXxcIlJlY2VpdmUgZW1haWwgZm9yPGJyLz5oZWxsb0B3b3JsZC5jb21cInwgaW5fMjVcblxuICAgIHN1YmdyYXBoIGNsaWVudHMgW1wiQ2xpZW50cyAoTVVBKVwiXVxuICAgICAgICBtdWEtY2xpZW50KFRodW5kZXJiaXJkLDxici8-V2VibWFpbCw8YnIvPk11dHQsPGJyLz5ldGMpXG4gICAgICAgIG11YS1zZXJ2aWNlKEJhY2tlbmQgc29mdHdhcmU8YnIvPm9uIGFub3RoZXIgc2VydmVyKVxuICAgIGVuZFxuICAgIGNsaWVudHMgLS0tfFwiU2VuZCBlbWFpbCBhczxici8-aGVsbG9Ad29ybGQuY29tXCJ8IGluXzQ2NVxuXG4gICAgb3V0XzI1KDI1KSAtLT58XCJEaXJlY3Q8YnIvPkRlbGl2ZXJ5XCJ8IHRpbl8yNVxuICAgIG91dF80NjUoNDY1KSAtLT4gcmVsYXkoXCJNVEE8YnIvPlJlbGF5IFNlcnZlclwiKSAtLT4gdGluXzI1KDI1KVxuXG4gICAgc3ViZ3JhcGggdGhpcmQtcGFydHktc2VydmVyW1wiVGhpcmQtcGFydHkgU2VydmVyXCJdXG4gICAgICAgIHRoaXJkLXBhcnR5LW10YShcIk1UQTxici8-ZnJpZW5kQGV4YW1wbGUuY29tXCIpXG4gICAgICAgIHRpbl8yNSgyNSkgLS0-IHRoaXJkLXBhcnR5LW10YVxuICAgIGVuZCIsIm1lcm1haWQiOnsidGhlbWUiOiJkZWZhdWx0In0sInVwZGF0ZUVkaXRvciI6ZmFsc2V9
 [ref-clear-vs-plain]: https://www.denimgroup.com/resources/blog/2007/10/cleartext-vs-pl
 [ref-port25-mandatory]: https://serverfault.com/questions/623692/is-it-still-wrong-to-require-starttls-on-incoming-smtp-messages
-[ref-mermaid-live-smtp]: https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoiZmxvd2NoYXJ0IExSXG4gICAgc3ViZ3JhcGggeW91ci1zZXJ2ZXIgW1wiWW91ciBTZXJ2ZXJcIl1cbiAgICAgICAgaW5fMjUoMjUpIC0tPiBzZXJ2ZXJcbiAgICAgICAgaW5fNDY1KDQ2NSkgLS0-IHNlcnZlclxuICAgICAgICBzZXJ2ZXIoKFwiZG9ja2VyLW1haWxzZXJ2ZXI8YnIvPmhlbGxvQHdvcmxkLmNvbVwiKSlcbiAgICAgICAgc2VydmVyIC0tLSBvdXRfMjUoMjUpXG4gICAgICAgIHNlcnZlciAtLS0gb3V0XzQ2NSg0NjUpXG4gICAgZW5kXG5cbiAgICB0aGlyZC1wYXJ0eShcIlRoaXJkLXBhcnR5PGJyLz4oc2VuZGluZyB5b3UgZW1haWwpXCIpIC0tLXxcIlJlY2VpdmUgZW1haWwgZm9yPGJyLz5oZWxsb0B3b3JsZC5jb21cInwgaW5fMjVcblxuICAgIHN1YmdyYXBoIGNsaWVudHMgW1wiQ2xpZW50cyAoTVVBKVwiXVxuICAgICAgICBtdWEtY2xpZW50KFRodW5kZXJiaXJkLDxici8-V2VibWFpbCw8YnIvPk11dHQsPGJyLz5ldGMpXG4gICAgICAgIG11YS1zZXJ2aWNlKEJhY2tlbmQgc29mdHdhcmU8YnIvPm9uIGFub3RoZXIgc2VydmVyKVxuICAgIGVuZFxuICAgIGNsaWVudHMgLS0tfFwiU2VuZCBlbWFpbCBhczxici8-aGVsbG9Ad29ybGQuY29tXCJ8IGluXzQ2NVxuXG4gICAgb3V0XzI1KDI1KSAtLT58XCJEaXJlY3Q8YnIvPkRlbGl2ZXJ5XCJ8IHRpbl8yNVxuICAgIG91dF80NjUoNDY1KSAtLT4gcmVsYXkoXCJNVEE8YnIvPlJlbGF5IFNlcnZlclwiKSAtLT4gdGluXzI1KDI1KVxuXG4gICAgc3ViZ3JhcGggdGhpcmQtcGFydHktc2VydmVyW1wiVGhpcmQtcGFydHkgU2VydmVyXCJdXG4gICAgICAgIHRoaXJkLXBhcnR5LW10YShcIk1UQTxici8-ZnJpZW5kQGV4YW1wbGUuY29tXCIpXG4gICAgICAgIHRpbl8yNSgyNSkgLS0-IHRoaXJkLXBhcnR5LW10YVxuICAgIGVuZCIsIm1lcm1haWQiOnsidGhlbWUiOiJkZWZhdWx0In0sInVwZGF0ZUVkaXRvciI6ZmFsc2V9
 [rfc-8314]: https://tools.ietf.org/html/rfc8314
 [rfc-8314-s41]: https://tools.ietf.org/html/rfc8314#section-4.1

docs/mkdocs.yml

@@ -73,7 +73,11 @@ markdown_extensions:
   - attr_list
   - admonition
   - pymdownx.details
-  - pymdownx.superfences
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
   - pymdownx.magiclink
   - pymdownx.inlinehilite
   - pymdownx.tilde