0.12.0-17 Misc fixes

.github/workflows/docs.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - main
+      - dev
     paths:
       - 'docs/**'
       - 'mkdocs.yml'
@@ -45,8 +46,40 @@ jobs:
       - name: Install MkDocs and dependencies
         run: pip install -r requirements-docs.txt
 
-      - name: Build MkDocs site
-        run: mkdocs build --strict --verbose
+      - name: Build MkDocs site (main -> /, dev -> /dev)
+        env:
+          REF_NAME: ${{ github.ref_name }}
+          SHA: ${{ github.sha }}
+        run: |
+          set -euo pipefail
+
+          # Ensure both refs are available locally.
+          git fetch origin main dev
+
+          MAIN_REF="origin/main"
+          DEV_REF="origin/dev"
+          if [ "${REF_NAME}" = "main" ]; then
+            MAIN_REF="${SHA}"
+          fi
+          if [ "${REF_NAME}" = "dev" ]; then
+            DEV_REF="${SHA}"
+          fi
+
+          # Build each branch in its own worktree and merge into one Pages artifact:
+          # - main docs at site/
+          # - dev docs at site/dev/
+          rm -rf .worktrees site
+          mkdir -p .worktrees
+          git worktree add --detach .worktrees/main "${MAIN_REF}"
+          git worktree add --detach .worktrees/dev "${DEV_REF}"
+
+          mkdocs build --strict --verbose \
+            --config-file .worktrees/main/mkdocs.yml \
+            --site-dir site
+
+          mkdocs build --strict --verbose \
+            --config-file .worktrees/dev/mkdocs.yml \
+            --site-dir site/dev
 
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v3