Fix docs deployment to use the GitHub Pages artifact flow

[Copilot]

The deploy Actions job was failing in GitHub Pages deployment because the workflow was still using mkdocs gh-deploy instead of the current artifact-based Pages flow. This updates the docs workflow to publish the built site through the supported upload-pages-artifact + deploy-pages path with the required permissions.

• Root cause

  • The deploy job invoked mkdocs gh-deploy --force, which does not match the repository's current GitHub Pages deployment model and failed when actions/deploy-pages required OIDC-backed id-token: write.

• Workflow changes

  • Keep docs generation in the build job with mkdocs build --strict
  • Configure Pages only for main branch pushes
  • Upload the generated site/ directory as the Pages artifact
  • Replace the custom gh-pages push step with actions/deploy-pages@v5

• Permissions and environment

  • Set workflow-wide contents: read
  • Grant the deploy job the Pages-specific permissions:
    • pages: write
    • id-token: write
  • Attach the deploy job to the github-pages environment and expose the deployed URL

- name: Upload GitHub Pages artifact
  uses: actions/upload-pages-artifact@v4
  with:
    path: ./site

- name: Deploy to GitHub Pages
  id: deployment
  uses: actions/deploy-pages@v5