Split User Guide publishing into build and deploy jobs (#56)

Author: scordio

.github/workflows/main.yml

@@ -85,13 +85,10 @@ jobs:
       - name: Generate Javadoc
         run: ./mvnw $MAVEN_ARGS compile javadoc:javadoc
 
-  publish-user-guide:
+  build-user-guide:
 
-    name: Publish User Guide
-    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    name: Build User Guide
     runs-on: ubuntu-latest
-    permissions:
-      contents: write
 
     steps:
       - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
@@ -102,8 +99,30 @@ jobs:
           cache: 'pip'
       - name: Install Material for MkDocs
         run: pip install mkdocs-material
-      - name: Publish to GitHub Pages
+      - name: Build User Guide
         run: |
           git config user.name '${{ github.actor }}'
           git config user.email '${{ github.actor }}@users.noreply.github.com'
-          mkdocs gh-deploy --force
+          mkdocs build --strict
+      - name: Upload User Guide Artifact
+        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
+        with:
+          path: target/mkdocs
+
+  deploy-user-guide:
+
+    name: Deploy User Guide
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    needs: build-user-guide
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5