fix: switch to GitHub Pages Actions deployment

- Use official GitHub Pages Actions instead of branch deployment
- This completely bypasses Jekyll processing
- Provides proper artifact upload and deployment process
- Requires changing repository settings to 'GitHub Actions' source

Author: dataGriff

.github/workflows/deploy-docs.yml

@@ -1,50 +1,58 @@
-name: build-mkdocs-gh-pages-branch
+name: Deploy MkDocs to GitHub Pages
 
 on:
   push:
     branches:
       - main
 
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
-  contents: write
+  contents: read
+  pages: write
+  id-token: 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:
-  deploy:
+  build:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
-          fetch-depth: 0  # Fetch all history for all branches and tags
+          fetch-depth: 0
 
-      - uses: actions/setup-python@v5
+      - name: Setup Python
+        uses: actions/setup-python@v5
         with:
           python-version: '3.x'
 
       - name: Install dependencies
-        run:  |     
+        run: |
           pip install mkdocs-material mkdocs-git-revision-date-localized-plugin pymdown-extensions mkdocs-mermaid2-plugin
 
-      - name: Configure git
-        run: |
-          git config --global user.name "github-actions[bot]"
-          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+      - name: Build MkDocs site
+        run: mkdocs build --clean
 
-      - name: Build and Deploy
-        run: |
-          # Build the site
-          mkdocs build
-          
-          # Add .nojekyll to disable Jekyll processing
-          touch site/.nojekyll
-          
-          # Deploy to gh-pages branch manually to ensure .nojekyll is included
-          cd site
-          git init
-          git add -A
-          git commit -m "Deploy MkDocs site"
-          git branch -M gh-pages
-          git remote add origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git
-          git push -f origin gh-pages
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './site'
+
+  deploy:
+    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