diff --git a/.github/workflows/docs-validate.yml b/.github/workflows/docs-validate.yml
index 988c3d3..d8df575 100644
--- a/.github/workflows/docs-validate.yml
+++ b/.github/workflows/docs-validate.yml
@@ -144,15 +144,26 @@ jobs:
                   print(issue)
           PY
 
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Install mdbook-mermaid
+        env:
+          MDBOOK_MERMAID_VERSION: '0.17.0'
+        run: cargo install mdbook-mermaid --locked --version "${MDBOOK_MERMAID_VERSION}"
+
       - name: Install mdBook
         env:
-          MDBOOK_VERSION: '0.4.36'
+          MDBOOK_VERSION: '0.5.2'
         run: |
           curl -fsSL "https://github.com/rust-lang/mdBook/releases/download/v${MDBOOK_VERSION}/mdbook-v${MDBOOK_VERSION}-x86_64-unknown-linux-gnu.tar.gz" -o /tmp/mdbook.tar.gz
           tar -xzf /tmp/mdbook.tar.gz -C /tmp
           sudo install /tmp/mdbook /usr/local/bin/mdbook
           mdbook --version
 
+      - name: Install mdbook-mermaid assets
+        run: mdbook-mermaid install book
+
       - name: Build mdBook
         run: mdbook build book
 
diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
index 4fce8f9..e9634c4 100644
--- a/.github/workflows/pages.yml
+++ b/.github/workflows/pages.yml
@@ -14,6 +14,10 @@ concurrency:
   group: pages
   cancel-in-progress: false
 
+env:
+  MDBOOK_VERSION: "0.5.2"
+  MDBOOK_MERMAID_VERSION: "0.17.0"
+
 jobs:
   build:
     runs-on: ubuntu-latest
@@ -21,10 +25,19 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Install mdbook-mermaid
+        run: cargo install mdbook-mermaid --locked --version "${MDBOOK_MERMAID_VERSION}"
+
+      - name: Install mdbook-mermaid assets
+        run: mdbook-mermaid install book
+
       - name: Setup mdBook
         uses: peaceiris/actions-mdbook@v2
         with:
-          mdbook-version: latest
+          mdbook-version: ${{ env.MDBOOK_VERSION }}
 
       - name: Setup Pages
         uses: actions/configure-pages@v5
diff --git a/.gitignore b/.gitignore
index 9bcd673..884fb30 100644
--- a/.gitignore
+++ b/.gitignore
@@ -167,6 +167,7 @@ docs/generated/
 
 # mdBook build output
 book/book/
+book/mermaid.min.js
 
 # Local git worktrees created for vendored submodules
 3rd-party/*.worktrees/
diff --git a/book/book.toml b/book/book.toml
index 2816f7b..0723bad 100644
--- a/book/book.toml
+++ b/book/book.toml
@@ -3,3 +3,9 @@ authors = ["Agent"]
 language = "zh-cn"
 src = "src"
 title = "Nano Agent Documentation"
+
+[preprocessor.mermaid]
+command = "mdbook-mermaid"
+
+[output.html]
+additional-js = ["mermaid.min.js", "mermaid-init.js"]
diff --git a/book/mermaid-init.js b/book/mermaid-init.js
new file mode 100644
index 0000000..d51920a
--- /dev/null
+++ b/book/mermaid-init.js
@@ -0,0 +1,33 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+(() => {
+    const darkThemes = ['ayu', 'navy', 'coal'];
+    const lightThemes = ['light', 'rust'];
+
+    const classList = document.getElementsByTagName('html')[0].classList;
+
+    const lastThemeWasLight = !darkThemes.some((theme) => classList.contains(theme));
+
+    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();
+            }
+        });
+    }
+})();