From d6a23ba54d99d9fb26ae3385b25f114a1263ce01 Mon Sep 17 00:00:00 2001
From: Jelmer de Wit <1598297+jdwit@users.noreply.github.com>
Date: Sun, 31 May 2026 21:05:53 +0200
Subject: [PATCH] docs: enable mermaid diagrams via pymdownx.superfences
 custom_fences

docs/livestreams.md already contains a flowchart-LR mermaid block,
but it rendered as a literal code block because the SuperFences
custom-fences handler wasn't configured. Material for MkDocs bundles
Mermaid.js automatically when the fence is declared this way -- no
extra plugin or runtime dependency.

Verified by building locally with `uv run mkdocs build --strict`:
the livestreams page now emits `<pre class="mermaid">` which the
Material runtime upgrades into an interactive diagram.

Versions confirmed against the latest releases on PyPI via
context7 + the squidfunk reference docs:
- mkdocs 1.6.x (current floor `>=1.6` accepts 1.6.1)
- mkdocs-material 9.7.x (current floor `>=9.5` accepts 9.7.6)
- pymdown-extensions 10.21.x (current floor `>=10.7` accepts; the
  fence_code_format format has been stable since 9.x)

No pyproject.toml changes needed; the existing docs deps are
already loose enough to pull the latest minors.

See https://squidfunk.github.io/mkdocs-material/reference/diagrams/
---
 mkdocs.yml | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/mkdocs.yml b/mkdocs.yml
index cb6b69a..0b1b57b 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -66,7 +66,15 @@ markdown_extensions:
       pygments_lang_class: true
   - pymdownx.inlinehilite
   - pymdownx.snippets
-  - pymdownx.superfences
+  - pymdownx.superfences:
+      # Mermaid.js fence handler. Material for MkDocs bundles
+      # Mermaid automatically when a `mermaid` custom-fence is
+      # declared; no separate plugin install is needed. See
+      # https://squidfunk.github.io/mkdocs-material/reference/diagrams/
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
   - pymdownx.tabbed:
       alternate_style: true
   - pymdownx.tasklist: