Refactor GitHub Pages workflow to separate build and deploy

Split the workflow into distinct 'build' and 'deploy' jobs. The build job handles checkout, install, and documentation build steps, while the deploy job depends on build and manages deployment to GitHub Pages. This improves workflow clarity and separation of concerns.

.github/workflows/gh-pages.yml

@@ -19,11 +19,7 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
-  # Single deploy job since we're just deploying
-  deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
+  build:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -38,8 +34,6 @@ jobs:
       - name: Install dependencies
         run: npm install --no-package-lock
       - name: Build docs
-        env:
-          BASE_URL: /${{ github.event.repository.name }}/
         run: npm run docs:build
       - name: Setup Pages
         uses: actions/configure-pages@v5
@@ -47,6 +41,20 @@ jobs:
         uses: actions/upload-pages-artifact@v3
         with:
           path: './.vitepress/dist'
+  # Single deploy job since we're just deploying
+  deploy:
+    needs: build
+
+    permissions:
+      pages: write      
+      id-token: write 
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4