Fix Mermaid sequence diagram rendering in documentation

.github/workflows/docs.yml

@@ -40,6 +40,11 @@ jobs:
           curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.40/mdbook-v0.4.40-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
           echo "$GITHUB_WORKSPACE/bin" >> $GITHUB_PATH
 
+      - name: Install mdbook-mermaid
+        run: |
+          curl -sSL https://github.com/badboy/mdbook-mermaid/releases/download/v0.14.0/mdbook-mermaid-v0.14.0-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
+          echo "$GITHUB_WORKSPACE/bin" >> $GITHUB_PATH
+
       - name: Setup Pages
         id: pages
         uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0

.gitignore

@@ -7,3 +7,8 @@
 
 # mdbook output
 /docs/book
+mdbook
+mdbook-mermaid
+
+# typos binary
+typos

CHANGELOG.md

@@ -17,6 +17,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 - `wassette secret set` now returns a clear error message when the component ID is not found, preventing silent failures and providing better user feedback
 - Fixed invalid `workflows` permission in dependabot-automerge workflow file that caused GitHub Actions validation error
+- Fixed Mermaid sequence diagram rendering in documentation by adding mdbook-mermaid preprocessor configuration
 
 ## [v0.3.0] - 2025-10-03
 

_typos.toml

@@ -2,6 +2,8 @@
 extend-exclude = [
     "**/*.wit",
     "**/*.wit.go",
+    "**/mermaid.min.js",
+    "**/mermaid-init.js",
 ]
 
 [default.extend-words]

docs/book.toml

@@ -9,8 +9,8 @@ title = "Wassette Documentation"
 build-dir = "book"
 
 [output.html]
+additional-js = ["mermaid.min.js", "mermaid-init.js", "theme/version-picker.js"]
 additional-css = ["theme/version-picker.css"]
-additional-js = ["theme/version-picker.js"]
 smart-punctuation = true
 git-repository-url = "https://github.com/microsoft/wassette"
 edit-url-template = "https://github.com/microsoft/wassette/edit/main/docs/{path}"
@@ -25,3 +25,8 @@ boost-hierarchy = 1
 boost-paragraph = 1
 expand = true
 heading-split-level = 3
+
+[preprocessor]
+
+[preprocessor.mermaid]
+command = "mdbook-mermaid"

docs/mermaid-init.js

@@ -0,0 +1,35 @@
+(() => {
+    const darkThemes = ['ayu', 'navy', 'coal'];
+    const lightThemes = ['light', 'rust'];
+
+    const classList = document.getElementsByTagName('html')[0].classList;
+
+    let lastThemeWasLight = true;
+    for (const cssClass of classList) {
+        if (darkThemes.includes(cssClass)) {
+            lastThemeWasLight = false;
+            break;
+        }
+    }
+
+    const theme = lastThemeWasLight ? 'default' : 'dark';
+    mermaid.initialize({ startOnLoad: true, theme });
+
+    // Simplest way to make mermaid re-render the diagrams in the new theme is via refreshing the page
+
+    for (const darkTheme of darkThemes) {
+        document.getElementById(darkTheme).addEventListener('click', () => {
+            if (lastThemeWasLight) {
+                window.location.reload();
+            }
+        });
+    }
+
+    for (const lightTheme of lightThemes) {
+        document.getElementById(lightTheme).addEventListener('click', () => {
+            if (!lastThemeWasLight) {
+                window.location.reload();
+            }
+        });
+    }
+})();