# 文档自动构建

站点构建只生成静态产物，不发布网站。所有平台使用同一入口：在 `docs-site/` 运行 `bun run ci`。每次构建重新读取仓库源文档，生成页面、搜索数据、版本、原文下载与 AI 快照。

## Gitee 流水线

Gitee 当前帮助文档描述的是通过 UI 编排流水线。仓库中的 `.github/workflows/docs.yml` 不会在 Gitee 自动执行，也不代表已经开通 Gitee 流水线。

在有流水线权限的 Gitee 项目中配置：

1. 创建流水线，输入源选择本仓库，分支选择 `main`；如需要对贡献分支构建，增加对应分支条件。
2. 触发条件选择代码变更 / Push。文档、站点源码、图片或 `ZufyUIVersion.h` 变化时需要构建；也可对所有推送触发。
3. 构建任务选支持 Bun 1.4.5 的 Linux 环境，例如预装该版本的执行机或 `oven/bun:1.4.5` 容器。任务从仓库根目录执行：

```sh
cd docs-site
bun install --frozen-lockfile
bun run ci
```

4. 配置制品收集目录为仓库根目录下 `docs-site/out/`，保留目录结构；不添加部署任务。
5. 手动运行一次确认成功，再通过一次推送验证触发。流水线配额、环境镜像和可用插件取决于账户配置。

官方说明：[流水线介绍](https://help.gitee.com/enterprise/pipeline/introduce)、[创建流水线](https://help.gitee.com/enterprise/pipeline/create)、[触发运行](https://help.gitee.com/enterprise/pipeline/pipeline/trigger)。本次本地生成不启用账户服务、不消耗云端构建额度。

## GitHub 镜像

仓库附带 `.github/workflows/docs.yml`。代码存在于 GitHub 且 Actions 已启用时，文档或站点相关的 Push / PR 会运行构建；也可手动触发。成功后下载 `zufyui-docs-static` 制品，保留 14 天。工作流只有读取仓库和上传制品步骤，没有 Pages 部署权限或发布步骤。

Gitee → GitHub 镜像同步需要另外配置；本项目不会暗中复制仓库或创建镜像。

## 本地内容自动更新

`bun run dev` 监听 Markdown 和版本文件变化，自动重新生成内容快照；Next.js 对界面源码热更新。若生成失败，终端显示错误，修正源文件后自动重试。

## 验收入口

- `bun run check`：内容覆盖、内部目标、资源和 TypeScript。
- `bun test`：章节映射、AI 文档链接、旧格式转换和全文搜索。
- `bun run build`：Next.js 静态导出。
- `bun scripts/verify-export.ts`：每篇正文确实进入 HTML、所有原始下载文件与仓库一致、导航数据的文件名与内容完整。
- `bun run preview`：仅用静态文件服务器检查 `http://127.0.0.1:4318/`。

首次自动构建需平台实际运行成功才能称为已启用。仅提交工作流文件不等同于云端验证通过。

## Release 交付

框架、文档原稿和 `docs-site/` 源码在同一仓库维护。依赖、编译缓存、静态导出和二进制包不提交到源码分支；按 `ZufyUIVersion.h` 的版本将产物上传到 Release。

先完成 Windows x64 Release 构建与自检，以及文档站 `bun run ci`，然后在仓库根目录执行（Python 环境需安装 fonttools 和 Pillow）：

```sh
python tools/package_release.py --out releases/v1.29.1 --docs
```

`--docs` 同时打包 `docs-site/out/`，检查版本并拒绝未归一化的导航文件目录。交付包括 Windows x64 ZIP（Demo、调试器和 Python 调试桥）、独立 `demo.exe`、静态站 ZIP、版本与源码提交清单，以及 SHA-256 校验文件。打包命令不会自行提交、推送或发布；Release 上传由维护者授权执行。

静态 ZIP 解压目录中直接包含 `index.html`。可在解压目录执行 `python -m http.server 4320 --bind 127.0.0.1`，访问 `http://127.0.0.1:4320/zh/`；托管时上传整个解压目录，保留所有 `__next.*.txt` 文件。
