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

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

Language

Maintenance / v1.29.1

Static documentation site

Download Markdown

This document is shown in Chinese.

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。

View sourcedocs-site/README.md