开发工具CLIAI 应用【免费下载链接】zcfZero-Config Code Flow for Claude code Codex项目地址https://gitcode.com/gh_mirrors/zc/zcf点击查看免费下载本篇技术指南完整还原 ZCFZero-Config Code Flow项目文档站由 GitBook 结构迁移至 VitePress 的全过程。ZCF 的官方文档此前采用 GitBook 多语言目录SUMMARY.md组织迁移后已由 VitePress 接管为支持 en / zh-CN / ja-JP 三语、内置本地搜索、暗色模式与 GitHub Pages 自动部署的静态站点。阅读完本文你将掌握 VitePress 多语言站点的骨架设计locales、nav、sidebar、基于导航定义批量生成侧边栏的工程化手法、UnoCSS 主题定制以及 GitHub Actions 部署流水线的完整落地方式并可把同一套方案复用到自己的文档项目中。迁移背景与目标迁移计划记录于仓库 .zcf/plan/history/docs-vitepress-migration.md核心背景与约束如下旧结构基于 GitBook以多语言目录 SUMMARY.md组织章节每门语言一套文件树目标站点框架为 VitePress配置模式参考 unocss/docs必须包含国际化默认语言 en、主内容 zh-CN、ja-JP 为壳占位支持搜索、暗色模式、GitHub 链接部署方式复制 unocss 的 GitHub Pages 脚本实际落地为.github/workflows/docs-deploy.yml。对应到当前仓库迁移后的目录布局为docs/ ├── .vitepress/ # VitePress 核心配置与主题 │ ├── config.ts │ └── theme/ ├── CNAME # 自定义域名 ├── index.md # 根入口跳转 /en/ ├── package.json # docs 包脚本与依赖 ├── uno.config.ts # UnoCSS 配置 ├── tsconfig.json ├── en/ # 英文默认语言 ├── zh-CN/ # 简体中文主内容 ├── ja-JP/ # 日语壳 └── public/assets/ # favicon 等静态资源迁移执行的六个阶段原计划将整个迁移拆成六个可独立验证的步骤当前仓库均已落地计划文档中以 ✅ 标记完成整理 GitBook 导航读取docs/{en,zh-CN,ja-JP}/SUMMARY.md抽取章节结构记录成导航映射分析 unocss 配置阅读 unocss/docs 的config、vite.config.ts等列出需要复制的模块与依赖初始化 VitePress 目录在docs/.vitepress/下创建config.ts及相关 theme、locale 配置迁移导航与内容将导航映射到 VitePress 的locales、nav、sidebar保证 zh-CN 完整、en/ja-JP 占位部署脚本同步新增 GitHub Pages 工作流.github/workflows/docs-deploy.yml以pnpm docs:build产出静态站点并部署验证运行pnpm docs:build构建通过。下面按阶段深入拆解每一环的落地细节与源码实现。阶段一导航结构与 SUMMARY 解析GitBook 时代的信息架构沉淀在三份语言各自的SUMMARY.md中例如 docs/en/SUMMARY.md 将文档划分为七个章节Getting Started、Features、Advanced Guides、CLI Commands、Workflow Details、Best Practices、Development Documentation。zh-CN 与 ja-JP 目录下存在结构等价、标题翻译不同的同构文件。这份章节映射正是 VitePresssidebar的天然输入。迁移的关键在于把SUMMARY 式的平铺目录重写为 VitePress 面向路由前缀/en/、/zh-CN/、/ja-JP/的侧边栏数据结构同时把每篇 Markdown 的相对链接例如getting-started/installation.md换算为以语言前缀开头的路由路径。阶段二与三VitePress 目录初始化与依赖装配迁移后的文档站是一个独立的 pnpm workspace 子包见 docs/package.json{ name: zcf/docs, type: module, private: true, scripts: { dev: vitepress dev --port 3366, build: vitepress build, preview: vitepress preview }, dependencies: { iconify-json/carbon: catalog:docs, unocss/reset: catalog:docs, unocss: catalog:docs, vitepress: catalog:docs, vue: catalog:docs } }几个值得注意的工程细节固定开发端口vitepress dev --port 3366将本地开发服务固定到 3366 端口避免多人开发时端口冲突依赖走 workspace catalogcatalog:docs说明版本统一收敛在根 pnpm-workspace.yaml 的 catalog 中文档站与 CLI 主体共享版本管理策略依赖组合vitepressvueunocssunocss/reseticonify-json/carbon图标集供主题内i-carbon-close之类的图标类使用构成站点运行时底座。VitePress 需要一个 TypeScript 工程来支撑.vitepress下的源码docs/tsconfig.json 采用moduleResolution: bundler、noEmit: true并将include指向.vitepress/**/*与页面源码保证config.ts与 Vue 组件在编辑器内获得完整类型检查。阶段三核心多语言配置与侧边栏生成器站点中枢是 docs/.vitepress/config.ts它以defineConfig声明了站点标题、描述、srcDir: .、lang: en-US、lastUpdated与cleanUrls: true并通过head注入 faviconexport default defineConfig({ title: siteTitle, description: siteDescription, srcDir: ., lang: en-US, lastUpdated: true, cleanUrls: true, head: [ [link, { rel: icon, type: image/x-icon, href: /assets/favicon.ico }], ], vite: { plugins: [UnoCSS()], }, // ... })createSidebar把章节定义批量转成侧边栏为避免手工维护上百条侧边栏项config.ts 定义了一个createSidebar工厂函数对应源码 docs/.vitepress/config.ts#L19-L42function createSidebar(definition: SidebarDefinitionSection[], base: string): DefaultTheme.SidebarItem[] { const normalizedBase base.endsWith(/) ? base : ${base}/ return definition.map(section ({ text: section.text, collapsed: false, items: section.items.map((item) { let link item.link if (!link) { link normalizedBase } else if (link index) { link normalizedBase } else if (!link.startsWith(/)) { link ${normalizedBase}${link} } return { text: item.text, link } }), })) }它的核心价值在于路径归一化空链接与index都指向语言根如/zh-CN/天然兼容xxx/index.md这类目录入口未以/开头的相对链接自动拼接语言前缀如getting-started/installation→/zh-CN/getting-started/installation以/开头的绝对链接原样保留允许跨语言引用。这意味着三份侧边栏只需描述章节 → 条目 → 短链接的数据路径细节全部由工厂统一计算迁移后若要调整目录结构只需改一处定义。三语侧边栏与 locales 体系config.ts 中依次构建了zhSidebar、enSidebar、jaSidebar三份数据分别以/zh-CN、/en、/ja-JP为 base。以 zh-CN 为例其章节覆盖项目介绍 / 开始使用 / 功能特性 / 进阶指南 / CLI 命令 / 工作流详解 / 最佳实践 / 开发文档八大区块源码 docs/.vitepress/config.ts#L44-L126且与 en / ja-JP 保持条目级一一对应——这正是en 默认、zh-CN 主内容、ja-JP 壳结构的导航载体。顶级themeConfig与locales分工如下themeConfig.search.provider local启用 VitePress 内置本地全文搜索无需外部搜索服务离线即可构建源码 docs/.vitepress/config.ts#L314-L316socialLinks与editLink提供 GitHub 仓库链接与Edit this page on GitHub编辑入口满足计划中GitHub 链接的硬性要求nav在每个 locale 内分别定义如 en 的 Home / Getting Started / Features / CLI / Workflows / Best Practices并随语言切换而本地化每个 locale 配置自己的sidebar、footer文案与editLink文本zh-CN 为在 GitHub 上编辑此页ja-JP 为GitHubでこのページを編集。根入口 docs/index.md 使用layout: home配合useRouter().go(/en/)在挂载后重定向到英文默认首页实现默认 en的语言兜底。阶段三延伸UnoCSS 主题定制站点主题位于 docs/.vitepress/theme/index.ts它继承 VitePress 默认主题并注入自定义布局import uno.css import unocss/reset/tailwind.css import ./custom.css export default { extends: DefaultTheme, Layout: () { return h(DefaultTheme.Layout, null, { layout-top: () h(TopBanner), }) }, } satisfies Theme要点UnoCSS 原子化样式import uno.css引入 UnoCSS 运行时产物配合根级 docs/uno.config.ts 的三个预设presetWind3()Wind3 工具类、presetAttributify()属性化写法、presetIcons()图标类Markdown 与 Vue 组件内可直接使用fixed top-0 z-200等原子类与i-carbon-close图标类布局插槽扩展通过 VitePress 布局插槽layout-top在页面顶部挂载 TopBanner.vue实现一个可关闭、按语言切换内容的顶部推广横幅组件借助useData().lang响应式读取当前语言并为zh-CN / en / ja-JP分别维护文案映射关闭时通过document.documentElement.classList增减has-top-banner以联动custom.css中的页面偏移样式。暗色模式由 VitePress 默认主题原生提供跟随系统或手动切换custom.css中针对明暗双态补充了定制样式无需额外依赖。阶段五GitHub Pages 部署流水线部署部分完全对齐复制 unocss 的 GitHub Pages 脚本的目标落地为 .github/workflows/docs-deploy.yml。工作流在main分支 push 时触发同时支持workflow_dispatch手动触发采用build deploy 双 Job结构permissions: contents: read pages: write id-token: write concurrency: group: docs-deploy cancel-in-progress: true jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: pnpm/action-setupv4 - uses: actions/setup-nodev4 with: cache: pnpm - run: pnpm install --frozen-lockfile - run: pnpm -F zcf/docs build # 构建 docs 子包 - uses: actions/upload-pages-artifactv3 with: path: docs/.vitepress/dist deploy: needs: build runs-on: ubuntu-latest environment: name: github-pages steps: - uses: actions/deploy-pagesv4工程化细节包括工作区过滤构建pnpm -F zcf/docs build只构建 docs 子包避免在文档发布时编译整个 CLI 工程锁文件保证可复现pnpm install --frozen-lockfile严格按 pnpm-lock.yaml 安装杜绝 CI 与本地依赖漂移Pages 权限模型pages: writeid-token: write是 GitHub Actions 原生 Pages 部署deploy-pages的必要权限组合并发保护concurrency.group: docs-deploy保证同一时间只有一个文档发布任务cancel-in-progress: true使新推送自动取消排队中的旧构建产物路径上传docs/.vitepress/dist即 VitePress 的默认构建输出目录。配套的 docs/CNAME 内容为zcf.ufomiao.com为 GitHub Pages 站点绑定自定义域名。仓库同时保留 .github/workflows/ci.yml 与 .github/workflows/release.yml分别承担主工程 CI 与发布任务与文档部署互不干扰。阶段六本地构建与验证验证迁移是否成功只需在仓库根目录执行# 本地开发固定 3366 端口 pnpm -F zcf/docs dev # 生产构建输出到 docs/.vitepress/dist pnpm -F zcf/docs build # 本地预览构建产物 pnpm -F zcf/docs preview计划文档中明确以pnpm docs:build构建通过作为阶段六的完成判据在当前仓库中该命令等价于通过 workspace filter 执行zcf/docs包的build脚本。构建通过即意味着三份语言侧边栏定义与全部 Markdown 路径均能解析不存在死链路由locales配置通过 VitePress 的 locale 校验UnoCSS 与主题组件编译无类型错误受 docs/tsconfig.json 严格模式约束。迁移方案要点总结回顾这次 GitBook → VitePress 迁移可以提炼出几条可复用的经验以数据驱动导航createSidebar(definition, base)把目录结构降维成纯数据语言前缀拼接逻辑收敛在工厂内是本次多语言站点最关键的抽象三语同构、一主两壳en / zh-CN / ja-JP 三份 sidebar 条目完全对齐zh-CN 承载完整内容ja-JP 保持占位保证了未来补全翻译时不会破坏导航结构本地搜索优先search.provider: local让全文搜索随构建产物一起离线可用省去外部搜索索引服务原子化样式与主题定制解耦UnoCSS 负责工具类与图标VitePress 布局插槽负责扩展点TopBanner通过useData().lang响应式做多语言内容分发部署流水线独立化文档发布作为独立子包构建 GitHub Pages 原生部署与主工程 CI/发布流程解耦--frozen-lockfile与并发组保证发布可复现、不堆积。相关实现文件一览多语言配置与侧边栏生成器见 docs/.vitepress/config.ts主题扩展见 docs/.vitepress/theme/index.ts部署流水线见 .github/workflows/docs-deploy.yml迁移执行记录见 .zcf/plan/history/docs-vitepress-migration.md。赞分享开发工具CLIAI 应用【免费下载链接】zcfZero-Config Code Flow for Claude code Codex项目地址https://gitcode.com/gh_mirrors/zc/zcf点击查看免费下载相关推荐Motion 动画库帧循环调度修复让 cancelFrame 对同帧同 Step 内已入队回调即时生效Motion 动画库帧循环调度修复让 cancelFrame 对同帧同 Step 内已入队回调即时生效 本文基于 Motion 仓库中的实现计划 plans/开发工具CLIAI 应用Astron Agent 文档站 VitePress 迁移与构建发布实战从静态 HTML 到自动化多语言站点Astron Agent 文档站 VitePress 迁移与构建发布实战从静态 HTML 到自动化多语言站点 本篇技术指南以仓库内 docs/faq.md h人工智能AI AgentAgent 编排RPA后端前端企业应用asdf 文档站点贡献指南VitePress 多语言文档站的构建与国际化实践asdf 文档站点贡献指南VitePress 多语言文档站的构建与国际化实践 本文围绕 asdf 项目的官方文档站点 docs/ 目录展开讲解如何为文档CLI开发工具上一篇如何在Windows 11 LTSC 24H2中一键恢复Microsoft Store完整终极指南下一篇终极指南3步实现CAJ到PDF的专业转换彻底告别知网格式限制创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考