Allow including Mermaid diagrams in Developer Docs (#3412)

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

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"

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

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>