From b03d4b348e1f74f09fb3ec3a535aecfef09da8ff Mon Sep 17 00:00:00 2001
From: Bart Louwers <bart@emeel.net>
Date: Sat, 19 Apr 2025 13:01:55 +0200
Subject: [PATCH] Allow including Mermaid diagrams in Developer Docs (#3412)

---
 .github/workflows/gh-pages-mdbook.yml         | 11 ++++--
 docs/mdbook/README.md                         |  4 +-
 docs/mdbook/book.toml                         |  4 ++
 .../src/design/ten-thousand-foot-view.md      | 32 +++++++++++++++-
 docs/mdbook/theme/head.hbs                    | 37 +++++++++++++++++++
 5 files changed, 82 insertions(+), 6 deletions(-)
 create mode 100644 docs/mdbook/theme/head.hbs

diff --git a/.github/workflows/gh-pages-mdbook.yml b/.github/workflows/gh-pages-mdbook.yml
index 3e6ea8c4e..9e577cfd3 100644
--- a/.github/workflows/gh-pages-mdbook.yml
+++ b/.github/workflows/gh-pages-mdbook.yml
@@ -1,7 +1,10 @@
-name: Build & Deploy mdBook documentation
+name: gh-pages-mdbook
 
 on:
   workflow_dispatch:
+  pull_request:
+    paths:
+      - 'docs/mdbook/**'
   push:
     branches:
       - main
@@ -20,8 +23,8 @@ jobs:
       - name: Install Dependencies
         shell: bash
         run: sudo apt-get install -y libwayland-dev libxkbcommon-dev # Required for winit
-      - name: Install mdbook-alerts
-        run: cargo install mdbook-alerts
+      - name: Install mdbook-alerts, mdbook-mermaid
+        run: cargo install mdbook-alerts mdbook-mermaid
       - name: Build
         working-directory: docs/mdbook
         shell: bash
@@ -33,6 +36,7 @@ jobs:
 
   gh-pages-mdbook-deploy:
     needs: gh-pages-mdbook-build
+    if: github.event_name != 'pull_request'
     name: Deploy
     runs-on: ubuntu-latest
     steps:
@@ -42,6 +46,7 @@ jobs:
         with:
           name: book
           path: artifacts/book
+
       - name: Deploy
         uses: JamesIves/github-pages-deploy-action@v4.7.3
         with:
diff --git a/docs/mdbook/README.md b/docs/mdbook/README.md
index 9e4a48313..519d6905b 100644
--- a/docs/mdbook/README.md
+++ b/docs/mdbook/README.md
@@ -2,10 +2,10 @@
 
 ## Build Locally
 
-Get the `mdbook` utility as well as [`mdbook-alerts`](https://github.com/lambdalisue/rs-mdbook-alerts), see https://rust-lang.github.io/mdBook/guide/installation.html
+Get the `mdbook` utility as well as [`mdbook-alerts`](https://github.com/lambdalisue/rs-mdbook-alerts) and [`mdbook-mermaid`](https://github.com/badboy/mdbook-mermaid), see https://rust-lang.github.io/mdBook/guide/installation.html
 
 ```
-cargo install mdbook mdbook-alerts
+cargo install mdbook mdbook-alerts mdbook-mermaid
 ```
 
 Run
diff --git a/docs/mdbook/book.toml b/docs/mdbook/book.toml
index f68116e87..c8af3b2e8 100644
--- a/docs/mdbook/book.toml
+++ b/docs/mdbook/book.toml
@@ -7,5 +7,9 @@ title = "MapLibre Native Developer Documentation"
 
 [output.html]
 additional-css = ["diff.css"]
+additional-js = []
 
 [preprocessor.alerts]
+
+[preprocessor.mermaid]
+command = "mdbook-mermaid"
diff --git a/docs/mdbook/src/design/ten-thousand-foot-view.md b/docs/mdbook/src/design/ten-thousand-foot-view.md
index 5cbdd9f5d..c3753c381 100644
--- a/docs/mdbook/src/design/ten-thousand-foot-view.md
+++ b/docs/mdbook/src/design/ten-thousand-foot-view.md
@@ -1,6 +1,36 @@
 # Ten Thousand Foot View
 
-![](media/ten-thousand-foot-view-diagram.png)
+```mermaid
+graph TD
+    subgraph Platform
+        MV[Map View]
+        MR[Map Renderer]
+    end
+
+    subgraph "MapLibre Native Core"
+        M[Map]
+        S[Style]
+        L[Layers]
+        I[Images]
+        Glyphs
+        R[Renderer]
+        TW[TileWorker]
+    end
+
+    %% Platform Interactions
+    MV -- initializes --> MR
+    MV -- Initializes --> M
+
+    %% Core Interactions
+    MR -- runs the rendering loop --> R
+    R -- Renders Map --> M
+    L -- Fetches --> S
+    L -- Fetches --> I
+    R -- Sends messages to generate tiles --> TW
+    TW -- Prepares layers to be rendered --> L
+    L -- Fetches --> Glyphs
+```
+
 *Figure 1: MapLibre Native Components – Ten Thousand Foot view*
 
 From ten thousand foot, MapLibre Native is composed of *Map View* and a
diff --git a/docs/mdbook/theme/head.hbs b/docs/mdbook/theme/head.hbs
new file mode 100644
index 000000000..76b4a0032
--- /dev/null
+++ b/docs/mdbook/theme/head.hbs
@@ -0,0 +1,37 @@
+<script type="module">
+import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11.6.0/+esm';
+
+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();
+        }
+    });
+}
+</script>