docs: add mdbook-mermaid plugin (#1382)

Author: samlaf

.github/workflows/mdbook.yaml

@@ -16,15 +16,8 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - name: Install latest mdbook
-        run: |
-          tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name')
-          url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz"
-          mkdir mdbook
-          curl -sSL $url | tar -xz --directory=./mdbook
-          echo `pwd`/mdbook >> $GITHUB_PATH
       - name: Build Book
-        run: mdbook build
+        run: make build # also installs deps
         working-directory: docs/spec
       - name: Setup Pages
         uses: actions/configure-pages@v4

Makefile

@@ -32,11 +32,6 @@ protoc: clean
 	./api/builder/protoc-docker.sh
 	./api/builder/generate-docs.sh
 
-# Serves the mdbook docs located in ./docs/spec.
-# Will open a browser window to view the docs.
-mdbook-serve:
-	mdbook serve ./docs/spec --open
-
 # Builds the protobuf files locally (i.e. without docker).
 protoc-local: clean
 	./api/builder/protoc.sh
@@ -95,3 +90,7 @@ docker-release-build:
 
 semver:
 	echo "${SEMVER}"
+
+##### Proxies to other local Makefiles #####
+mdbook-serve:
+	$(MAKE) -C docs/spec serve

docs/spec/Makefile

@@ -0,0 +1,10 @@
+# Serves the mdbook docs located in this directory.
+# Will open a browser window to view the docs.
+serve: install-deps
+	mdbook serve . --open
+
+build: install-deps
+	mdbook build
+
+install-deps:
+	cargo install mdbook [email protected]

docs/spec/README.md

@@ -12,15 +12,19 @@ The protobuf documentation for all of our services is automatically generated by
 
 ## Preview
 
-To preview the book locally, run (from the rootdir):
+To preview the book locally, run:
 
 ```bash
-make mdbook-serve
+make serve
 ```
 
 which will start a local server at `http://localhost:3000` and open your browser to preview the result.
 
 ## Github Pages
 
 The book is automatically built and deployed to Github Pages on every push to the `main` branch.
-This is done by the Github Actions workflow defined in [../../.github/workflows/mdbook.yaml](../../.github/workflows/mdbook.yaml)
+This is done by the Github Actions workflow defined in [../../.github/workflows/mdbook.yaml](../../.github/workflows/mdbook.yaml)
+
+## Mermaid Diagrams
+
+We use mdbook-mermaid to render mermaid diagrams in the book. It is installed along with mdbook when running `make install-deps`. The 2 js files `mermaid-init.js` and `mermaid.min.js` were installed from `mdbook-mermaid install .` which was ran with mdbook-mermaid v0.14.1. These two files are copied into the built book and needed to render the images. Haven't found a way to only generate the images and then update the markdown files to reference the images, so we are stuck with this dependency for now.

docs/spec/book.toml

@@ -6,4 +6,14 @@ src = "src"
 title = "EigenDA Spec"
 
 [output.html]
-mathjax-support = true
+mathjax-support = true
+additional-js = ["mermaid.min.js", "mermaid-init.js"]
+
+[preprocessor]
+
+[preprocessor.mermaid]
+# Preprocesses the mermaid diagrams (see src/integration/proxy.md for an example)
+# and generates the corresponding SVG files.
+# See https://github.com/badboy/mdbook-mermaid for more information.
+# This requires the mdbook-mermaid crate to be installed.
+command = "mdbook-mermaid"

docs/spec/mermaid-init.js

@@ -0,0 +1,37 @@
+// You can modify this file to customize mdbook-mermaid.
+// See https://github.com/badboy/mdbook-mermaid?tab=readme-ov-file#configure-your-mdbook-to-use-mdbook-mermaid
+(() => {
+    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();
+            }
+        });
+    }
+})();