feat(ci): add documentation preview environment for PRs

.github/workflows/docs-preview.yml

@@ -0,0 +1,106 @@
+name: Documentation Preview
+
+on:
+  pull_request:
+    paths:
+      - 'docs-site/**'
+      - 'docs/**'
+      - '*.md'
+      - '.github/workflows/docs-preview.yml'
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: docs-preview-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  build-preview:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: docs-site/package-lock.json
+
+      - name: Install dependencies
+        run: |
+          cd docs-site
+          npm ci
+
+      - name: Build documentation
+        id: build
+        continue-on-error: true
+        run: |
+          cd docs-site
+          npm run build
+
+      - name: Upload preview artifact
+        if: steps.build.outcome == 'success'
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: docs-preview-pr-${{ github.event.pull_request.number }}
+          path: docs-site/dist
+          retention-days: 7
+
+      - name: Comment on PR
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
+        with:
+          script: |
+            const artifactUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
+            const buildOutcome = '${{ steps.build.outcome }}';
+            const body = buildOutcome === 'success'
+              ? [
+                  '## Documentation Preview',
+                  '',
+                  `Documentation has been built for this PR.`,
+                  '',
+                  `**[Download preview artifact](${artifactUrl})**`,
+                  '',
+                  'To view locally:',
+                  '1. Download the `docs-preview-pr-${{ github.event.pull_request.number }}` artifact from the workflow run',
+                  '2. Unzip and open `index.html` in your browser',
+                  '',
+                  `_Built from commit ${context.sha.substring(0, 7)}_`,
+                ].join('\n')
+              : [
+                  '## Documentation Preview',
+                  '',
+                  `Documentation build failed for this PR. [View logs](${artifactUrl}).`,
+                  '',
+                  `_Built from commit ${context.sha.substring(0, 7)}_`,
+                ].join('\n');
+
+            // Find existing comment
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+
+            const botComment = comments.find(c =>
+              c.user.type === 'Bot' && c.body.includes('Documentation Preview')
+            );
+
+            if (botComment) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: botComment.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              });
+            }