chore(docs): deploy docs on release publish

.github/workflows/deploy-docs.yml

@@ -0,0 +1,24 @@
+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 --retry 3 --retry-all-errors \
+            --request POST \
+            "$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

@@ -46,6 +46,10 @@ jobs:
           command: npm run test -w packages/stacks-utils
           needs_lfs: false
           needs_playwright: false
+        - command_description: Unit Tests (stacks-docs)
+          command: npm run test -w packages/stacks-docs
+          needs_lfs: false
+          needs_playwright: false
         - command_description: Unit Tests (stacks-email)
           command: npm run test -w packages/stacks-email
           needs_lfs: false
@@ -59,7 +63,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:
@@ -102,8 +106,16 @@ 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 --retry 3 --retry-all-errors \
+            --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:
   group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

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's Netlify ignore rule skips automatic production builds from ordinary `main` commits while preserving deploy previews and branch deploys. 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,11 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Netlify ignores the build when this script exits 0. Exit 1 to build.
+if [[ "${CONTEXT:-}" == "deploy-preview" || "${CONTEXT:-}" == "branch-deploy" ]]; then
+    echo "Building docs deploy: ${CONTEXT} context."
+    exit 1
+fi
+
+echo "Skipping docs deploy: production deploys require a build hook."
+exit 0

packages/stacks-docs/netlify-ignore.test.js

@@ -0,0 +1,47 @@
+import assert from "node:assert/strict";
+import { execSync, spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import test from "node:test";
+
+const packageDirectory = dirname(fileURLToPath(import.meta.url));
+const repositoryRoot = execSync("git rev-parse --show-toplevel", {
+    cwd: packageDirectory,
+    encoding: "utf8",
+}).trim();
+const netlifyConfig = readFileSync(
+    resolve(packageDirectory, "netlify.toml"),
+    "utf8"
+);
+const ignoreCommand = netlifyConfig.match(/ignore = "([^"]+)"/)?.[1];
+
+assert.ok(ignoreCommand, "netlify.toml must define an ignore command");
+
+function runIgnoreCommand(context) {
+    return spawnSync(ignoreCommand, {
+        cwd: repositoryRoot,
+        env: {
+            ...process.env,
+            CONTEXT: context,
+        },
+        shell: true,
+        encoding: "utf8",
+    });
+}
+
+test("skips automatic production builds", () => {
+    const result = runIgnoreCommand("production");
+
+    assert.equal(result.status, 0, result.stderr);
+    assert.match(result.stdout, /production deploys require a build hook/);
+});
+
+for (const context of ["deploy-preview", "branch-deploy"]) {
+    test(`builds the ${context} context`, () => {
+        const result = runIgnoreCommand(context);
+
+        assert.equal(result.status, 1, result.stderr);
+        assert.match(result.stdout, new RegExp(`${context} context`));
+    });
+}

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 ./packages/stacks-docs/netlify-ignore.sh"

packages/stacks-docs/package.json

@@ -12,7 +12,7 @@
         "check": "npm run build -w @stackoverflow/stacks-svelte && npm run build:package -w @stackoverflow/stacks-email && svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
         "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
         "lint": "npm run check && eslint .",
-        "test": "vitest run src/lib",
+        "test": "vitest run src/lib && node --test netlify-ignore.test.js",
         "format": "prettier --write .",
         "init-private-content": "if [ -d src/docs/private/.git ]; then git -C src/docs/private pull --ff-only; elif [ -s ~/.ssh/id_rsa ]; then GIT_SSH_COMMAND=\"ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no\" git clone --depth 1 git@github.com:StackEng/StacksDocsPrivate.git src/docs/private; else echo 'Skipping private docs; no SSH key found'; fi"
     },