From 862c1caca2705ec11add0429cba12098c107d28a Mon Sep 17 00:00:00 2001
From: Tobias Gesellchen <tobias@gesellix.de>
Date: Sat, 16 May 2026 23:54:39 +0200
Subject: [PATCH] docs: render mermaid diagrams on the GitHub Pages site
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

spotify-oauth.md (and any future docs) embed mermaid sequence/flow
diagrams as fenced code blocks. Kramdown emits those as
<pre><code class="language-mermaid">, which is not what Mermaid's
auto-renderer looks for, so on the rendered site they show up as raw
code instead of diagrams.

Add docs/_includes/head-custom.html (a hook the pages-themes/minimal
remote theme already exposes) to load Mermaid 11 as an ES module from
jsDelivr, rewrite pre/code.language-mermaid nodes into div.mermaid, and
call mermaid.run() once.

No Jekyll plugin or _config.yml change needed — the include slot is
honoured by the remote theme as-is.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/_includes/head-custom.html | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)
 create mode 100644 docs/_includes/head-custom.html

diff --git a/docs/_includes/head-custom.html b/docs/_includes/head-custom.html
new file mode 100644
index 0000000..412267e
--- /dev/null
+++ b/docs/_includes/head-custom.html
@@ -0,0 +1,24 @@
+{%- comment -%}
+Render Mermaid diagrams in docs pages.
+
+Markdown ```mermaid fenced blocks are emitted by Kramdown as
+<pre><code class="language-mermaid">…</code></pre>, but Mermaid only
+auto-renders elements with class="mermaid". This snippet rewrites the
+pre/code nodes into div.mermaid before initialising the library.
+
+Loaded as an ES module from the jsDelivr CDN so we don't have to vendor
+the library into the repo. Pinned to a major version for cache stability.
+{%- endcomment -%}
+<script type="module">
+  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
+
+  document.querySelectorAll('pre > code.language-mermaid').forEach((code) => {
+    const div = document.createElement('div');
+    div.className = 'mermaid';
+    div.textContent = code.textContent;
+    code.parentElement.replaceWith(div);
+  });
+
+  mermaid.initialize({ startOnLoad: false, securityLevel: 'strict' });
+  mermaid.run();
+</script>