Twenty 文档站迁移 Mintlify 实践：从 twenty-website 到 twenty-docs 的完整落地路径

Twenty 文档站迁移 Mintlify 实践：从 twenty-website 到 twenty-docs 的完整落地路径

【免费下载链接】twentyThe open alternative to Salesforce, designed for AI.项目地址: https://gitcode.com/GitHub_Trending/tw/twenty

本文基于 Twenty 仓库中的 MIGRATION.md 展开，完整还原其官方文档站从旧站点（twenty-website）迁移到 Mintlify 独立包packages/twenty-docs的范围、组件转换规则、目录结构、本地验证与部署流程，并结合当前仓库中的 Nx 项目配置、docs.json 与导航生成脚本，深入讲解迁移完成后这套文档工程如何演进为多语言、可校验的持续化文档管线。读完后你将掌握：如何在 Nx monorepo 中托管并本地预览 Mintlify 文档站、如何复现“旧自定义组件 → Mintlify 等价组件”的转换映射，以及文档导航如何由单一基础结构文件自动生成为多语言配置。

一、迁移背景与范围：一次性搬完 69 篇 MDX 与 81 张图

MIGRATION.md 开篇以“Mintlify Migration Summary”的形式记录了这次迁移搬动的全部内容。Twenty 官方文档原先嵌在twenty-website站点中，采用自研 React 组件渲染；迁移后文档独立为仓库内的packages/twenty-docs包，由 Mintlify 托管渲染与部署。迁移范围如下表（数字以迁移文档记录为准）：

类别	数量	说明
MDX 文档文件	69 篇	从 twenty-website 复制到 twenty-docs
用户指南文章	45 篇	面向产品使用者
开发者文档文章	22 篇	面向贡献者与集成开发者
入门指南	2 篇	迁移前已存在
图片与资产	81 张	用户指南截图、开发者文档配图、Logo 与品牌资产

导航结构随内容一并迁移：Mintlify 主配置中包含带 Tab 与嵌套分组的完整导航——迁移时 User Guide 标签页有 11 个分组（section），Developers 标签页有 6 个分组。

从当前仓库结构看，这套内容已经明显“长大”：packages/twenty-docs下的英文 MDX 覆盖getting-started/（11 篇）、developers/（49 篇）、user-guide/（一百余篇，含 Data Model、Data Migration、Workflows 等 15 个主题目录），并且l/目录下沉淀了 12 种语言的翻译副本。这说明迁移是一次“底座铺设”：把内容与导航整体搬入 Mintlify 约定后，后续多语言与内容扩展都建立在这个结构之上。

二、组件转换映射：旧自定义组件如何落到 Mintlify 等价物

旧文档页大量使用自研 React 组件，Mintlify 只提供一套固定组件库，因此迁移的核心工作之一是逐类替换。MIGRATION.md 给出的转换规则与后续人工复核清单如下：

已完成的机械替换

旧组件	迁移方式
<ArticleWarning>	替换为 Mintlify 的<Warning>提示组件
<ArticleLink href="...">text</ArticleLink>	降级为原生 Markdown 链接text
<ArticleEditContent>	直接删除（Mintlify 侧无需对应物）

需要人工复核的部分

• <ArticleTabs>：Mintlify 的对应组件是<Tabs>，需逐页转换；
• 嵌入式 iframe / 视频：可能需要调整实现方式；
• 自定义样式元素：需逐一检查 Mintlify 兼容性。

对于“视频嵌入”这一已知难点，仓库中的实际答案是保留了一个可复用的 MDX 片段 snippets/vimeo-embed.mdx：它导出一个VimeoEmbed组件，内部用 69.01% 的 padding-top 撑出 16:9 比例的容器，通过 iframe 内嵌player.vimeo.com播放地址并开启autoplay/loop参数。文档页引入该片段即可替代原站点的视频组件——这正是迁移文档中“Embedded iframes/videos - May need adjustment”一条的最终落点。

三、迁移后的目录结构：从 Mintlify 约定到实际仓库

MIGRATION.md 记录的迁移期目录结构如下（原样保留，便于对照迁移意图）：

packages/twenty-docs/ ├── mint.json # 主配置 ├── user-guide/ │ ├── getting-started/ # 7 文件 │ ├──>npx nx run twenty-docs:dev

这个命令的实际执行链路可以在 project.json 中完整核对：dev目标使用nx:run-commands执行器，以包目录为工作目录运行mintlify dev；同文件还定义了另外四个目标，构成完整的本地验证矩阵：

• dev：mintlify dev，启动开发服务器（默认 http://localhost:3000）；
• validate：mintlify validate，校验文档构建是否合法，对应根目录命令npx nx run twenty-docs:validate；
• lint：先跑npx oxlint -c .oxlintrc.json .（通用 TS/JS 规则），再跑npx tsx scripts/lint-mdx.ts（MDX 专用规则），串行执行；
• test：npx vitest run --config vitest.config.mts，用于脚本层单测；
• fmt：Prettier 检查/修复，带缓存目录。

运行前提也写得很明确：package.json 声明engines为 Node^24.5.0、Yarn^4.0.2（npm字段为please-use-yarn，即强制 Yarn），mintlify依赖版本锁定在^4.2.790。复现迁移文档的验证步骤时，应使用仓库统一的 Yarn 工作区环境，而不是单独npm install。

五、部署流程：仓库即文档源

MIGRATION.md 的 Deployment 章节给出了四步上线流程，核心思想是“文档以仓库文件为唯一事实来源，Mintlify 只负责拉取与构建”：

1. 将变更推送到代码仓库；
2. 在 Mintlify 控制台关联该仓库；
3. 将子目录（subdirectory）设置为packages/twenty-docs——即 Mintlify 不会构建整个 monorepo，只以该包为文档根；
4. 之后 Mintlify 在检测到变更时自动部署，并自动生成搜索 embeddings。

这套“子目录 + 自动部署”模式与仓库内的工程配置互相印证：docs.json 中配置了 SEO canonical 指向线上文档域名，意味着自动部署后的页面会声明规范链接；而本地validate目标正是上线前对同一份配置做静态校验的对应手段。

六、迁移完成后的演进：导航从手写 JSON 变成生成管线

MIGRATION.md 在 Status 一节宣布迁移完成：旧的文档载体被移除，文档此后全部存放在packages/twenty-docs。（从当前源码结构看，packages/twenty-website包仍然存在，但从其 package.json 看它现在是基于 Next.js 的营销站点，不再承担文档职责——可以推断迁移文档所指的“removed”是旧版内嵌文档的 website 形态，而非当前这个营销站点目录。）

迁移完成后，docs.json没有停留在手写状态，而是长出了一条“基础结构 + 翻译标签 → 生成”的管线，这是理解当前文档站导航的关键：

导航事实来源与生成脚本

• navigation/base-structure.json：唯一的事实来源（source of truth），只含英文标签与页面 slug，按tabs → groups → pages三级组织，且支持分组嵌套（如 Workflows 的 How-Tos 下再分 CRM Automations / Connect to Other Tools / Advanced Configurations / Need More Help 四个子组）。按 README 说明，该文件不上传翻译平台。
• scripts/generate-docs-json.ts：读取 base-structure，并为每种支持语言加载l/<language>/navigation.json中的标签映射，最终把结果写回docs.json的navigation.languages。语言清单由 navigation/supported-languages.ts 从 twenty-shared 的DOCUMENTATION_SUPPORTED_LANGUAGES常量复用而来，保证文档站语言列表与产品常量同源。
• 根目录通过 package.json 暴露为yarn docs:generate与yarn docs:generate-navigation-template两个命令，对应上述脚本。

生成逻辑里有一段值得注意的工程约束（generate-docs-json.ts 的源码注释）：Mintlify 要求每个页面路径只能出现在一种语言的导航里，否则语言切换器无法解析等价页面、会回退到第一篇页面。因此脚本只在l/<lang>/<slug>.mdx真实存在时才把该页面挂进对应语言（见formatPageSlug，第 156–164 行），空的分组与 Tab 会被整体丢弃。这就是l/目录中每种语言恰好是 117 篇 user-guide + 74 篇 developers + 11 篇 getting-started 的由来——翻译缺口的页面会自动从该语言导航中消失，而不是渲染出死链。

MDX 质量门禁：为翻译管线定制的 Lint

scripts/lint-mdx.ts 是迁移“人工复核清单”沉淀下来的自动化防线。它解决一个非常具体的问题：翻译平台会把正文中的<foo>解析成标签，导致尖括号占位符在每种语言的译文里丢失或变形；而花括号{foo}能安全往返（见 第 3–6 行 的注释）。脚本的判定细节包括：

• 跳过node_modules、l、images、scripts目录，只扫描源 MDX；
• 内置约 60 个合法 HTML 元素名单（img、iframe、video等），避免误报真实元素；
• 精确计算围栏代码块（支持不同长度的反引号围栏配对）与行内代码区间，代码内的占位符不计为违规；
• 命中时输出文件:行:列并提示“reads as a tag in Crowdin, use {name} instead”，有违规则退出码 1。

配合lint目标中的 oxlint，MDX 内容在进入翻译管线前就有机器校验——这是对迁移文档中“Custom styled elements - Review for compatibility”这类遗留项的长期治理。

七、已知问题清单与遗留事项

MIGRATION.md 末尾的 Known Issues to Review 是迁移期的诚实存档，逐条对照当前仓库可作如下收束：

• ArticleTabs 组件可能需手工转换：Mintlify 使用<Tabs>组件，需逐页处理——对应现在 MDX 页面中的 Tabs 用法；
• 部分图片路径可能不正确：当前图片统一收敛在 images/ 下，按 README 约定以/images/...绝对路径引用；
• 自定义样式组件可能需要调整：以 snippets/ 中的可复用片段（card-title、chart-icon、vimeo-embed）+ oxlint/MDX lint 双重约束来收敛；
• 视频嵌入可能需要复核：已用VimeoEmbed片段给出统一实现。

八、小结：一次迁移如何变成一套可持续的文档工程

回顾这次迁移的完整轨迹：先用明确的范围清单（69 篇 MDX、81 张图、完整导航）完成一次性搬迁；再用“旧组件 → Mintlify 等价物”的映射表消除渲染层差异；随后以npx nx run twenty-docs:dev在 3000 端口做整站预览、以validate做构建校验，并把子目录packages/twenty-docs接入 Mintlify 的自动部署。迁移结束后，仓库又把导航改造成base-structure.json → generate-docs-json.ts → docs.json的生成式管线，让 12 种语言共用一份结构、各取一份标签，并用专门的 MDX lint 守住翻译往返的一致性。对需要把文档站从自研组件迁移到 Mintlify（或同类托管文档平台）的团队来说，这份仓库内的完整案例提供了从范围盘点、组件转换、本地验证到多语言持续治理的可复制路径。

【免费下载链接】twentyThe open alternative to Salesforce, designed for AI.项目地址: https://gitcode.com/GitHub_Trending/tw/twenty