From afd4f57c573ef6c2c520ed81d9c07851a0ae0047 Mon Sep 17 00:00:00 2001 From: "Jiaxiao (mossaka) Zhou" Date: Fri, 13 Mar 2026 00:13:18 +0000 Subject: [PATCH 1/2] feat(ci): add documentation preview environment for PRs Build and upload docs-site as an artifact when PRs modify documentation files. Posts a comment on the PR with a link to download the preview. Co-Authored-By: Claude Opus 4.6 (1M context) --- .github/workflows/docs-preview.yml | 94 ++++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 .github/workflows/docs-preview.yml diff --git a/.github/workflows/docs-preview.yml b/.github/workflows/docs-preview.yml new file mode 100644 index 000000000..6930089f9 --- /dev/null +++ b/.github/workflows/docs-preview.yml @@ -0,0 +1,94 @@ +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 + run: | + cd docs-site + npm run build + + - name: Upload preview artifact + 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 body = [ + '## 📄 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'); + + // 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, + }); + } From fcdb8b476086023e006e99a757834a702333a14b Mon Sep 17 00:00:00 2001 From: "Jiaxiao (mossaka) Zhou" Date: Fri, 13 Mar 2026 00:31:02 +0000 Subject: [PATCH 2/2] fix(ci): handle docs-site build failure gracefully in preview workflow The docs-site build fails due to a Zod v4/Starlight compatibility issue in the 404 page rendering. Since build-preview is not a required CI check, make the build step continue-on-error and adjust the PR comment to indicate whether the build succeeded or failed. Co-Authored-By: Claude Opus 4.6 (1M context) --- .github/workflows/docs-preview.yml | 38 ++++++++++++++++++++---------- 1 file changed, 25 insertions(+), 13 deletions(-) diff --git a/.github/workflows/docs-preview.yml b/.github/workflows/docs-preview.yml index 6930089f9..c53c00229 100644 --- a/.github/workflows/docs-preview.yml +++ b/.github/workflows/docs-preview.yml @@ -36,11 +36,14 @@ jobs: 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 }} @@ -52,19 +55,28 @@ jobs: with: script: | const artifactUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`; - const body = [ - '## 📄 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'); + 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({