chore: rework docs deploy workflow

Author: Julusian

.github/workflows/deploy-docs.yml

@@ -0,0 +1,84 @@
+name: Deploy Docs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+    # Review gh actions docs if you want to further define triggers, paths, etc
+    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
+
+# Ensure we avoid any race conditions with rapid pushes to main
+concurrency:
+  group: "Deploy to GitHub Pages"
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build Docusaurus
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - name: Use Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: ".node-version"
+      - name: restore node_modules
+        uses: actions/cache@v4
+        with:
+          path: |
+            packages/node_modules
+          key: ${{ runner.os }}-${{ hashFiles('packages/yarn.lock') }}
+      - name: Prepare Environment
+        run: |
+          corepack enable
+
+          cd packages
+          yarn config set cacheFolder /home/runner/publish-docs-cache
+          yarn install
+          yarn build:all
+        env:
+          CI: true
+      - name: Run docusaurus
+        run: |
+          cd packages/documentation
+          yarn docs:build
+        env:
+          CI: true
+      - name: Run typedoc
+        run: |
+          cd packages
+          yarn docs:typedoc
+          cp docs documentation/build/typedoc -R
+        env:
+          CI: true
+
+      - name: Upload Build Artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: packages/documentation/build
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write # to deploy to Pages
+      id-token: write # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    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

.github/workflows/node.yaml

@@ -625,15 +625,12 @@ jobs:
         env:
           CI: true
 
-  publish-docs:
-    name: Publish Docs
+  build-docs:
+    name: Build Docs
     runs-on: ubuntu-latest
-    continue-on-error: true
     timeout-minutes: 15
 
-    permissions:
-      contents: write
-
+    # This is just to ensure the docs build, another job performs the build & publish
     steps:
       - uses: actions/checkout@v6
         with:
@@ -671,13 +668,6 @@ jobs:
           cp docs documentation/build/typedoc -R
         env:
           CI: true
-      - name: Publish
-        if: github.ref == 'refs/heads/main' # always publish for just the main branch
-        uses: peaceiris/actions-gh-pages@v4
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./packages/documentation/build
-          force_orphan: true
 
   check-for-multiple-library-versions:
     name: Check for multiple library versions