Skip to main content

Docs Vite To Docusaurus 中文适配设计

日期： 2026-04-21

目标： 以 docs-vite/docs 为唯一内容基线，将现有 Docusaurus 站点改造成以中文为默认语言的新版本开发者文档站，并为后续繁体中文与英文生成保留稳定的路径和结构。

背景​

当前仓库中存在两套文档：

  • docs-vite/docs：VitePress 版本，新版开发者文档内容，中文主写
  • docs/：Docusaurus 版本，当前以英文为默认内容源，并通过 i18n/zh-CN、i18n/zh-TW 维护翻译层

本次目标不是继续维护这两套结构，而是将 Docusaurus 站点的内容与信息架构完全切换到 docs-vite/docs 的新版模型。

决策结论​

1. 中文作为新的默认基线​

  • docs/ 不再承载英文主源，而是改为新版中文主内容
  • Docusaurus 默认语言切换为 zh-CN
  • 当前阶段只先交付中文一致版本
  • 繁体中文与英文后续基于本次稳定下来的中文路径生成

2. 信息架构完全以 docs-vite 为准​

  • 页面集合、栏目结构、导航顺序、首页内容全部以 docs-vite/docs 为准
  • 旧版 Docusaurus 中已不再存在于 docs-vite/docs 的页面视为淘汰页面
  • 淘汰页面不再出现在导航和侧边栏中，只保留跳转兼容

3. 迁移方式采用“源镜像迁移”​

  • 将 docs-vite/docs/**/*.md 作为唯一正文来源
  • 在 docs/ 中按等价路径重建页面内容
  • 对不兼容的链接、frontmatter 和目录入口方式做 Docusaurus 适配

目标结构​

迁移完成后，Docusaurus 内容结构应与 docs-vite/docs 对齐。

保留并重写的主要栏目​

  • docs/index.md
  • docs/widget/*
  • docs/chat-page/*
  • docs/webhooks/*
  • docs/api/*

新增页面​

  • docs/widget/examples.md
  • docs/chat-page/webview-appbridge.md

删除正文但保留兼容跳转的页面​

  • docs/widget/configuration.md
  • docs/guide/README.md
  • docs/guide/quickstart.md

目录入口语义调整​

docs-vite 使用 index.md 作为目录首页，Docusaurus 当前大量使用 README.md。迁移后对外路径需与新版保持一致：

  • /widget/
  • /chat-page/
  • /webhooks/
  • /api/

内部可根据 Docusaurus 更稳定的实现方式选择 index.md、目录首页文档或显式 slug，但最终 URL 必须与新版一致。

页面映射规则​

内容源范围​

仅使用以下内容作为正文来源：

  • docs-vite/docs/**/*.md

以下目录不作为正文来源：

  • docs-vite/docs/.vitepress/
  • docs-vite/dist/
  • docs-vite/docs/.vitepress/dist/
  • docs-vite/docs/.vitepress/cache/

静态资源规则​

  • 仅在 Markdown 正文直接引用资源时再单独搬运
  • docs-vite/docs/public/ 中的静态资源需要评估是否同步到 Docusaurus 的 static/ 目录
  • 未被文档引用的 VitePress 运行时资源不迁移

Markdown 适配规则​

  • 保留原有标题层级、表格、代码块和提示框语义
  • 将 docs-vite 中的内链写法统一改为 Docusaurus 可解析的相对链接或 canonical path
  • 所有内链以新版路径为准，不再继续引用旧 guide/* 或已淘汰页面
  • 如存在仅适用于 VitePress 的语法，需转换为 Docusaurus MDX 兼容写法

导航与站点配置​

sidebars.ts 需要完全按 docs-vite/docs/.vitepress/config.ts 的 sidebar 顺序重写，包含：

  1. 介绍
  2. 网站小部件
    • 快速接入
    • JavaScript API
    • 示例项目
  3. 聊天页面
    • 直接链接
    • 自托管部署
    • URL 参数说明
    • APP 嵌入访客端 WebView
  4. Webhooks
    • 配置指南
    • 签名校验
    • 事件类型
    • 事件负载
  5. 开放 API
    • 鉴权与签名
    • 在线聊天
      • 创建单聊
      • 批量创建单聊
      • 创建群组
      • 删除单聊
      • 解散群组
      • 批量解散群组
    • 错误码参考

站点导航与页脚应同步切换为中文语义，并删去对旧 Guide 模型的依赖：

  • 默认入口指向中文首页
  • 主导航只保留与新版结构一致的入口
  • 页脚链接需同步更新到新版栏目首页

多语言策略​

本阶段​

  • 默认语言切换为 zh-CN
  • 本阶段不对外暴露旧英文与繁体中文残留结构
  • 旧的 i18n/zh-CN、i18n/zh-TW 内容不作为当前正文来源

后续阶段​

  • 在中文主路径与 doc id 稳定后，再基于 docs/ 生成繁体中文与英文版本
  • 多语言生成应遵循“同路径翻译”，而不是再次调整结构

路由兼容策略​

迁移会删除旧页面，因此需要补充跳转兼容，避免历史链接直接失效。

兼容原则​

  • 被移除的旧页面应重定向到语义最接近的新页面
  • 历史语言前缀路径应能够回落到当前中文主路径

典型跳转​

  • guide/README / guide/quickstart -> 新首页或最接近的新版起始页
  • widget/configuration -> widget/javascript-api 或 widget/examples，以最终内容映射最贴近者为准
  • 旧 zh-CN 前缀路径 -> 无语言前缀的中文 canonical path

具体跳转规则将在实施阶段落实到 Docusaurus redirects 配置中。

内容迁移边界​

本次必须完成​

  • 中文首页适配
  • 四个主栏目首页适配
  • 所有 docs-vite/docs 中存在的中文页面迁移到 docs/
  • Docusaurus 配置切换到中文默认站点
  • 新版 sidebar/nav/footer 落地
  • 旧页面的核心跳转兼容

本次不做​

  • 繁体中文正文生成
  • 英文正文生成
  • 视觉层面的深度重构
  • 对 docs-vite 本身进行反向修订

风险与约束​

风险​

  • Docusaurus 默认语言切换后，历史 locale 路由可能出现不一致，需要明确 redirect
  • 旧 README.md 目录入口与新版 index.md 语义不同，需谨慎处理 doc id 与 URL
  • 旧翻译目录在本阶段若仍被构建引用，可能造成 broken links 或重复内容

约束​

  • 内容以 docs-vite/docs 为准，不做主观扩写
  • 不回退到旧英文结构
  • 不保留已淘汰页面作为正文页面

验收标准​

结构验收​

  • docs/ 页面集合与 docs-vite/docs/**/*.md 页面集合一致
  • docs-vite 中新增的 widget/examples、chat-page/webview-appbridge 已落地
  • 旧 guide/* 与 widget/configuration 不再出现在导航中

内容验收​

抽样核对以下页面与 docs-vite 内容一致：

  • 首页
  • widget/index
  • widget/installation
  • widget/examples
  • chat-page/webview-appbridge
  • webhooks/index
  • api/index

构建验收​

  • docusaurus build 通过
  • 无 broken links
  • 无 broken markdown links

路由验收​

  • /widget/、/chat-page/、/webhooks/、/api/ 等新版路径可正常访问
  • 旧淘汰页面不会直接 404，而是命中重定向

实施输出​

实施阶段将基于本设计产出一份明确的执行计划，包含：

  • 需要修改和删除的具体文件
  • 逐页迁移清单
  • Docusaurus 配置变更清单
  • 跳转兼容清单
  • 构建验证步骤