Next.js App Router + React + TypeScript。正文在构建时读取仓库 Markdown,导出独立 HTML;导航、目录和搜索索引随站点一起交付,不使用文档后端。
本地运行
安装 Bun 1.4.5,在本目录运行:
bun install --frozen-lockfile
bun run dev
开发地址 http://127.0.0.1:4317。文档源变化由开发监听器自动重新生成;页面源码由 Next.js 热更新。
构建与预览
bun run check
bun test
bun run build
bun run preview
产物在 docs-site/out/,预览地址 http://127.0.0.1:4318。部署只需静态文件服务器,无需 Node/Bun 服务端。此项目不自动发布公网。
子路径托管时构建前设置 DOCS_BASE_PATH=/ZufyUI(PowerShell:$env:DOCS_BASE_PATH='/ZufyUI');预览服务器会挂载同一路径。不要在构建之后改路径。正式构建和开发预览使用不同输出目录,可同时运行。
内容约定
- 自动收录根目录、
docs/、tools/下的.md(大小写均支持),以及本说明。新增文档无需新建 React 页面。 - 双语 API 的
###chapter:经验证后按稳定路由拆分;原始全文在/raw/docs/src/API.md等地址保留。 - 普通 Markdown、GFM 表格、代码高亮和旧版提示块均支持。原文中的 HTML 经过清理,不执行脚本。
- 中英文 API / README / CHANGELOG 分别提供对应页面;没有译文的维护文档保留原文,界面显示提示。
- 界面支持中文、英语、俄语、德语、法语和西班牙语;翻译集中在
lib/i18n/。新增的四种语言使用英文技术正文,不调用在线翻译服务。 - 本地插图随构建复制;来源中的远程图片仍使用原地址。MiSans VF 从锁定的 npm 包复制到站点,使用 Unicode 分片按需加载。
- 版本从
ZufyUIVersion.h读取;路由冲突、章节映射变化、缺失本地图片会使构建失败。
AI 文档
总入口 与 模块索引 是维护的分层指引。构建自动生成 LLM.MD、llms.txt、llms-full.txt、原始 Markdown 和下载清单。自动生成快照不等于自动核实 API 语义。
阅读体验
- 正文在固定圆角容器内滚动。刷新恢复正文及目录的位置,语言切换保持对应章节位置。
- 桌面侧栏支持收起、展开和拖动宽度;状态与宽度存储在本机。分隔条也支持方向键调整。
- 顶部搜索栏直接输入,结果在下方展开;
Ctrl+K聚焦,方向键选择,Enter 打开,Esc 收起。 - 语言使用原位下拉及本地 SVG 国旗;正文、代码和界面统一使用本地 MiSans VF。
- 站内链接及前后篇章使用客户端导航,复用字体和已加载资源。静态服务器可对带内容哈希的字体和
/_next/static/文件设置一年 immutable 缓存;HTML 应重新验证。 - 图片轻微悬浮放大,点击全屏预览;滚轮缩放、自由拖动、点击图片外的空白关闭。拖动手势不会触发关闭。键盘
+/-缩放、0适应窗口、Esc 关闭。 - 代码块只有内容实际溢出时显示“展开”,可全屏查看与复制;普通代码区域没有整块悬浮样式。
自动构建
运行 bun run ci 完成内容生成、校验、测试、静态导出及产物检查。支持 Linux/Windows,不需要原生 C++ 编译工具链。流水线构建产物为整个 docs-site/out/ 目录。
Next.js 16.4.6 在 Windows 导出导航数据时未正确归一化路径分隔符;patches/next@16.4.6.patch 是针对该外部问题的依赖修复,由 Bun 安装时自动应用。产物检查会逐一比对导航数据文件和构建源数据,防止静态托管时出现 404。
站点源码与框架同仓维护,生成目录和依赖不提交。带版本号的静态 ZIP、Demo 和调试器通过仓库 Release 分发;打包命令见流水线说明。
Gitee 仓库需在 Gitee Go 中启用代码推送触发,并使用该构建命令;具体接入步骤见 流水线说明。仓库中的配置与脚本不会自行启用平台服务。
字体与资源
MiSans 字体来自小米,遵循《MiSans 字体知识产权许可协议》;分片发行工具来自 dsrkafuu/misans,其脚本为 Apache-2.0。构建保留包说明、脚本许可及字体协议链接在 /fonts/。框架源文档的授权和第三方声明见 THIRD_PARTY_NOTICES。