fix: adjust approach with gh-pages

Author: jeffabailey

.github/workflows/mdbook-pr-preview.yml

@@ -64,6 +64,11 @@ jobs:
       - name: Add Cargo bin to PATH
         run: echo "${CARGO_HOME}/bin" >> "$GITHUB_PATH"
 
+      - name: Set site-url for PR preview subpath
+        run: |
+          SITE_URL="/${{ github.event.repository.name }}/${{ env.PREVIEW_DIR }}/"
+          sed -i "s|^site-url = .*|site-url = \"${SITE_URL}\"|" book.toml
+
       - name: Build with mdBook
         run: ${{ env.CARGO_HOME }}/bin/mdbook build
 

.github/workflows/mdbook.yml

@@ -1,7 +1,9 @@
-# Workflow for building and deploying a mdBook site to GitHub Pages
-#
-# To get started with mdBook see: https://rust-lang.github.io/mdBook/index.html
+# Workflow for building and deploying a mdBook site to GitHub Pages.
+# Publishes to the gh-pages branch so PR previews (pr-<number>/) from
+# mdbook-pr-preview.yml are served from the same branch. Set Pages source
+# to "Deploy from a branch" → gh-pages, folder / (root).
 #
+# See: https://rust-lang.github.io/mdBook/index.html
 name: Deploy mdBook site to Pages
 
 on:
@@ -12,21 +14,17 @@ on:
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+# Push to gh-pages so PR previews (mdbook-pr-preview) are served from the same branch.
+# Repository Settings → Pages → Source: Deploy from a branch → gh-pages / (root).
 permissions:
-  contents: read
-  pages: write
-  id-token: write
+  contents: write
 
-# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
-# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
 concurrency:
   group: "pages"
   cancel-in-progress: false
 
 jobs:
-  # Build job
-  build:
+  build-and-deploy:
     runs-on: ubuntu-latest
     env:
       CARGO_HOME: ${{ github.workspace }}/.cargo
@@ -69,31 +67,17 @@ jobs:
           REPO_ROOT: ${{ github.workspace }}
       - name: Add Cargo bin to PATH
         run: echo "${CARGO_HOME}/bin" >> "$GITHUB_PATH"
-      - name: Setup Pages
-        if: ${{ !env.ACT }}
-        id: pages
-        uses: actions/configure-pages@v5
       - name: Build with mdBook
         run: ${{ env.CARGO_HOME }}/bin/mdbook build
-      - name: Upload artifact
+      - name: Deploy to gh-pages (root)
         if: ${{ !env.ACT }}
-        uses: actions/upload-pages-artifact@v3
+        uses: peaceiris/actions-gh-pages@v4
         with:
-          path: ./book
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_branch: gh-pages
+          publish_dir: ./book
+          keep_files: true
       - name: Confirm local act build
         if: ${{ env.ACT }}
         run: |
-          echo "Local act run: mdBook build completed; skipping Pages upload/deploy steps."
-
-  # Deployment job
-  deploy:
-    if: ${{ !github.event.act }}
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    needs: build
-    steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
+          echo "Local act run: mdBook build completed; skipping gh-pages deploy."

book.toml

@@ -20,4 +20,6 @@ giscus.loading = "lazy"
 giscus.crossorigin = "anonymous"
 
 [output.html]
+# Required for correct asset and 404 paths on GitHub Pages (project site and PR preview subpaths).
+site-url = "/managing-innersource-projects/"
 additional-js = ["mermaid.min.js", "mermaid-init.js"]