# ZufyUI 静态文档站

Next.js App Router + React + TypeScript。正文在构建时读取仓库 Markdown，导出独立 HTML；导航、目录和搜索索引随站点一起交付，不使用文档后端。

## 本地运行

安装 Bun 1.4.5，在本目录运行：

```sh
bun install --frozen-lockfile
bun run dev
```

开发地址 `http://127.0.0.1:4317`。文档源变化由开发监听器自动重新生成；页面源码由 Next.js 热更新。

## 构建与预览

```sh
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) 与 [模块索引](../docs/ai/LLM.MD) 是维护的分层指引。构建自动生成 `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 分发；打包命令见[流水线说明](../docs/site-ci.md)。

Gitee 仓库需在 Gitee Go 中启用代码推送触发，并使用该构建命令；具体接入步骤见 [流水线说明](../docs/site-ci.md)。仓库中的配置与脚本不会自行启用平台服务。

## 字体与资源

MiSans 字体来自小米，遵循《MiSans 字体知识产权许可协议》；分片发行工具来自 `dsrkafuu/misans`，其脚本为 Apache-2.0。构建保留包说明、脚本许可及字体协议链接在 `/fonts/`。框架源文档的授权和第三方声明见 [THIRD_PARTY_NOTICES](../THIRD_PARTY_NOTICES.md)。
