feat(website,docs,build): 首屏改成大标题 + 整行渐变填色，官网与文档站合并发布到 GitHub Pages

官网（`website/`） - 首屏标题放大一档（`--fs-display` 上限 3.6rem → 4rem），第二行改成**整行渐变填色**，照 ClassIsland 官网那种「大标题 + 中间一段渐变 + 一行副标 + 一排徽章 + 两个按钮」的写法； - 标题下补一排 mono 芯片（版本 / Windows / Linux·Docker / 触摸屏），主按钮换成「立即下载」+「GitHub 仓库」； - 顶部导航与页脚补「文档站」入口；页脚原本指向 GitHub blob 的那三个链接改成指向文档站 —— 那几个文件已经移到 `docs/management/` 下，原链接是 404。 > ⚠ 渐变那一行**不参与逐字揭示**：`main.js` 的 `setupHeadlineReveal` 会跳过 `.reveal-grad`。 > 拆成 per-char 的 `inline-block` 之后每个字各自建一层合成，祖先的 `background-clip: text` > 就穿不过去，渐变会整行失效 —— 所以它按整行入场（透明度 + 轻微上浮）。站点发布（`.github/workflows/pages.yml`，取代 `docs.yml`） - **一个仓库在 GitHub Pages 上只有一个站点**，所以官网与文档站拼成一份产物：官网在根、文档站在 `/docs/` 下，组装逻辑在 `scripts/build-pages.mjs`； - 站点根 404 由 `website/404.html` 提供（含 `{{BASE}}` 占位符，由脚本与 workflow 按仓库名注入）； - 官网目录里的 `serve.mjs` 与 `tools/` 是开发用的，不发布； - `website/serve.mjs` 把 `../docs/_site` 挂在 `/docs/` 下，让本地预览与线上同形 —— 否则页脚那几个「文档站」链接在本地全是 404； - 文档站模板顶栏补一个「官网」入口（`{{_rel}}../`）。版本迭代 - `scripts/version.mjs` 补上**官网上手写的三处版本号**（顶栏徽标 / 首屏芯片 / 页脚）。官网是纯静态站、没有构建步骤，没有哪段代码会去读 `package.json`，漏改的后果是首页一直挂着旧版本号 —— 而那是别人看到的第一眼。落点从 10 处变成 13 处， `AGENTS.md` §4.4 与 `docs/dev/release.md` 同步。
2026-10-06 16:44:23 +08:00
1 parent 19c2aa07b2
commit ded10118f5
@@ -1,26 +1,29 @@
-name: 发布文档站
+name: 发布官网与文档站

-# 把 docs/ 用 docfx 构建成静态站点，部署到 GitHub Pages。
+# 把一个 GitHub Pages 站点发出去：
 #
-# 为什么单独一个 workflow：
-#   docfx 是 .NET 工具（`dotnet tool install -g docfx`），需要在 CI 里装 .NET SDK；
-#   而文档站与三个交付物的发布节奏也完全不一样 —— 改一个错别字就该上线，
-#   不该为此打个安装包、发个 Release。
+#   /                产品官网（website/，纯静态、无构建步骤）
+#   /docs/           文档站（docfx 构建 docs/ 得到）
+#
+# 为什么要拼成一个站点：**一个仓库在 GitHub Pages 上只有一个站点**。两者发布节奏也不一样
+# （改个错别字就该上线，不该为此打个安装包），所以走 workflow 而不是塞进发布流程。
 #
 # 站点地址：https://lovechengke.github.io/ClassHelper/
 # 需要在仓库 Settings → Pages 里把 Source 选成「GitHub Actions」（只需做一次）。
 #
-# 本地预览：pnpm docs:serve
+# 本地预览：pnpm dev:site（官网在 :5180，文档站挂在同一个端口的 /docs/ 下）

 on:
  push:
    branches: [master]
    paths:
-      # 文档内容与构建脚本
+      - 'website/**'
      - 'docs/**'
-      - '.github/workflows/docs.yml'
-      # 顶栏那个版本徽标取自根 package.json（docs/build.mjs 通过 --metadata 注入），
-      # 所以版本号变了也要重新发一次文档站
+      - 'scripts/build-pages.mjs'
+      - '.github/workflows/pages.yml'
+      # 两个页面上的版本号都取自根 package.json
+      # （官网是手写的徽章，文档站由 docs/build.mjs 用 --metadata 注入），
+      # 所以版本号变了也要重新发一次
      - 'package.json'
  workflow_dispatch:

@@ -59,19 +62,24 @@ jobs:
        # --check 把 docfx 的警告当错误：最常见的警告是"某个 .md 没被任何 toc.yml 引用"，
        # 那种页面会被构建出来但没有侧边栏 —— 属于必须修掉的疏漏，不该悄悄上线。
        #
-        # DOCS_BASE 是给 404 页用的：项目页挂在 /<仓库名>/ 子路径下，而浏览器按**被请求的路径**
-        # 解析 404 页里的相对链接，所以要把站点根钉成 <base>。这里从仓库名算，改仓库名不用改脚本。
+        # DOCS_BASE 是给文档站那份 404 用的：项目页挂在 /<仓库名>/ 子路径下，而浏览器按
+        # **被请求的路径**解析 404 页里的相对链接，所以要把站点根钉成 <base>。
        env:
-          DOCS_BASE: /${{ github.event.repository.name }}/
+          DOCS_BASE: /${{ github.event.repository.name }}/docs/
        run: node docs/build.mjs --check

+      - name: 组装站点（官网在根，文档站在 /docs/）
+        env:
+          SITE_BASE: /${{ github.event.repository.name }}/
+        run: node scripts/build-pages.mjs
+
      - name: 配置 Pages
        uses: actions/configure-pages@v5

      - name: 上传构建产物
        uses: actions/upload-pages-artifact@v3
        with:
-          path: docs/_site
+          path: .cache/pages

  deploy:
    needs: build
@@ -66,7 +66,10 @@ deploy/                      Dockerfile / docker-compose{,.sqlite}.yml / nginx.c
                             profile.d/ logrotate.d/ systemd/（装到 /etc 的模板）
                             Dockerfile.linux-package（安装包内那份，--mode docker 用）
                             classhelper.service（systemd 模板，5 个占位符）/ .env{,.sqlite}.example
-docs/                        **文档站**（docfx 项目，发布到 GitHub Pages；不进 pnpm workspace）
+docs/                        **文档站**（docfx 项目；不进 pnpm workspace）
+                             ⚠ 与官网（website/）共用**同一个** GitHub Pages 站点：官网在根、
+                               文档站在 /docs/ 下。一个仓库在 Pages 上只有一个站点，
+                               拼装由 scripts/build-pages.mjs 完成，见 §4.4「官网与文档站怎么发布」。
                             docfx.json / toc.yml（顶栏）+ 各章节自己的 toc.yml（侧栏）
                             get-started/ app/ management/ dev/（四章内容）
                             management/{production,linux-deploy,mysql}.md（部署与换库）
@@ -83,6 +86,12 @@ docs/                        **文档站**（docfx 项目，发布到 GitHub Pag
 website/                     产品官网（**纯静态、无构建步骤**，不进 pnpm workspace）
                             index.html / assets/{styles.css,motion.js,main.js,icon.png,shots/}
                             serve.mjs（本地预览）/ tools/capture-shots.mjs（实机图采集）
+                             404.html（**站点根** 404，含 {{BASE}} 占位符，由 build-pages.mjs 注入）
+                             ⚠ serve.mjs 把 ../docs/_site 挂在 /docs/ 下，为的是让本地与线上同形 ——
+                               否则页脚那几个「文档站」链接在本地全是 404。文档站得先 pnpm docs:build。
+                             ⚠ 首屏标题第二行是 .reveal-grad：**它不参与逐字揭示**
+                               （main.js 会跳过它）。拆成 per-char 的 inline-block 后每个字各自建一层合成，
+                               祖先的 background-clip: text 就穿不过去，渐变会整行失效。
                             ⚠ assets/motion.js 是动效层：曲线与弹簧 token 逐条取自 beUI
                               （beui.dev/components/motion，见 README §7「官网」）。
                               改官网动效请改 token 表，不要在组件里另写 duration / cubic-bezier。
@@ -219,11 +228,13 @@ pnpm build:classisland-plugin
 | `pnpm dist:server` / `dist:win` / `dist:dir` / `dist:all` | 打包服务端安装程序 / 客户端安装包 / 免安装目录 / 全部                                                 |
 | `pnpm dist:server:linux`                                  | 打包 **Linux 服务端安装包**（`classhelper-server-linux-x64-<版本>.tar.gz` + `.sha256`）—— 见 §5 第 59 条 |
 | `pnpm icons`                                              | 从 `build/classhelper.png` 派生全部图标（PWA / favicon / 托盘 / 安装包 / 插件 / 官网 / 文档站 / 界面内品牌标） |
-| `pnpm version:check`                                      | 逐处列出并比对 10 个落点的版本号，不一致即 exit 1（见 §4.4「版本迭代」）                              |
-| `pnpm version:bump patch\|minor\|major`                   | **改版本号的唯一入口**：一次改写全部 10 处（含插件清单与 C# 里的常量）                                |
+| `pnpm version:check`                                      | 逐处列出并比对 13 个落点的版本号，不一致即 exit 1（见 §4.4「版本迭代」）                              |
+| `pnpm version:bump patch\|minor\|major`                   | **改版本号的唯一入口**：一次改写全部 13 处（含插件清单、C# 里的常量，以及官网上手写的三处版本号）     |
 | `pnpm docs:build`                                         | 构建文档站到 `docs/_site`（需要 .NET SDK 8 + `dotnet tool install -g docfx`）                         |
 | `pnpm docs:serve`                                         | 构建文档站并起本地预览 → http://127.0.0.1:5181                                                        |
 | `pnpm docs:check`                                         | 构建文档站并把 docfx 的警告当错误（发布前用；最常见的警告是"某个 .md 没被任何 toc.yml 引用"）          |
+| `pnpm pages:build`                                        | 把官网（根）与文档站（/docs/）拼成一份 GitHub Pages 产物到 `.cache/pages`（CI 用；见 §4.4）           |
+| `pnpm dev:site`                                           | 构建文档站后起官网预览 → http://127.0.0.1:5180（文档站挂在同端口的 /docs/ 下，与线上同形）            |

 ### 端口

@@ -285,7 +296,7 @@ pnpm dist:classisland-plugin
 > 算一次发布：攒够一批功能 / 修好一个用户能感知的 bug / 要给别人一份新安装包。
 > 不算：改注释、改文档、重构、加测试。

-**同一个版本号写在 10 个文件里**（5 份 `package.json`、`deploy/package.runtime.json`、
+**同一个版本号写在 13 处（11 个文件）里**（5 份 `package.json`、`deploy/package.runtime.json`、
 两个 `docker-compose*.yml` 的镜像 tag、插件 `manifest.yml`、以及插件 C# 里的 `PluginVersion` 常量）。
 手工改必然漏一处，而漏掉的那处**不会报错** —— 只会在某个不常走的分支上表现为"版本号对不上"。
 所以**改版本号的唯一入口是脚本**：
@@ -350,17 +361,29 @@ gh workflow run release-linux-server.yml -f tag=v<版本> -f attach=true
 **已发布的版本号不要复用**：客户端把它记进「忽略此版本」，两端各有 30 分钟缓存 ——
 同号换内容会让「检查更新」永久失灵。要修就 `pnpm version:bump patch` 发新号。

-#### 文档站怎么发布
+#### 官网与文档站怎么发布

-**不用做任何事。** 推 master 时只要 `docs/**`、`package.json` 或 `.github/workflows/docs.yml`
-变过，`.github/workflows/docs.yml` 就会用 docfx 构建并部署到 GitHub Pages
-（`https://lovechengke.github.io/ClassHelper/`）。
+**不用做任何事。** 推 master 时只要 `website/**`、`docs/**`、`scripts/build-pages.mjs` 或
+`package.json` 变过，`.github/workflows/pages.yml` 就会构建并部署到 GitHub Pages：
+
+```
+https://lovechengke.github.io/ClassHelper/          ← 官网（website/，纯静态无构建）
+https://lovechengke.github.io/ClassHelper/docs/     ← 文档站（docfx 构建 docs/）
+```
+
+> **一个仓库在 GitHub Pages 上只有一个站点**，所以两者是拼在一起发的
+> （`scripts/build-pages.mjs` 把 `website/` 放到根、`docs/_site/` 放到 `docs/` 下）。
+> 官网在根是因为产品页的地址最短最好分享；文档站多一层路径没有代价。
+> 改这个布局要同时动三处：`scripts/build-pages.mjs`、本 workflow 里的 `DOCS_BASE`，
+> 以及文档站模板 `docs/templates/classhelper/layout/_master.tmpl` 里那个 `{{_rel}}../` 的「官网」入口。

 - 顶栏的版本徽标取自根 `package.json`（`docs/build.mjs` 用 `--metadata _chVersion=…` 注入），
-  **不要在文档里再写一份版本号**；
+  **不要在文档里再写一份版本号**；官网首屏那排芯片里的 `v1.1.2` 是手写的，发版时要一起改；
 - 首次启用需要在仓库 Settings → Pages 把 Source 选成「GitHub Actions」（只需一次）；
- 404 页的 `<base>` 由 workflow 按仓库名注入 —— 项目页挂在 `/<仓库名>/` 子路径下，
-  而浏览器是按**被请求的路径**解析 404 页里的相对链接的。本地预览时 base 是 `./`。
+- 404 页的 `<base>` 由 `scripts/build-pages.mjs`（本地 `./`）与 workflow（CI 传 `/<仓库名>/`）注入 ——
+  项目页挂在 `/<仓库名>/` 子路径下，而浏览器是按**被请求的路径**解析 404 页里的相对链接的；
+- 本地预览：`pnpm dev:site`（官网在 http://127.0.0.1:5180，文档站挂在同一个端口的 `/docs/` 下，
+  与线上同形）；只想单独看文档站用 `pnpm docs:serve`。

 ---

@@ -19,9 +19,9 @@ description: 改版本号、跑验收、打安装包、发 GitHub Release、发
 | 要给别人一份新安装包                    | 只在自己机器上跑             |
 | 插件单独发补丁（只动插件第 4 段版本号） | —                            |

-## 版本号写在哪（10 处）
+## 版本号写在哪（13 处 / 11 个文件）

-同一个版本号出现在 10 个文件里，**手工改必然漏一处**，而漏掉的那处不会报错：
+同一个版本号分散在 13 个落点上，**手工改必然漏一处**，而漏掉的那处不会报错：

 | 文件                                                             | 内容                            |
 | ---------------------------------------------------------------- | ------------------------------- |
@@ -31,6 +31,10 @@ description: 改版本号、跑验收、打安装包、发 GitHub Release、发
 | `deploy/docker-compose.yml`、`docker-compose.sqlite.yml`         | 镜像 tag 的默认值               |
 | `packages/classisland-plugin/manifest.yml`                       | 插件清单（四段：`x.y.z.0`）     |
 | `packages/classisland-plugin/src/Services/BridgeService.cs`      | 插件上报的 `PluginVersion` 常量 |
+| `website/index.html` × 3                                         | 官网顶栏徽标 / 首屏芯片 / 页脚  |
+
+最后一行值得单独说：官网是**纯静态站、没有构建步骤**，没有哪段代码会去读 `package.json`，
+所以那三处只能靠脚本一起改 —— 漏了的话首页会一直挂着旧版本号，而那是别人看到的第一眼。

 所以**改版本号的唯一入口是脚本**：

@@ -150,13 +154,23 @@ gh release upload v1.1.3 \
 gh workflow run release-linux-server.yml -f tag=v1.1.3 -f attach=true
 ```

-### 8. 文档站
+### 8. 官网与文档站

-**不用做任何事。** 推送 master 时只要 `docs/**` 或 docs 的 workflow 变过，
-[`docs.yml`](https://github.com/LoveChengke/classhelper/blob/master/.github/workflows/docs.yml)
-会自动用 docfx 构建并部署到 GitHub Pages。
+**不用做任何事。** 推送 master 时只要 `website/**`、`docs/**`、`scripts/build-pages.mjs` 或
+`package.json` 变过，
+[`pages.yml`](https://github.com/LoveChengke/classhelper/blob/master/.github/workflows/pages.yml)
+就会把两者构建成**同一个** GitHub Pages 站点发出去：

-文档站顶栏的版本徽标取自根 `package.json`，所以第 1 步改完就跟着变了。
+```
+https://lovechengke.github.io/ClassHelper/          ← 官网
+https://lovechengke.github.io/ClassHelper/docs/     ← 文档站
+```
+
+（一个仓库在 Pages 上只有一个站点，所以是拼在一起发的 —— 官网在根、文档站在 `/docs/` 下。）
+
+文档站顶栏的版本徽标取自根 `package.json`，所以第 1 步改完就跟着变了；
+官网首屏那排芯片、顶栏徽标与页脚里的版本号也是**由 `pnpm version:bump` 一起改的**
+（它们是那 13 个落点里的三个）。

 ### 9. 检查

@@ -30,7 +30,7 @@
      "_appFooter": "<div class=\"ch-footer\"><span>班级小助手（Class Helper）· 文档</span><span class=\"ch-footer-sep\">·</span><a href=\"https://github.com/LoveChengke/classhelper\">GitHub 仓库</a><span class=\"ch-footer-sep\">·</span><a href=\"https://github.com/LoveChengke/classhelper/releases\">下载与更新日志</a><span class=\"ch-footer-sep\">·</span><span>构建于 docfx</span></div>"
    },
    "sitemap": {
-      "baseUrl": "https://lovechengke.github.io/ClassHelper/",
+      "baseUrl": "https://lovechengke.github.io/ClassHelper/docs/",
      "changefreq": "weekly",
      "priority": 0.5
    }
@@ -1,6 +1,6 @@
 /**
 * 文档站本地预览用的最小静态服务器（构建产物 docs/_site）。
- * 正式发布走 GitHub Pages（.github/workflows/docs.yml），不需要这个文件。
+ * 正式发布走 GitHub Pages（.github/workflows/pages.yml：官网在根、文档站在 /docs/），不需要这个文件。
 *
 *   node docs/build.mjs --serve     → 构建后直接预览（推荐）
 *   node docs/serve.mjs             → http://127.0.0.1:5181（要求已经构建过）
@@ -100,6 +100,10 @@
              </form>
              {{/_enableSearch}}
            </div>
+            <!-- 官网入口。文档站被发布在官网下面一层（<站点根>/docs/），所以从任意一页
+                 回到官网就是「先退到文档站根（_rel），再退一层」。这个耦合与控制它的
+             .github/workflows/pages.yml 是同一件事，那边改布局这边要跟着改。 -->
+            <a class="ch-nav-site" href="{{_rel}}../" title="产品官网">官网</a>
            <a class="ch-nav-github" href="https://github.com/LoveChengke/classhelper" target="_blank" rel="noopener noreferrer" title="GitHub 仓库" aria-label="GitHub 仓库">
              <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="18" height="18" fill="currentColor" aria-hidden="true"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27s1.36.09 2 .27c1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.01 8.01 0 0 0 16 8c0-4.42-3.58-8-8-8Z"/></svg>
            </a>
@@ -108,10 +108,29 @@ header.bg-body {
  color: var(--bs-secondary-color);
 }

+/* 顶栏右侧那一组（官网链接 + GitHub 图标）。
+   `margin-left: auto` 只挂在组里的**第一个**元素上 —— 挂两个各推各的会散开。 */
+.ch-nav-site {
+  margin-left: auto;
+  padding: 6px 10px;
+  border-radius: 6px;
+  font-size: 14px;
+  color: var(--bs-secondary-color);
+  text-decoration: none;
+  white-space: nowrap;
+  transition:
+    color 0.15s ease,
+    background-color 0.15s ease;
+}
+
+.ch-nav-site:hover {
+  color: var(--bs-body-color);
+  background: var(--ch-accent-soft);
+}
+
 .ch-nav-github {
  display: inline-flex;
  align-items: center;
-  margin-left: auto;
  padding: 6px 8px;
  border-radius: 6px;
  color: var(--bs-secondary-color);
@@ -40,6 +40,8 @@
    "version:bump": "node scripts/version.mjs --bump",
    "docs:build": "node docs/build.mjs",
    "docs:serve": "node docs/build.mjs --serve",
+    "pages:build": "node scripts/build-pages.mjs",
+    "dev:site": "pnpm docs:build && node website/serve.mjs",
    "docs:check": "node docs/build.mjs --check",
    "dist:win": "pnpm --filter @classhelper/desktop-client dist:win",
    "dist:dir": "pnpm --filter @classhelper/desktop-client dist:dir",
@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * 组装 GitHub Pages 站点 —— `pnpm pages:build`，CI 里由 .github/workflows/pages.yml 调用。
+ *
+ * ## 为什么需要它
+ *
+ * **一个仓库在 GitHub Pages 上只有一个站点**，但我们要发布两个东西：
+ * 产品官网（`website/`，纯静态、无构建步骤）与文档站（`docs/`，docfx 构建出来）。
+ * 于是把两者拼成一个站点，按这个布局：
+ *
+ *   <站点根>/            官网（website/ 的内容）
+ *   <站点根>/docs/       文档站（docs/_site 的内容）
+ *
+ * 官网在根、文档站在 `/docs/` 下 —— 产品页的地址最短最好分享，文档站多一层路径没有代价。
+ *
+ * ## 三件容易忽略的事
+ *
+ * ① **404 页要注入站点根**。Pages 对任何未知路径都返回**站点根**的 404.html，
+ *    而浏览器是按**被请求的那个路径**解析页面里的相对链接的 —— 不钉 `<base>`，
+ *    访问 `/ClassHelper/docs/typo` 时页面上所有链接都会指到 `/ClassHelper/docs/` 下面去。
+ *    （文档站自己那份 `docs/404.html` 只在「文档站被单独托管」时才用得上，合并站点里备而不用。）
+ * ② **官网目录里那两个开发用的东西不能发出去**：`serve.mjs`（本地预览服务器）与
+ *    `tools/`（实机截图采集脚本，会真的开 Electron 窗口）。它们对静态托管没有意义。
+ * ③ **`.nojekyll`**：现在走的是 `actions/upload-pages-artifact`，不经过 Jekyll，
+ *    但留着这个文件不花任何代价，万一哪天切回分支发布也不会因为 `_` 开头的目录被吞掉。
+ *
+ * 用法：
+ *   node scripts/build-pages.mjs                      # 输出到 .cache/pages/
+ *   SITE_BASE=/ClassHelper/ node scripts/build-pages.mjs
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const websiteDir = path.join(root, 'website');
+const docsDir = path.join(root, 'docs', '_site');
+const outDir = path.join(root, '.cache', 'pages');
+
+/** 站点根路径。CI 里按仓库名传（项目页挂在 /<仓库名>/ 下），本地预览用 './'。 */
+const BASE = process.env.SITE_BASE ?? './';
+
+/** 官网目录里不发出去的东西（开发用） */
+const SKIP = new Set(['serve.mjs', '404.html']); // 404.html 要注入 base，单独处理
+const SKIP_DIRS = new Set(['tools']);
+
+function copyWebsite() {
+  for (const entry of fs.readdirSync(websiteDir, { withFileTypes: true })) {
+    if (entry.isDirectory() && SKIP_DIRS.has(entry.name)) continue;
+    if (entry.isFile() && SKIP.has(entry.name)) continue;
+    fs.cpSync(path.join(websiteDir, entry.name), path.join(outDir, entry.name), { recursive: true });
+  }
+}
+
+function main() {
+  if (!fs.existsSync(path.join(docsDir, 'index.html'))) {
+    console.error('[pages] 找不到 docs/_site —— 先跑 `pnpm docs:build`。');
+    process.exit(1);
+  }
+
+  fs.rmSync(outDir, { recursive: true, force: true });
+  fs.mkdirSync(path.join(outDir, 'docs'), { recursive: true });
+
+  copyWebsite();
+  fs.cpSync(docsDir, path.join(outDir, 'docs'), { recursive: true });
+
+  // 站点根的 404：把 {{BASE}} 换成站点根路径
+  const notFound = fs.readFileSync(path.join(websiteDir, '404.html'), 'utf8').replaceAll('{{BASE}}', BASE);
+  fs.writeFileSync(path.join(outDir, '404.html'), notFound, 'utf8');
+
+  // 见文件头 ③
+  fs.writeFileSync(path.join(outDir, '.nojekyll'), '', 'utf8');
+
+  const count = (dir) =>
+    fs.readdirSync(dir, { withFileTypes: true }).reduce((sum, entry) => {
+      if (entry.isDirectory()) return sum + count(path.join(dir, entry.name));
+      return sum + 1;
+    }, 0);
+
+  console.log(`[pages] 站点已组装到 ${path.relative(root, outDir)}（base = ${BASE}）`);
+  console.log(`[pages]   根   ← website/        ${count(outDir) - count(path.join(outDir, 'docs'))} 个文件`);
+  console.log(`[pages]   docs/ ← docs/_site/    ${count(path.join(outDir, 'docs'))} 个文件`);
+}
+
+try {
+  main();
+} catch (error) {
+  console.error('[pages] 失败：', error.message);
+  process.exit(1);
+}
@@ -4,15 +4,17 @@
 *
 * ## 为什么要这个脚本
 *
- * 这个仓库里**同一个版本号写在 10 个地方**（5 份 package.json、运行时常量、两个 compose 文件、
- * 插件清单，以及插件 C# 源码里的一个 const）。手工改必然漏一处，而漏掉的那处**不会报错**，
- * 只会在某个不常走的分支上表现为"版本号对不上"：
+ * 这个仓库里**同一个版本号写在 13 处（11 个文件）**：5 份 package.json、运行时常量、两个 compose 文件、
+ * 插件清单、插件 C# 源码里的一个 const，以及官网页面上三处手写的版本号。手工改必然漏一处，
+ * 而漏掉的那处**不会报错**，只会在某个不常走的分支上表现为"版本号对不上"：
 *
 *   - `deploy/docker-compose*.yml`     镜像 tag 落后 → 服务器上跑的还是旧镜像；
 *   - `deploy/package.runtime.json`    容器 / 安装包里那份依赖清单的版本（人看，但会误导排查）；
 *   - `manifest.yml` + `BridgeService.cs`  ClassIsland 上显示的插件版本
 *     （清单里的 version 与实际上报的 PluginVersion 不一致时，
- *     Web 端「ClassIsland 联动」页显示的版本会对不上插件市场）。
+ *     Web 端「ClassIsland 联动」页显示的版本会对不上插件市场）；
+ *   - `website/index.html` 的那三处        官网是纯静态站、无构建步骤，没有哪段代码会去读
+ *     `package.json`，漏改的后果是**首页上一直挂着旧版本号** —— 那是别人看到的第一眼。
 *
 * 因此：**改版本号的唯一入口是这个脚本**。它按表逐个改写，任何一处没匹配到（或匹配到多处）
 * 就直接失败退出，不做"尽力而为"的部分改写。
@@ -71,11 +73,35 @@ const PLUGIN_TARGETS = [
  },
 ];

-const ALL_TARGETS = [...PRODUCT_TARGETS, ...PLUGIN_TARGETS];
+/**
+ * 官网首屏与页脚那三处手写的版本号。官网是纯静态站，没有构建步骤、也没有哪段代码会去读
+ * `package.json`，所以这三处只能靠脚本一起改 —— 漏了的话官网会一直显示旧版本号，
+ * 而它是别人看到的第一眼。
+ */
+const SITE_TARGETS = [
+  {
+    file: 'website/index.html',
+    label: '（顶栏徽标）',
+    pattern: /(<span class="brand-ver">)(\d+\.\d+\.\d+)(<\/span>)/,
+  },
+  { file: 'website/index.html', label: '（首屏芯片）', pattern: /(<li>v)(\d+\.\d+\.\d+)(<\/li>)/ },
+  {
+    file: 'website/index.html',
+    label: '（页脚）',
+    pattern: /(<p class="foot-ver">版本 )(\d+\.\d+\.\d+)( ·)/,
+  },
+];
+
+const ALL_TARGETS = [...PRODUCT_TARGETS, ...PLUGIN_TARGETS, ...SITE_TARGETS];

 const PRODUCT_RE = /^\d+\.\d+\.\d+$/;
 const PLUGIN_RE = /^\d+\.\d+\.\d+\.\d+$/;

+/** 输出用的名字：同一个文件里有多个落点时带上括号里的说明，否则三行看起来一模一样 */
+function name(target) {
+  return target.label ? `${target.file} ${target.label}` : target.file;
+}
+
 function readTarget(target) {
  const source = fs.readFileSync(path.join(root, target.file), 'utf8');
  const flags = target.pattern.flags.includes('g') ? target.pattern.flags : `${target.pattern.flags}g`;
@@ -102,7 +128,7 @@ function writeVersion(target, next, { dry }) {
    const replaced = source.replace(global, (_m, prefix, _old, suffix) => `${prefix}${next}${suffix}`);
    fs.writeFileSync(path.join(root, target.file), replaced, 'utf8');
  }
-  return `${target.file}  ${hits[0][2]} → ${next}`;
+  return `${name(target)}  ${hits[0][2]} → ${next}`;
 }

 function bumpProduct(current, level) {
@@ -122,7 +148,7 @@ function check(product) {
  for (const target of ALL_TARGETS) {
    const version = readVersion(target);
    if (!version) {
-      console.log(`?? ${target.file.padEnd(width)}  （未匹配到版本号）`);
+      console.log(`?? ${name(target).padEnd(width)}  （未匹配到版本号）`);
      problems.push(`${target.file}：匹配不到版本号`);
      continue;
    }
@@ -131,7 +157,7 @@ function check(product) {
    const ok = PLUGIN_RE.test(version)
      ? version.split('.').slice(0, 3).join('.') === product
      : version === expected;
-    console.log(`${ok ? '  ' : '!!'} ${target.file.padEnd(width)}  ${version}`);
+    console.log(`${ok ? '  ' : '!!'} ${name(target).padEnd(width)}  ${version}`);
    if (!ok) problems.push(`${target.file}：${version} ≠ ${expected}`);
  }

@@ -149,6 +175,7 @@ function apply(next, { dry, product }) {
  const lines = [];
  for (const target of PRODUCT_TARGETS) lines.push(writeVersion(target, next, { dry }));
  for (const target of PLUGIN_TARGETS) lines.push(writeVersion(target, pluginNext, { dry }));
+  for (const target of SITE_TARGETS) lines.push(writeVersion(target, next, { dry }));

  console.log(
    `${dry ? '[dry] 将改写' : '已改写'} ${product} → ${next}（插件 ${product}.0 → ${pluginNext}）：\n`,
@@ -0,0 +1,136 @@
+<!doctype html>
+<!--
+  站点根 404 页（**不经过 docfx**，放在 website/ 下，由发布流程注入 {{BASE}}）。
+
+  一个仓库在 GitHub Pages 上只有一个站点，官网在根、文档站在 /docs/ 下 —— 因此严格来说
+  整个站点只有这一份 404 生效：Pages 对任何未知路径都返回站点根的 404.html。
+  docs/404.html（docfx 那份）只在「文档站被单独托管」时才用得上，合并站点里它是备而不用的。
+  所以这一页要把两条路都给出来：回官网、去文档站。
+-->
+<html lang="zh-CN">
+  <head>
+    <meta charset="utf-8" />
+    <base href="{{BASE}}" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="robots" content="noindex" />
+    <title>页面不存在 | 班级小助手</title>
+    <style>
+      :root {
+        --board: #16231e;
+        --chalk: #eef3ef;
+        --chalk-2: #b9c7bf;
+        --chalk-3: #8a9a91;
+        --blue: #2f8fe6;
+        --line: rgba(238, 243, 239, 0.14);
+      }
+
+      * {
+        box-sizing: border-box;
+      }
+
+      html {
+        color-scheme: dark;
+      }
+
+      body {
+        margin: 0;
+        min-height: 100vh;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        padding: 32px;
+        background: var(--board);
+        color: var(--chalk);
+        font-family:
+          'Segoe UI Variable Text',
+          'Segoe UI',
+          'Microsoft YaHei UI',
+          'Microsoft YaHei',
+          -apple-system,
+          BlinkMacSystemFont,
+          'PingFang SC',
+          'Hiragino Sans GB',
+          sans-serif;
+        line-height: 1.75;
+      }
+
+      main {
+        max-width: 34em;
+      }
+
+      .code {
+        font-family: ui-monospace, Consolas, monospace;
+        font-size: 4rem;
+        font-weight: 600;
+        line-height: 1;
+        color: var(--blue);
+      }
+
+      h1 {
+        margin: 18px 0 10px;
+        font-size: 1.5rem;
+        font-weight: 600;
+      }
+
+      p {
+        margin: 0 0 26px;
+        color: var(--chalk-2);
+      }
+
+      .links {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 10px;
+      }
+
+      a {
+        display: inline-block;
+        padding: 11px 20px;
+        border: 1px solid var(--line);
+        border-radius: 4px;
+        color: var(--chalk);
+        text-decoration: none;
+        transition:
+          border-color 0.15s ease,
+          color 0.15s ease,
+          background-color 0.15s ease;
+      }
+
+      a:hover {
+        border-color: var(--chalk-3);
+        background: rgba(238, 243, 239, 0.06);
+      }
+
+      a.primary {
+        background: var(--blue);
+        border-color: var(--blue);
+        color: #fff;
+      }
+
+      a.primary:hover {
+        background: #1280dd;
+        border-color: #1280dd;
+      }
+
+      @media (prefers-reduced-motion: reduce) {
+        a {
+          transition: none;
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <div class="code">404</div>
+      <h1>这里没有这一页</h1>
+      <p>链接可能过期了，或者这一页已经被重写进了别的章节。</p>
+      <div class="links">
+        <a class="primary" href="index.html">回到官网首页</a>
+        <a href="docs/index.html">文档站</a>
+        <a href="docs/get-started/index.html">快速上手</a>
+        <a href="docs/faq.html">常见问题</a>
+        <a href="https://github.com/LoveChengke/ClassHelper">GitHub 仓库</a>
+      </div>
+    </main>
+  </body>
+</html>
@@ -60,6 +60,11 @@

    const units = [];
    lines.forEach((line) => {
+      // 整行渐变填色的那一行**不拆字**，整行做一个单元（见 styles.css 的 .reveal-grad）：
+      // 拆成 per-char 的 inline-block 后，每个字各自建一层合成，祖先的
+      // `background-clip: text` 就穿不过去了，渐变会整行失效。
+      if (line.classList.contains('reveal-grad')) return;
+
      const text = line.textContent.trim();
      line.textContent = '';
      for (const char of Array.from(text)) {
@@ -62,7 +62,12 @@
    'Microsoft YaHei UI', 'Microsoft YaHei', 'Noto Sans SC', system-ui, sans-serif;
  --mono: ui-monospace, 'Cascadia Mono', 'SF Mono', Consolas, 'Microsoft YaHei UI', monospace;

-  --fs-display: clamp(2.1rem, 5vw, 3.6rem);
+  /* 首屏标题：比站内其它标题大一档（ClassIsland 官网也是这个量级）。
+     两个数都是量出来的：
+       上限 4rem —— 第一行 11 个汉字 × 1em ≈ 704px，得留在 .hero-intro 的列宽（46em）里；
+       下限 1.8rem —— 375px 屏上可用宽度只有 327px，再大会把「它知道现在是第几节课，」
+                     折成「它知道现在是第几」+ 三个字的孤行。 */
+  --fs-display: clamp(1.8rem, 5.7vw, 4rem);
  --fs-h2: clamp(1.7rem, 3.4vw, 2.5rem);
  --fs-h3: clamp(1.05rem, 1.5vw, 1.2rem);
  --fs-lead: clamp(1rem, 1.5vw, 1.12rem);
@@ -417,10 +422,10 @@ table {
  font-family: var(--display);
  font-weight: 400;
  font-size: var(--fs-display);
-  line-height: 1.32;
+  line-height: 1.22;
  letter-spacing: 0.01em;
  max-width: 20em;
-  margin-bottom: 30px;
+  margin-bottom: 26px;
 }

 /* 标题逐字上浮 —— beUI TextReveal。
@@ -649,9 +654,41 @@ strong {
 }

 /* 首屏文字收成左列（ClassIsland 的 .introduction-col 也是这么窄的一条）。
-   47em ≈ 750px：再窄一点，「它知道现在是第几节课，」的逗号就会掉到第二行去。 */
+   46em ≈ 736px：这一列要能装下放大的「它知道现在是第几节课，」（11 个汉字 × 4rem ），
+   同时右边还要留得下三句事实。两边的数是一起量的，改一个就得回头看另一个。 */
 .hero-intro {
-  max-width: 47em;
+  max-width: 46em;
+}
+
+/* 整行渐变填色 —— ClassIsland 官网的 .gradient-base 那个写法。
+   这一行**不拆字**（main.js 的 setupHeadlineReveal 会跳过它）：拆成 per-char 的
+   inline-block 之后每个字各自建一层合成，祖先的 `background-clip: text` 就穿不过去，
+   渐变会整行失效。所以它按「整行」入场：透明度 + 轻微上浮，比逐字稍晚一点起。 */
+.display .reveal-grad {
+  background-image: linear-gradient(135deg, var(--chalk) 6%, var(--blue) 78%);
+  -webkit-background-clip: text;
+  background-clip: text;
+  color: transparent;
+  -webkit-text-fill-color: transparent;
+  opacity: 0;
+  transition: opacity 0.85s var(--ease-out) 0.24s;
+}
+
+html:not(.reveal-pending) .display .reveal-grad {
+  opacity: 1;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .display .reveal-grad {
+    transform: translateY(14%);
+    transition:
+      opacity 0.85s var(--ease-out) 0.24s,
+      transform 0.85s var(--ease-out) 0.24s;
+  }
+
+  html:not(.reveal-pending) .display .reveal-grad {
+    transform: none;
+  }
 }

 /* 宽屏上把三句事实挪到文字右边，填住那条空 —— ClassIsland 的首屏也是左文右块。
@@ -659,7 +696,7 @@ strong {
@media (min-width: 1080px) {
  .hero .wrap {
    display: grid;
-    grid-template-columns: minmax(0, 47em) 1fr;
+    grid-template-columns: minmax(0, 46em) 1fr;
    grid-template-areas:
      'intro facts'
      'screen screen'
@@ -691,15 +728,47 @@ strong {

 .hero-sub {
  font-family: var(--display);
-  font-size: clamp(1.35rem, 2.6vw, 1.9rem);
-  line-height: 1.5;
+  font-size: clamp(1.4rem, 2.9vw, 2.1rem);
+  line-height: 1.45;
  color: var(--chalk);
-  margin-bottom: 14px;
+  margin-bottom: 16px;
 }

 .hero-intro .lead {
  max-width: 32em;
-  margin-bottom: 26px;
+  margin-bottom: 28px;
+}
+
+/* 首屏按钮比站内其它按钮大一档 —— 它是这一页的主行动点 */
+.hero-intro .actions .btn {
+  padding: 15px 26px;
+  font-size: 0.95rem;
+}
+
+/* 平台 / 支持情况那一行小标签（对应 ClassIsland 首屏底部那句「支持在 Windows…」）。
+   做成 mono 的芯片而不是一句话：这行是要被扫一眼的，不是要被读的。 */
+.hero-badges {
+  list-style: none;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  margin-top: 22px;
+}
+
+.hero-badges li {
+  font-family: var(--mono);
+  font-size: var(--fs-xs);
+  line-height: 1.6;
+  padding: 4px 11px;
+  border: 1px solid var(--board-line);
+  border-radius: 999px;
+  color: var(--chalk-2);
+}
+
+/* 第一个是版本号：当前这一版是什么，比平台支持更需要一眼看到 */
+.hero-badges li:first-child {
+  border-color: var(--blue);
+  color: var(--chalk);
 }

 /* ── 首屏入场：照着 ClassIsland 的 .intro-seq 写（逐项 0.72s EASE_OUT + 错峰延迟）。
@@ -54,6 +54,7 @@
          <a href="#shots">实机</a>
          <a href="#deploy">部署</a>
          <a href="#verify">验收</a>
+          <a href="docs/index.html">文档站</a>
        </nav>
        <a class="btn btn-quiet" href="#deploy" data-press="0.95">取安装包</a>
      </div>
@@ -68,7 +69,7 @@
          <div class="hero-intro">
            <h1 class="display" data-reveal>
              <span class="reveal-line">它知道现在是第几节课，</span>
-              <span class="reveal-line">所以不会在课上打扰学生。</span>
+              <span class="reveal-line reveal-grad">不会在课上打扰学生</span>
            </h1>

            <p class="hero-sub intro-seq" style="--intro-delay: 150ms">课表、作业、通知、成绩、叫人</p>
@@ -79,9 +80,24 @@
            </p>

            <div class="actions intro-seq" style="--intro-delay: 250ms">
-              <a class="btn btn-solid" href="#deploy" data-press="0.93">下载与部署</a>
-              <a class="btn btn-line" href="#journey" data-press="0.93">先看它怎么工作</a>
+              <a class="btn btn-solid" href="#deploy" data-press="0.93">立即下载</a>
+              <a
+                class="btn btn-line"
+                href="https://github.com/LoveChengke/ClassHelper"
+                target="_blank"
+                rel="noreferrer"
+                data-press="0.93"
+              >
+                GitHub 仓库
+              </a>
            </div>
+
+            <ul class="hero-badges intro-seq" style="--intro-delay: 300ms">
+              <li>v1.1.2</li>
+              <li>Windows 10/11</li>
+              <li>Linux · Docker</li>
+              <li>触摸屏可用</li>
+            </ul>
          </div>

          <div
@@ -649,27 +665,10 @@
        </div>
        <nav class="foot-nav" aria-label="相关链接">
          <a href="https://github.com/LoveChengke/ClassHelper" target="_blank" rel="noreferrer">源码仓库</a>
-          <a
-            href="https://github.com/LoveChengke/ClassHelper/blob/master/docs/production.md"
-            target="_blank"
-            rel="noreferrer"
-          >
-            生产部署
-          </a>
-          <a
-            href="https://github.com/LoveChengke/ClassHelper/blob/master/docs/linux-deploy.md"
-            target="_blank"
-            rel="noreferrer"
-          >
-            Linux 运维
-          </a>
-          <a
-            href="https://github.com/LoveChengke/ClassHelper/blob/master/docs/mysql.md"
-            target="_blank"
-            rel="noreferrer"
-          >
-            切换 MySQL
-          </a>
+          <a href="docs/index.html">文档站</a>
+          <a href="docs/management/production.html">生产部署</a>
+          <a href="docs/management/linux-deploy.html">Linux 运维</a>
+          <a href="docs/management/mysql.html">切换 MySQL</a>
          <a href="https://classisland.tech" target="_blank" rel="noreferrer">ClassIsland</a>
        </nav>
      </div>
@@ -1,9 +1,13 @@
 /**
 * 官网本地预览用的最小静态服务器 —— 只是为了 `node serve.mjs` 能直接看页面。
- * 正式发布时把 website/ 整个目录丢给任意静态托管 / Nginx 即可，不需要这个文件。
+ * 正式发布时把 website/ 与 docs/_site/ 一起交给静态托管即可，不需要这个文件。
 *
 *   node website/serve.mjs          → http://127.0.0.1:5180
 *   PORT=8080 node website/serve.mjs
+ *
+ * 线上两者是同一个 GitHub Pages 站点：官网在根，文档站在 /docs/ 下（见 .github/workflows/pages.yml）。
+ * 这里把 docs/_site 挂到 /docs/ 就是为了让本地与线上同形 —— 否则页脚那几个「文档站」链接
+ * 在本地全是 404。文档站没构建过时 /docs/ 会 404，先跑一次 `pnpm docs:build`。
 */

 import { createServer } from 'node:http';
@@ -12,27 +16,36 @@ import { extname, join, normalize, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';

 const ROOT = resolve(fileURLToPath(new URL('.', import.meta.url)));
+const DOCS_ROOT = resolve(ROOT, '..', 'docs', '_site');
 const PORT = Number(process.env.PORT ?? 5180);

 const MIME = {
  '.html': 'text/html; charset=utf-8',
  '.css': 'text/css; charset=utf-8',
  '.js': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
  '.png': 'image/png',
  '.jpg': 'image/jpeg',
  '.svg': 'image/svg+xml',
  '.ico': 'image/x-icon',
  '.webmanifest': 'application/manifest+json',
+  '.woff': 'font/woff',
  '.woff2': 'font/woff2',
+  '.map': 'application/json',
 };

 const server = createServer(async (request, response) => {
  const url = new URL(request.url ?? '/', 'http://localhost');
  const requested = decodeURIComponent(url.pathname);
-  const target = normalize(join(ROOT, requested === '/' ? 'index.html' : requested));

-  // 目录穿越防护：解析结果必须仍在 ROOT 里
-  if (target !== ROOT && !target.startsWith(ROOT + sep)) {
+  // 文档站挂在 /docs/ 下（线上也是这样）
+  const underDocs = requested === '/docs' || requested.startsWith('/docs/');
+  const base = underDocs ? DOCS_ROOT : ROOT;
+  const relative = underDocs ? requested.replace(/^\/docs\/?/, '/') : requested;
+  const target = normalize(join(base, relative === '/' ? 'index.html' : relative));
+
+  // 目录穿越防护：解析结果必须仍在它所属的根里
+  if (target !== base && !target.startsWith(base + sep)) {
    response.writeHead(403).end('Forbidden');
    return;
  }
@@ -47,10 +60,18 @@ const server = createServer(async (request, response) => {
    });
    response.end(body);
  } catch {
+    if (underDocs) {
+      response
+        .writeHead(404, { 'content-type': 'text/html; charset=utf-8' })
+        .end(
+          '<p style="font:16px/1.7 system-ui;padding:40px">文档站还没构建。先跑一次 <code>pnpm docs:build</code>。</p>',
+        );
+      return;
+    }
    response.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' }).end('404');
  }
 });

 server.listen(PORT, '127.0.0.1', () => {
-  console.log(`官网预览：http://127.0.0.1:${PORT}`);
+  console.log(`官网预览：http://127.0.0.1:${PORT}（文档站在 /docs/）`);
 });