ci: share the docs build action (#3874)

PR validation, nightly link checking, and docs publishing each had their
own copy of the Astro setup and build steps. This moves that sequence
into one local composite action and makes all three jobs run the same
checks, asset fetch, build, and built-site tests.

The workflow path filters now include the shared action, so changes to
it exercise PR validation and the publishing path.

The single `setup-node` pin is v7, superseding the three-copy bump in
#3869.

Tested with the full docs command sequence, Actionlint, YAML validation,
and action metadata validation.

> _This was written by Codex on behalf of @max-sixty_

.github/actions/docs-build/action.yaml

@@ -0,0 +1,40 @@
+name: docs build
+description: Install, build, and verify the Astro documentation site
+
+runs:
+  using: composite
+  steps:
+    - name: Setup Node.js
+      uses: actions/setup-node@v7
+      with:
+        node-version: 24
+        cache: npm
+        cache-dependency-path: docs/package-lock.json
+
+    - name: Install docs dependencies
+      shell: bash
+      run: npm ci
+      working-directory: docs
+
+    - name: Fetch docs assets
+      shell: bash
+      env:
+        GH_TOKEN: ${{ github.token }}
+      run: |
+        gh repo clone max-sixty/worktrunk-assets /tmp/worktrunk-assets -- --depth 1
+        cp -r /tmp/worktrunk-assets/assets docs/public/
+
+    - name: Check docs source
+      shell: bash
+      run: npm run check && npm test
+      working-directory: docs
+
+    - name: Build docs
+      shell: bash
+      run: npm run build
+      working-directory: docs
+
+    - name: Test built site
+      shell: bash
+      run: npm run test:site
+      working-directory: docs

.github/workflows/ci.yaml

@@ -191,6 +191,10 @@ jobs:
           docs:
             - 'docs/**'
             - 'src/cli/mod.rs'
+            - '.github/actions/docs-build/**'
+            - '.github/workflows/ci.yaml'
+            - '.github/workflows/nightly.yaml'
+            - '.github/workflows/publish-docs.yaml'
 
   msrv:
     runs-on: ubuntu-24.04
@@ -225,24 +229,5 @@ jobs:
     - name: 📂 Checkout code
       uses: actions/checkout@v7
 
-    - name: Setup Node.js
-      uses: actions/setup-node@v6
-      with:
-        node-version: 24
-        cache: npm
-        cache-dependency-path: docs/package-lock.json
-
-    - name: Install docs dependencies
-      run: npm ci
-      working-directory: docs
-
-    - name: Fetch assets
-      env:
-        GH_TOKEN: ${{ github.token }}
-      run: |
-        gh repo clone max-sixty/worktrunk-assets /tmp/worktrunk-assets -- --depth 1
-        cp -r /tmp/worktrunk-assets/assets docs/public/
-
     - name: 🕷️ Check and build docs
-      run: npm run check && npm test && npm run build && npm run test:site
-      working-directory: docs
+      uses: ./.github/actions/docs-build

.github/workflows/nightly.yaml

@@ -357,13 +357,11 @@ jobs:
       run: cargo test --test integration crate_io_archive_builds_and_versions_without_git -- --ignored
 
   link-check:
-    # The pre-commit `lychee-system` hook (manual stage) over every tracked
-    # .md/.txt file, resolving local routes against the built Astro site. It
-    # lives here, not in PR CI: link health depends on the outside world
-    # (429s, bot-blocking, transient outages), so it was the flakiest PR
-    # check — and link rot isn't PR-correlated anyway; links break when
-    # external sites change, not when code does. A failure opens the
-    # nightly-failure issue instead of reddening an unrelated PR.
+    # The shared docs action verifies and builds the site before the pre-commit
+    # `lychee-system` hook checks every tracked .md/.txt file. Lychee remains in
+    # the nightly workflow rather than required PR CI because external link
+    # health depends on 429s, bot-blocking, and transient outages. A scheduled
+    # docs or link failure opens the nightly-failure issue.
     needs: gate
     if: needs.gate.outputs.run == 'true'
     runs-on: ubuntu-24.04
@@ -374,27 +372,8 @@ jobs:
     - name: 📂 Checkout code
       uses: actions/checkout@v7
 
-    - name: Setup Node.js
-      uses: actions/setup-node@v6
-      with:
-        node-version: 24
-        cache: npm
-        cache-dependency-path: docs/package-lock.json
-
-    - name: Install docs dependencies
-      run: npm ci
-      working-directory: docs
-
-    - name: Fetch docs assets
-      env:
-        GH_TOKEN: ${{ github.token }}
-      run: |
-        gh repo clone max-sixty/worktrunk-assets /tmp/worktrunk-assets -- --depth 1
-        cp -r /tmp/worktrunk-assets/assets docs/public/
-
-    - name: Build docs
-      run: npm run build
-      working-directory: docs
+    - name: 🕷️ Check and build docs
+      uses: ./.github/actions/docs-build
 
     - name: Install lychee
       uses: baptiste0928/cargo-install@v3

.github/workflows/publish-docs.yaml

@@ -8,6 +8,8 @@ on:
     paths:
       - 'docs/**'
       - 'src/cli/mod.rs'
+      - '.github/actions/docs-build/**'
+      - '.github/workflows/publish-docs.yaml'
   workflow_dispatch:
 
 concurrency:
@@ -22,27 +24,8 @@ jobs:
       - name: 📂 Checkout code
         uses: actions/checkout@v7
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v6
-        with:
-          node-version: 24
-          cache: npm
-          cache-dependency-path: docs/package-lock.json
-
-      - name: Install docs dependencies
-        run: npm ci
-        working-directory: docs
-
-      - name: Fetch assets
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          gh repo clone max-sixty/worktrunk-assets /tmp/worktrunk-assets -- --depth 1
-          cp -r /tmp/worktrunk-assets/assets docs/public/
-
-      - name: 🕷️ Build docs
-        run: npm run check && npm test && npm run build && npm run test:site
-        working-directory: docs
+      - name: 🕷️ Check and build docs
+        uses: ./.github/actions/docs-build
 
       - uses: actions/upload-pages-artifact@v5
         with: