Use actions for docs deploy

.github/workflows/ci-release.yml

@@ -49,10 +49,3 @@ jobs:
       vendor_deps: ${{ inputs.vendor_deps }}
     permissions:
       contents: write
-
-  docs:
-    if: ${{ !github.event.repository.is_template }}
-    needs: [tests, do_release]  # only build docs when release is successful
-    uses: ./.github/workflows/reusable-build-and-deploy-docs.yml
-    permissions:
-      contents: write

.github/workflows/docs.yml

@@ -0,0 +1,24 @@
+# Docs publish on push, not on release, so the site never lags main.
+name: docs
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - docs/**
+      - mkdocs.yml
+      - src/**
+      - .github/workflows/docs.yml
+      - .github/workflows/reusable-build-and-deploy-docs.yml
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+
+  docs:
+    uses: ./.github/workflows/reusable-build-and-deploy-docs.yml

.github/workflows/reusable-build-and-deploy-docs.yml

@@ -3,12 +3,19 @@ name: reusable / build and deploy docs
 on:
   workflow_dispatch:  # Manual trigger
   workflow_call:
+
 permissions:
-  contents: write
+  contents: read
+  pages: write
+  id-token: write
+
+# Pages allows one deploy at a time; don't cancel one half-done.
+concurrency:
+  group: pages
+  cancel-in-progress: false
 
 jobs:
-  build-and-deploy-docs:
-    # only build docs when publishing a release
+  build:
     runs-on: ubuntu-latest
 
     steps:
@@ -18,14 +25,29 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@v7
         with:
+          enable-cache: true
           python-version: '3.13'
 
-      - uses: actions/cache@v6
-        with:
-          key: ${{ github.ref }}
-          path: .cache
-
       - name: Install dependencies
         run: uv sync --only-group docs
 
-      - run: uv run --no-sync mkdocs gh-deploy --force
+      - name: Build the site
+        run: uv run --no-sync mkdocs build --strict
+
+      - name: Upload the site artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/template-release.yml

@@ -19,15 +19,8 @@ jobs:
     if: ${{ github.event.repository.is_template }}
     uses: ./.github/workflows/reusable-template-tests.yml
 
-  # Before the tag, so a docs failure stops the release.
-  docs:
-    needs: [static-analysis, template-tests]
-    uses: ./.github/workflows/reusable-build-and-deploy-docs.yml
-    permissions:
-      contents: write
-
   do_release:
-    needs: [static-analysis, template-tests, docs]
+    needs: [static-analysis, template-tests]
     runs-on: ubuntu-latest
     concurrency: release
     permissions:

_new_project/AGENTS.md

@@ -30,5 +30,5 @@ This is an Autodesk Maya Python tool, created from
   `gh workflow run ci-release.yml -f version=1.2.3`. It bumps `version` in
   `pyproject.toml`, tags `v<version>`, builds an installable Maya module zip
   (`.mod` + `<name>_drag_and_drop_installer.py`) and attaches it to a GitHub
-  release, and deploys docs to GitHub Pages.
+  release.
 - CI on push/PR runs static analysis (ruff) and the Maya test matrix.

_new_project/CONTRIBUTING.md

@@ -146,7 +146,7 @@ Serve locally:
 * [ci-main.yml](.github/workflows/ci-main.yml): tests (if any) + lint/format checks. Runs on every push/PR to main.
 * [ci-release.yml](.github/workflows/ci-release.yml): the above, then bumps `pyproject.toml`, tags, builds the Maya module zip, creates a GitHub release, and deploys docs. Trigger with `python3 release.py --bump patch` (or `minor`/`major`), or `gh workflow run ci-release.yml -f version=1.2.3`.
 
-Maya versions to test against are set in [reusable-maya-tests.yml](.github/workflows/reusable-maya-tests.yml); that job is skipped if `tests` don't exist. Docs deploy to [https://{{PROJECT_OWNER}}.github.io/{{PROJECT_NAME}}](https://{{PROJECT_OWNER}}.github.io/{{PROJECT_NAME}}); enable once via repo Settings > Pages, source: `gh-pages` branch.
+Maya versions to test against are set in [reusable-maya-tests.yml](.github/workflows/reusable-maya-tests.yml); that job is skipped if `tests` don't exist. Docs deploy on push to main via [docs.yml](.github/workflows/docs.yml), to [https://{{PROJECT_OWNER}}.github.io/{{PROJECT_NAME}}](https://{{PROJECT_OWNER}}.github.io/{{PROJECT_NAME}}); enable once via repo Settings > Pages, source: `GitHub Actions`.
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 

docs/documentation.md

@@ -32,7 +32,7 @@ line per module you want documented.
 
 ## Publishing
 
-Docs deploy automatically when you [cut a release](releasing.md), to
-`https://your-name.github.io/my-cool-tool`.
+Docs deploy on every push to `main` that touches `docs/`, `mkdocs.yml`, or
+`src/`, to `https://your-name.github.io/my-cool-tool`.
 
-Enable it once: repo **Settings** → **Pages** → source **gh-pages** branch.
+Enable it once: repo **Settings** → **Pages** → source **GitHub Actions**.

docs/releasing.md

@@ -7,9 +7,9 @@ A release turns your code into something a user can install.
 On GitHub, go to **Actions** → **Release** → **Run workflow**, then type the
 version number (e.g. `1.2.4`).
 
-GitHub bumps the version, runs the checks, tags the code, builds the zip,
-publishes it on your repo's Releases page, and updates your
-[docs site](documentation.md).
+GitHub bumps the version, runs the checks, tags the code, builds the zip, and
+publishes it on your repo's Releases page. Your
+[docs site](documentation.md) updates separately, on push.
 
 The other three fields only apply if your tool has dependencies: