From 84ab26408d1e3065015255fc5e3d09d3655f06d4 Mon Sep 17 00:00:00 2001
From: Marko Vejnovic <marko@harmont.dev>
Date: Mon, 13 Jul 2026 21:50:58 +0000
Subject: [PATCH 1/2] fix(docs): render Mermaid/KaTeX on swup navigation, not
 only full load

ExDoc uses swup for client-side page transitions, so DOMContentLoaded and
the KaTeX auto-render onload fire only on the initial hard load. After any
in-docs navigation (sidebar link, internal link, HexDocs search) both
Mermaid diagrams and $$..$$ math were left as raw source. Drive all
rendering from ExDoc's window `exdoc:loaded` event, which fires on the
initial load and after every swup content swap. Also fix the Mermaid
selector: ExDoc emits <pre><code class="mermaid">, not <pre class="mermaid">.

Closes HYP-10 (#82).
---
 mix.exs | 69 +++++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 48 insertions(+), 21 deletions(-)

diff --git a/mix.exs b/mix.exs
index 4c4bdcb7..49b9564e 100644
--- a/mix.exs
+++ b/mix.exs
@@ -151,30 +151,57 @@ defmodule Hyper.MixProject do
     """
     <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css" crossorigin="anonymous">
     <script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.js" crossorigin="anonymous"></script>
-    <script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/contrib/auto-render.min.js" crossorigin="anonymous"
-    onload="renderMathInElement(document.body, {delimiters: [
-      {left: '$$', right: '$$', display: true},
-      {left: '$', right: '$', display: false},
-      {left: '\\\\[', right: '\\\\]', display: true},
-      {left: '\\\\(', right: '\\\\)', display: false}
-    ]});"></script>
+    <script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/contrib/auto-render.min.js" crossorigin="anonymous"></script>
     <script src="https://cdn.jsdelivr.net/npm/mermaid@11.4.1/dist/mermaid.min.js" integrity="sha384-rbtjAdnIQE/aQJGEgXrVUlMibdfTSa4PQju4HDhN3sR2PmaKFzhEafuePsl9H/9I" crossorigin="anonymous"></script>
     <script>
-      document.addEventListener("DOMContentLoaded", function () {
-        mermaid.initialize({
-          startOnLoad: false,
-          theme: document.body.className.includes("dark") ? "dark" : "default"
-        });
-        let id = 0;
-        for (const pre of document.querySelectorAll("pre.mermaid")) {
-          const code = pre.textContent;
-          const div = document.createElement("div");
-          div.className = "mermaid";
-          div.textContent = code;
-          pre.replaceWith(div);
+      // ExDoc moves between pages with swup (client-side transitions): a full
+      // load -- and therefore DOMContentLoaded and a script's onload -- fires
+      // only once, on first arrival. ExDoc re-emits `exdoc:loaded` on window
+      // after every swup content swap as well as on the initial load, so all
+      // rendering must hang off it; otherwise KaTeX and Mermaid go unrendered
+      // the moment a reader navigates within the docs.
+      (function () {
+        let mermaidReady = false;
+
+        function renderMath() {
+          if (typeof window.renderMathInElement !== "function") return;
+          renderMathInElement(document.body, {
+            delimiters: [
+              {left: "$$", right: "$$", display: true},
+              {left: "$", right: "$", display: false},
+              {left: "\\\\[", right: "\\\\]", display: true},
+              {left: "\\\\(", right: "\\\\)", display: false}
+            ]
+          });
         }
-        mermaid.run();
-      });
+
+        function renderMermaid() {
+          if (typeof window.mermaid === "undefined") return;
+          if (!mermaidReady) {
+            mermaid.initialize({
+              startOnLoad: false,
+              theme: document.body.className.includes("dark") ? "dark" : "default"
+            });
+            mermaidReady = true;
+          }
+          // ExDoc renders ```mermaid fences as <pre><code class="mermaid">; lift
+          // each into a bare <div class="mermaid"> for Mermaid to render into.
+          for (const code of document.querySelectorAll("pre > code.mermaid")) {
+            const div = document.createElement("div");
+            div.className = "mermaid";
+            div.textContent = code.textContent;
+            code.parentElement.replaceWith(div);
+          }
+          mermaid.run({nodes: document.querySelectorAll("div.mermaid:not([data-processed])")});
+        }
+
+        function render() {
+          renderMath();
+          renderMermaid();
+        }
+
+        window.addEventListener("exdoc:loaded", render);
+      })();
     </script>
     """
   end

From 5567e2418ecab37f3683a53ae31add610aa535c2 Mon Sep 17 00:00:00 2001
From: Marko Vejnovic <marko@harmont.dev>
Date: Mon, 13 Jul 2026 23:34:25 +0000
Subject: [PATCH 2/2] refactor(docs): use ExDoc's canonical KaTeX/Mermaid
 recipe

Replace the hand-rolled DOM surgery with the snippet ExDoc's own README
prescribes: two `exdoc:loaded` listeners, KaTeX via renderMathInElement, and
Mermaid via mermaid.render() per <pre code.mermaid> block. Drops the unused
\[ / \( delimiters (docs use only $ / $$), which removes the quad-backslash
heredoc escaping, and loads mermaid with defer to match the reference. Same
behavior, verified: KaTeX + Mermaid render on both hard load and swup nav.
---
 mix.exs | 81 ++++++++++++++++++++++++---------------------------------
 1 file changed, 34 insertions(+), 47 deletions(-)

diff --git a/mix.exs b/mix.exs
index 49b9564e..bc4c92c8 100644
--- a/mix.exs
+++ b/mix.exs
@@ -145,63 +145,50 @@ defmodule Hyper.MixProject do
     ]
   end
 
-  # Load Mermaid in the HTML docs and render any ```mermaid code fences as
-  # diagrams. ExDoc tags Mermaid blocks with the `mermaid` class.
+  # KaTeX (math) and Mermaid (diagrams) rendering for the HTML docs. This is the
+  # recipe ExDoc's own README prescribes: ExDoc navigates between pages with
+  # swup (client-side content swaps) and re-fires `exdoc:loaded` on window after
+  # every swap as well as on the initial load. Hanging rendering off that event
+  # -- rather than DOMContentLoaded / a script `onload`, which fire only once --
+  # is what keeps math and diagrams rendered as a reader navigates the docs.
   defp before_closing_body_tag(:html) do
     """
     <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css" crossorigin="anonymous">
     <script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.js" crossorigin="anonymous"></script>
     <script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/contrib/auto-render.min.js" crossorigin="anonymous"></script>
-    <script src="https://cdn.jsdelivr.net/npm/mermaid@11.4.1/dist/mermaid.min.js" integrity="sha384-rbtjAdnIQE/aQJGEgXrVUlMibdfTSa4PQju4HDhN3sR2PmaKFzhEafuePsl9H/9I" crossorigin="anonymous"></script>
+    <script defer src="https://cdn.jsdelivr.net/npm/mermaid@11.4.1/dist/mermaid.min.js" integrity="sha384-rbtjAdnIQE/aQJGEgXrVUlMibdfTSa4PQju4HDhN3sR2PmaKFzhEafuePsl9H/9I" crossorigin="anonymous"></script>
     <script>
-      // ExDoc moves between pages with swup (client-side transitions): a full
-      // load -- and therefore DOMContentLoaded and a script's onload -- fires
-      // only once, on first arrival. ExDoc re-emits `exdoc:loaded` on window
-      // after every swup content swap as well as on the initial load, so all
-      // rendering must hang off it; otherwise KaTeX and Mermaid go unrendered
-      // the moment a reader navigates within the docs.
-      (function () {
-        let mermaidReady = false;
-
-        function renderMath() {
-          if (typeof window.renderMathInElement !== "function") return;
-          renderMathInElement(document.body, {
-            delimiters: [
-              {left: "$$", right: "$$", display: true},
-              {left: "$", right: "$", display: false},
-              {left: "\\\\[", right: "\\\\]", display: true},
-              {left: "\\\\(", right: "\\\\)", display: false}
-            ]
+      window.addEventListener("exdoc:loaded", () => {
+        renderMathInElement(document.body, {
+          delimiters: [
+            {left: "$$", right: "$$", display: true},
+            {left: "$", right: "$", display: false}
+          ]
+        });
+      });
+
+      let mermaidInitialized = false;
+      window.addEventListener("exdoc:loaded", () => {
+        if (!mermaidInitialized) {
+          mermaid.initialize({
+            startOnLoad: false,
+            theme: document.body.className.includes("dark") ? "dark" : "default"
           });
+          mermaidInitialized = true;
         }
 
-        function renderMermaid() {
-          if (typeof window.mermaid === "undefined") return;
-          if (!mermaidReady) {
-            mermaid.initialize({
-              startOnLoad: false,
-              theme: document.body.className.includes("dark") ? "dark" : "default"
-            });
-            mermaidReady = true;
-          }
-          // ExDoc renders ```mermaid fences as <pre><code class="mermaid">; lift
-          // each into a bare <div class="mermaid"> for Mermaid to render into.
-          for (const code of document.querySelectorAll("pre > code.mermaid")) {
-            const div = document.createElement("div");
-            div.className = "mermaid";
-            div.textContent = code.textContent;
-            code.parentElement.replaceWith(div);
-          }
-          mermaid.run({nodes: document.querySelectorAll("div.mermaid:not([data-processed])")});
-        }
-
-        function render() {
-          renderMath();
-          renderMermaid();
+        let id = 0;
+        for (const codeEl of document.querySelectorAll("pre code.mermaid")) {
+          const preEl = codeEl.parentElement;
+          const graphEl = document.createElement("div");
+          mermaid.render("mermaid-graph-" + id++, codeEl.textContent).then(({svg, bindFunctions}) => {
+            graphEl.innerHTML = svg;
+            bindFunctions?.(graphEl);
+            preEl.insertAdjacentElement("afterend", graphEl);
+            preEl.remove();
+          });
         }
-
-        window.addEventListener("exdoc:loaded", render);
-      })();
+      });
     </script>
     """
   end