OpenPRoT · moidx · Sep 29, 2025 · Sep 28, 2025 · Sep 28, 2025 · Sep 28, 2025
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -10,29 +10,22 @@ on:
 
 permissions:
   contents: read
-  pages: write
-  id-token: write
 
 env:
   CARGO_TERM_COLOR: always
 
 jobs:
   docs:
     name: Documentation
-    # Only run this job on the main branch
-    if: github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
     steps:
     - uses: actions/checkout@v5
-    
+
     - name: Install Rust toolchain
       uses: dtolnay/rust-toolchain@stable
       with:
         components: rust-docs
-    
+
     - name: Cache cargo registry
       uses: actions/cache@v4
       with:
@@ -41,40 +34,12 @@ jobs:
           ~/.cargo/git
           target
         key: ${{ runner.os }}-docs-cargo-${{ hashFiles('**/Cargo.lock') }}
-    
+
     - name: Build documentation
       run: cargo doc --all-features --no-deps --workspace
-
-    - name: Create index.html redirect for GitHub Pages
-      run: |
-        cat > target/doc/index.html << 'EOF'
-        <!DOCTYPE html>
-        <html>
-        <head>
-            <meta http-equiv="refresh" content="0; url=openprot/">
-            <title>OpenProt Documentation</title>
-        </head>
-        <body>
-            <p>Redirecting to <a href="openprot/">OpenProt Documentation</a>...</p>
-        </body>
-        </html>
-        EOF
-
+
     - name: Check for broken links in docs
       run: |
         cargo install cargo-deadlinks
         cargo deadlinks --check-http
       continue-on-error: true
-
-    - name: Setup Pages
-      uses: actions/configure-pages@v5
-
-    # Upload the 'github-pages' artifact
-    - name: Upload artifact
-      uses: actions/upload-pages-artifact@v4
-      with:
-        path: ./target/doc
-
-    - name: Deploy to GitHub Pages
-      id: deployment
-      uses: actions/deploy-pages@v4
diff --git a/.github/workflows/github_pages.yml b/.github/workflows/github_pages.yml
@@ -0,0 +1,61 @@
+# Licensed under the Apache-2.0 license
+
+name: GitHub Pages
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build-and-deploy:
+    name: Build and Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v5
+
+    - name: Install Rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+      with:
+        components: rust-docs
+
+    - name: Cache cargo registry
+      uses: actions/cache@v4
+      with:
+        path: |
+          ~/.cargo/registry
+          ~/.cargo/git
+          target
+        key: ${{ runner.os }}-github-pages-cargo-${{ hashFiles('**/Cargo.lock') }}
+
+    - name: Install mdbook and mdbook-mermaid
+      run: |
+        cargo install mdbook --locked
+        cargo install mdbook-mermaid --locked
+
+    - name: Build mdbook documentation
+      run: cargo xtask docs
+
+    - name: Setup Pages
+      uses: actions/configure-pages@v5
+
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v4
+      with:
+        path: ./target/book
+
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4
diff --git a/docs/book.toml b/docs/book.toml
@@ -9,3 +9,9 @@ title = "OpenProt Documentation"
 command = "mdbook-mermaid"
 
 [output.html]
+additional-js = ["src/third_party/mermaid.min.js", "src/third_party/mermaid-init.js"]
+default-theme = "light"
+
+[output.html.fold]
+enable = true
+level = 1
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -4,10 +4,26 @@
 
 # User Guide
 
-- [Getting Started](./getting-started.md)
-- [Usage](./usage.md)
+* [Getting Started](./getting-started.md)
+* [Usage](./usage.md)
+
+# Specification
+
+* [Introduction](./specification/README.md)
+* [Firmware Resiliency](./specification/firmware_resiliency.md)
+* [Middleware](./specification/middleware/README.md)
+  * [MCTP](./specification/middleware/mctp.md)
+  * [SPDM](./specification/middleware/spdm.md)
+  * [PLDM](./specification/middleware/pldm.md)
+* [Services](./specification/services/README.md)
+* [Device Abstraction](./specification/device_abstraction/README.md)
+* [Terminology](./specification/terminology.md)
 
 # Developer Guide
 
-- [Architecture](./architecture.md)
-- [Contributing](./contributing.md)
+* [Architecture](./architecture.md)
+* [Contributing](./contributing.md)
+* [Design](./design/README.md)
+  * [Digest Driver for Hubris](./design/driver-hubris-hash.md)
+  * [Rust Traits to IDL Guide](./design/rust-trait-to-idl-conversion.md)
+
diff --git a/docs/src/design/README.md b/docs/src/design/README.md
@@ -0,0 +1 @@
+# Design