From 7475beb3d6b5b195d24fd3c9937be1ec1d14ffd6 Mon Sep 17 00:00:00 2001
From: Matthew Fishman <mfishman@flatironinstitute.org>
Date: Wed, 26 Aug 2026 18:28:01 -0400
Subject: [PATCH] Fix broken mermaid diagrams, drop SparseArraysBase from the
 nav

The ecosystem overview diagram stopped rendering: mermaid 11.17.0 breaks when a global AMD `define` is present, which Documenter's require.js provides (https://github.com/mermaid-js/mermaid/issues/8095). Render the diagrams from a pinned version until that is fixed. Also drops `SparseArraysBase` from the nav for now.
---
 Project.toml               |  2 +-
 docs/make.jl               |  5 +++--
 docs/src/assets/mermaid.js | 22 ++++++++++++++++++++++
 3 files changed, 26 insertions(+), 3 deletions(-)
 create mode 100644 docs/src/assets/mermaid.js

diff --git a/Project.toml b/Project.toml
index 571fed60..02a3529d 100644
--- a/Project.toml
+++ b/Project.toml
@@ -1,6 +1,6 @@
 name = "ITensorDocsNext"
 uuid = "701fd796-f527-45da-9a53-2681c1a90c45"
-version = "0.1.19"
+version = "0.1.20"
 authors = ["ITensor developers <support@itensor.org> and contributors"]
 
 [workspace]
diff --git a/docs/make.jl b/docs/make.jl
index 1f2e3d7c..9f35ec6e 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -25,7 +25,9 @@ Documenter.makedocs(;
     sitename = "ITensor ecosystem docs",
     modules = [ITensorDocsNext],
     warnonly = true,
-    format = Documenter.HTML(; assets = ["assets/favicon.ico", "assets/extras.css"]),
+    format = Documenter.HTML(;
+        assets = ["assets/favicon.ico", "assets/extras.css", "assets/mermaid.js"]
+    ),
     # `upgrade_guide.md` is kept in source but left out of the nav until it gets a
     # rewrite to match the current next-generation API.
     pages = ["index.md", "ecosystem_overview.md"]
@@ -58,7 +60,6 @@ docs = [
                 "ITensorBase",
                 "TensorAlgebra",
                 "GradedArrays",
-                "SparseArraysBase",
             ]
         )
     ),
diff --git a/docs/src/assets/mermaid.js b/docs/src/assets/mermaid.js
new file mode 100644
index 00000000..df37f07c
--- /dev/null
+++ b/docs/src/assets/mermaid.js
@@ -0,0 +1,22 @@
+// Since mermaid 11.17.0 the published ESM bundle contains UMD-wrapped dependencies that
+// register with the global AMD `define` that Documenter's require.js provides instead of
+// exporting themselves, so DocumenterMermaid's unpinned `mermaid@11` import throws before it
+// renders anything (https://github.com/mermaid-js/mermaid/issues/8095). Render the diagrams
+// here from the last version that works; DocumenterMermaid's own pass then skips them, since
+// mermaid ignores diagrams already marked `data-processed`.
+const MERMAID = "https://cdn.jsdelivr.net/npm/mermaid@11.16.1/dist/mermaid.esm.min.mjs";
+
+async function renderMermaidDiagrams() {
+  if (!document.querySelector(".mermaid")) {
+    return;
+  }
+  const { default: mermaid } = await import(MERMAID);
+  mermaid.initialize({ startOnLoad: false, theme: "neutral" });
+  await mermaid.run({ querySelector: ".mermaid" });
+}
+
+if (document.readyState === "loading") {
+  document.addEventListener("DOMContentLoaded", renderMermaidDiagrams);
+} else {
+  renderMermaidDiagrams();
+}