From 734a45cf66149c474556480ee916747af0d777bb Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Mon, 20 Jul 2026 18:36:21 +0800 Subject: [PATCH 1/2] ci: deploy documentation to GitHub Pages --- ...026-07-13-documentation-site-projection.md | 6 +- .github/workflows/docs-pages.yml | 84 +++++++++++++++++++ website/.vitepress/config.ts | 1 + 3 files changed, 89 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/docs-pages.yml diff --git a/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.md b/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.md index b3bdbb0c1b..44d1b17a5b 100644 --- a/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.md +++ b/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.md @@ -20,7 +20,7 @@ The projector parses Markdown links without reserializing the document. A link t Mermaid renders the canonical diagrams. The website workspace explicitly declares the five packages that `vitepress-plugin-mermaid` asks Vite to prebundle because pnpm's strict dependency isolation otherwise makes those transitive packages unavailable to the local development server; Knip records this runtime-only use as an intentional dependency exception. -Site publication is separate from site construction. The repository contains local development and build commands, but no hosting or deployment workflow until a public destination is chosen. +Site publication remains separate from site construction. A dedicated GitHub Actions workflow runs the existing documentation gates, uploads `website/.dist` as a Pages artifact, and deploys only after the build succeeds. `actions/configure-pages` supplies the destination's base path to VitePress at build time, so the private Pages origin, a later public project path, and a custom domain do not require distinct checked-in configurations. Pages visibility remains a repository hosting setting rather than a workflow permission. ## Alternatives considered @@ -34,8 +34,10 @@ Site publication is separate from site construction. The repository contains loc **Build only in a deployment workflow.** A deployment job can reveal rendering failures after merge. Keeping the production build in `doc-sync` makes the same failure visible locally and in ordinary CI even when no public deployment exists. +**Hard-code the public project path.** A fixed `/deepseek-harness/` base works for the public project URL but not for the unique origin assigned to a private Pages site or for a future custom domain. Consuming Pages metadata keeps one build contract across those destinations. + ## Consequences -Documentation facts have one editable home, public routes remain stable across source moves, and the site can include generated references without committing another generated copy. Local development watches canonical inputs and regenerates the disposable projection. +Documentation facts have one editable home, public routes remain stable across source moves, and the site can include generated references without committing another generated copy. Local development watches canonical inputs and regenerates the disposable projection. Merges that affect the documentation site deploy the checked result to Pages, while manual dispatch provides a recovery and validation entry point. The publication manifest is a maintained allowlist, and link projection adds a small repository-specific build adapter. A new kind of Markdown link behavior needs a projector test. Mermaid support also increases the client bundle size, but preserves diagrams already used by the canonical documentation. diff --git a/.github/workflows/docs-pages.yml b/.github/workflows/docs-pages.yml new file mode 100644 index 0000000000..41e003ae8a --- /dev/null +++ b/.github/workflows/docs-pages.yml @@ -0,0 +1,84 @@ +name: Deploy documentation + +on: + push: + # Keep this branch only for the pre-merge deployment validation run. + branches: [master, worktree/docs-pages-deploy] + paths: + - '.github/workflows/docs-pages.yml' + - 'docs/**' + - 'package.json' + - 'pnpm-lock.yaml' + - 'pnpm-workspace.yaml' + - 'scripts/project-doc-site.ts' + - 'scripts/project-doc-site.spec.ts' + - 'website/**' + workflow_dispatch: + +concurrency: + group: github-pages + cancel-in-progress: false + +permissions: + contents: read + +env: + PRIMARY_NODE_VERSION: '24' + +jobs: + build: + runs-on: ubuntu-latest + permissions: + contents: read + pages: read + steps: + - uses: actions/checkout@v6 + + - uses: actions/setup-node@v6 + with: + node-version: ${{ env.PRIMARY_NODE_VERSION }} + + - name: Enable corepack (pnpm) + run: corepack enable + + - name: Resolve pnpm store path + id: pnpm-store + run: echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT" + + - uses: actions/cache@v4 + with: + path: ${{ steps.pnpm-store.outputs.path }} + key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }} + restore-keys: | + ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm- + + - name: Install (immutable) + run: pnpm install --frozen-lockfile + + - name: Configure Pages + id: pages + uses: actions/configure-pages@v5 + + - name: Verify and build documentation + env: + DOCS_BASE: ${{ steps.pages.outputs.base_path }}/ + run: pnpm run doc-sync + + - name: Upload Pages artifact + uses: actions/upload-pages-artifact@v4 + with: + path: website/.dist + + deploy: + needs: build + runs-on: ubuntu-latest + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/website/.vitepress/config.ts b/website/.vitepress/config.ts index b9f38b0f7e..3ea513a0bb 100644 --- a/website/.vitepress/config.ts +++ b/website/.vitepress/config.ts @@ -108,6 +108,7 @@ const sharedTheme: Pick Date: Mon, 20 Jul 2026 18:41:10 +0800 Subject: [PATCH 2/2] ci: restrict Pages deployment to master --- .github/workflows/docs-pages.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/docs-pages.yml b/.github/workflows/docs-pages.yml index 41e003ae8a..e1ad20997d 100644 --- a/.github/workflows/docs-pages.yml +++ b/.github/workflows/docs-pages.yml @@ -2,8 +2,7 @@ name: Deploy documentation on: push: - # Keep this branch only for the pre-merge deployment validation run. - branches: [master, worktree/docs-pages-deploy] + branches: [master] paths: - '.github/workflows/docs-pages.yml' - 'docs/**'