docs bot: format generated docs PRs before committing

.github/workflows/update-docs.yml

@@ -56,6 +56,13 @@ jobs:
           token: ${{ steps.app-token.outputs.token }}
           path: _docs
 
+      - name: Record docs baseline
+        id: docs-base
+        working-directory: _docs
+        # The commit the docs branch builds on, used to scope formatting to the
+        # pages this run touches.
+        run: echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+
       - name: Resolve PR number
         id: pr
         run: |
@@ -184,6 +191,49 @@ jobs:
             --max-turns 30
             --allowedTools "Read,Write,Edit,Glob,Grep,Bash"
 
+      # Pinned from the docs repo's own .nvmrc rather than left to whatever the
+      # runner image ships, so formatting matches what contributors produce.
+      - name: Set up Node
+        if: always()
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: _docs/.nvmrc
+
+      - name: Format docs with Prettier
+        if: always()
+        working-directory: _docs
+        run: |
+          BRANCH="docs/pr-${{ steps.pr.outputs.number }}"
+          if [ "$(git rev-parse --abbrev-ref HEAD)" != "$BRANCH" ]; then
+            echo "No docs branch checked out; nothing to format."
+            exit 0
+          fi
+
+          # Format only the pages this branch touches, so the docs PR diff stays
+          # limited to the changes under review.
+          CHANGED=$(mktemp)
+          git diff --name-only --diff-filter=d -z \
+            "${{ steps.docs-base.outputs.sha }}" HEAD > "$CHANGED"
+          if [ ! -s "$CHANGED" ]; then
+            echo "No doc changes to format."
+            exit 0
+          fi
+
+          # The docs repo pins Prettier, so this matches what its pre-commit hook
+          # produces. `--ignore-unknown` skips files Prettier has no parser for.
+          npm ci --no-audit --no-fund
+          xargs -0 npx prettier --ignore-unknown --write < "$CHANGED"
+
+          if git diff --quiet; then
+            echo "Doc changes are already formatted."
+            exit 0
+          fi
+
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git commit -am "chore: format with Prettier"
+          git push origin "$BRANCH"
+
       - name: Assign docs PR
         if: always()
         env: