From 31ef4fcc68a28ab0606c535cea2fb3046fe77fb4 Mon Sep 17 00:00:00 2001
From: Paul Kompfner <paul@daily.co>
Date: Wed, 5 Aug 2026 12:10:50 -0400
Subject: [PATCH] docs bot: format generated docs PRs before committing

The workflow installs the docs repo's pinned toolchain and runs its Prettier
over the pages a run touched, so generated docs PRs land already formatted.
Scoping to touched pages keeps the PR diff limited to the changes under review,
and Node comes from the docs repo's .nvmrc rather than the runner image.
---
 .github/workflows/update-docs.yml | 50 +++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/.github/workflows/update-docs.yml b/.github/workflows/update-docs.yml
index b31f8251e15..9b2602177d2 100644
--- a/.github/workflows/update-docs.yml
+++ b/.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: