chore: extract docs deploy into standalone workflow

.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: Docs
+
+on:
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: Git ref to build and deploy (branch, tag, or SHA)
+        type: string
+        default: main
+  workflow_call:
+    inputs:
+      ref:
+        description: Git ref to build and deploy (branch, tag, or SHA)
+        type: string
+        default: main
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          ref: ${{ inputs.ref }}
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.14"
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --frozen --all-groups
+
+      - name: Build documentation
+        run: uv run zensical build --clean
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+      - id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/release.yml

@@ -11,7 +11,6 @@ on:
 permissions:
   contents: write
   id-token: write
-  pages: write
 
 concurrency:
   group: release
@@ -191,30 +190,10 @@ jobs:
 
   docs:
     needs: release
-    runs-on: ubuntu-latest
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    steps:
-      - uses: actions/checkout@v5
-        with:
-          ref: main
-          fetch-depth: 0
-
-      - uses: astral-sh/setup-uv@v6
-        with:
-          python-version: "3.14"
-          enable-cache: true
-
-      - name: Install dependencies
-        run: uv sync --frozen --all-groups
-
-      - name: Build documentation
-        run: uv run zensical build --clean
-
-      - uses: actions/upload-pages-artifact@v3
-        with:
-          path: site
-
-      - id: deployment
-        uses: actions/deploy-pages@v4
+    uses: ./.github/workflows/docs.yml
+    with:
+      ref: main
+    permissions:
+      contents: read
+      pages: write
+      id-token: write

docs/pages/contributing.md

@@ -34,6 +34,7 @@ The public site is built by [Zensical](https://zensical.org) from
 
 ```bash
 just docs-serve     # live-reloading local preview
+just docs-deploy    # publish to GitHub Pages (Actions workflow on main)
 just docs-cli       # regenerate reference/cli/ from the cyclopts app
 just docs-shots     # regenerate TUI screenshots (SVG) from demo data
 just docs-gifs      # re-record GIF walkthroughs (requires `brew install vhs`)

justfile

@@ -60,6 +60,10 @@ docs-gifs:
 docs-serve:
     uv run zensical serve
 
+# Deploy the docs site to GitHub Pages (workflow_dispatch on main).
+docs-deploy:
+    gh workflow run docs.yml --ref main
+
 # Build wheel/sdist and verify the ttd CLI from the artifact (pre-release smoke).
 release-smoke:
     rm -rf dist/