ZZufyUI文档首页DocumentationДокументацияDokumentationDocumentationDocumentación

正在准备文档Preparing your docsПодготовка документацииDokumentation wird geladenPréparation de la documentationPreparando la documentación

Language

Maintenance / v1.29.1

Documentation builds

Download Markdown

This document is shown in Chinese.

站点构建只生成静态产物,不发布网站。所有平台使用同一入口:在 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 容器。任务从仓库根目录执行:
cd docs-site
bun install --frozen-lockfile
bun run ci
  1. 配置制品收集目录为仓库根目录下 docs-site/out/,保留目录结构;不添加部署任务。
  2. 手动运行一次确认成功,再通过一次推送验证触发。流水线配额、环境镜像和可用插件取决于账户配置。

官方说明:流水线介绍、创建流水线、触发运行。本次本地生成不启用账户服务、不消耗云端构建额度。

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):

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 文件。

View sourcedocs/site-ci.md