From 91f06f55a32968b47b825f8373616ce9e4f9a02a Mon Sep 17 00:00:00 2001
From: morluto <76467478+morluto@users.noreply.github.com>
Date: Sat, 24 Oct 2026 02:36:22 +0800
Subject: [PATCH] ci(docs): render documentation in the selected docs lane

---
 .github/workflows/ci.yml | 4 +++-
 docs/testing.md          | 7 +++++++
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 89a6c39c45..05d2c19bd1 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -949,7 +949,7 @@ jobs:
           retention-days: 30
 
   docs:
-    name: Docs Generation
+    name: Documentation
     needs: changes
     if: needs.changes.outputs.docs == 'true'
     runs-on: ubuntu-latest
@@ -964,6 +964,8 @@ jobs:
         uses: ./.github/actions/npm-cache
       - run: npm ci
       - run: npm run docs:check
+      - name: Render documentation and validate page links
+        run: npm run docs:build
       - name: Generation leaves authored files unchanged
         run: git diff --exit-code
       - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
diff --git a/docs/testing.md b/docs/testing.md
index e44af7e0d6..f429f65482 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -25,6 +25,7 @@ behavior, and complete CI evidence before merging.
 | `npm run check:changed`           | Cached typecheck/lint and branch-related source feedback                                                                |
 | `npm run check:pr`                | Opt-in complete local deterministic gate and generated-file checks                                                      |
 | `npm run docs:check`              | Generated-document validation and fresh onboarding example consistency checks                                           |
+| `npm run docs:build`              | Render VitePress documentation and apply its page-link checks; no live external-link or GitHub fragment verification    |
 
 The general source suite above runs on Linux in CI, and Windows CI runs a
 curated lane ([Native platform baseline in CI](#native-platform-baseline-in-ci)).
@@ -34,6 +35,12 @@ semantics. Compare failures against the base revision, or run the suite on
 Linux or WSL, before attributing them to a change. See `CONTRIBUTING.md` →
 Windows source checkouts.
 
+The CI documentation lane runs both `docs:check` and `docs:build` when the
+existing change classifier selects documentation or its producing inputs.
+Generated facts and rendered page links have separate checks. VitePress does not
+establish that every external URL or GitHub-rendered localized heading exists;
+verify those destinations when editing them.
+
 For example:
 
 ```bash