chore(docs): deploy docs on release publish

.github/workflows/deploy-docs.yml

@@ -0,0 +1,25 @@
+name: Deploy docs
+
+on:
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  deploy-docs:
+    name: "Deploy docs (manual)"
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy docs site
+        run: |
+          curl --fail --silent --show-error \
+            --request POST \
+            --data '{"forceDocsDeploy":true,"source":"workflow_dispatch"}' \
+            "$NETLIFY_DOCS_BUILD_HOOK_URL?trigger_branch=main&trigger_title=Manual+docs+deploy"
+        env:
+          NETLIFY_DOCS_BUILD_HOOK_URL: ${{ secrets.NETLIFY_DOCS_BUILD_HOOK_URL }}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true

.github/workflows/main.yml

@@ -55,7 +55,7 @@ jobs:
 
   release:
     name: "Release (main)"
-    if: github.ref == 'refs/heads/main'
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     needs: [build-and-test]
     runs-on: ubuntu-latest
     env:
@@ -98,6 +98,14 @@ jobs:
             This is necessary because the PR is updated by github-actions[bot].
             This is a technical user which does not trigger actions workflows on push events.
             See this GH issue for more details: https://github.com/changesets/action/issues/187
+      - name: Deploy docs site
+        if: steps.changesets.outputs.published == 'true'
+        run: |
+          curl --fail --silent --show-error \
+            --request POST \
+            "$NETLIFY_DOCS_BUILD_HOOK_URL?trigger_branch=main&trigger_title=Release+docs+deploy"
+        env:
+          NETLIFY_DOCS_BUILD_HOOK_URL: ${{ secrets.NETLIFY_DOCS_BUILD_HOOK_URL }}
 
 # cancel the jobs if another workflow is kicked off for the same branch
 concurrency:

README.md

@@ -187,6 +187,8 @@ _Despite using changesets to communicate the intent of creating releases in a mo
 
 Docs are deployed directly from the current release flow; we no longer merge into a `production` branch to publish stackoverflow.design. Normal contribution PRs target `main`.
 
+When `changesets/action` publishes a new version from `main`, the release workflow triggers the Netlify build hook stored in `NETLIFY_DOCS_BUILD_HOOK_URL`. The docs site also has a Netlify ignore rule so ordinary `main` commits are skipped unless the deployed commit changes one of the released package version files. To deploy the latest `main` docs without publishing packages, manually run the Deploy docs workflow from the `main` branch.
+
 ## License
 Code and documentation copyright 2017-2026 Stack Exchange, Inc and released under the [MIT License](/LICENSE.MD).
 

packages/stacks-docs/netlify-ignore.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Netlify ignores the build when this script exits 0. Exit 1 to build.
+repo_root="$(git rev-parse --show-toplevel)"
+cd "$repo_root"
+
+head_ref="${COMMIT_REF:-HEAD}"
+base_ref="$head_ref^"
+
+if [[ "${INCOMING_HOOK_BODY:-}" == *"forceDocsDeploy"* ]]; then
+    echo "Building docs deploy: manual deploy requested."
+    exit 1
+fi
+
+if [[ "${CONTEXT:-}" == "deploy-preview" || "${CONTEXT:-}" == "branch-deploy" ]]; then
+    echo "Building docs deploy: ${CONTEXT} context."
+    exit 1
+fi
+
+if ! git rev-parse --verify "$base_ref" >/dev/null 2>&1; then
+    echo "Building docs deploy: no previous commit is available."
+    exit 1
+fi
+
+version_files=(
+    "packages/stacks-classic/package.json"
+    "packages/stacks-svelte/package.json"
+    "packages/stacks-utils/package.json"
+)
+
+if git diff --quiet "$base_ref" "$head_ref" -- "${version_files[@]}"; then
+    echo "Skipping docs deploy: no package versions changed."
+    exit 0
+fi
+
+echo "Building docs deploy: package versions changed."
+exit 1

packages/stacks-docs/netlify.toml

@@ -0,0 +1,3 @@
+[build]
+  # Netlify treats exit code 0 as "ignore this build" and non-zero as "build".
+  ignore = "bash netlify-ignore.sh"