2026/9/8 22:10:26
FEATURED · 精选文章 
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 个分组sectionDevelopers 标签页有 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 链接textArticleEditContent直接删除Mintlify 侧无需对应物需要人工复核的部分ArticleTabsMintlify 的对应组件是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同文件还定义了另外四个目标构成完整的本地验证矩阵devmintlify dev启动开发服务器默认 http://localhost:3000validatemintlify validate校验文档构建是否合法对应根目录命令npx nx run twenty-docs:validatelint先跑npx oxlint -c .oxlintrc.json .通用 TS/JS 规则再跑npx tsx scripts/lint-mdx.tsMDX 专用规则串行执行testnpx vitest run --config vitest.config.mts用于脚本层单测fmtPrettier 检查/修复带缓存目录。运行前提也写得很明确package.json 声明engines为 Node^24.5.0、Yarn^4.0.2npm字段为please-use-yarn即强制 Yarnmintlify依赖版本锁定在^4.2.790。复现迁移文档的验证步骤时应使用仓库统一的 Yarn 工作区环境而不是单独npm install。五、部署流程仓库即文档源MIGRATION.md 的 Deployment 章节给出了四步上线流程核心思想是“文档以仓库文件为唯一事实来源Mintlify 只负责拉取与构建”将变更推送到代码仓库在 Mintlify 控制台关联该仓库将子目录subdirectory设置为packages/twenty-docs——即 Mintlify 不会构建整个 monorepo只以该包为文档根之后 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 质量门禁为翻译管线定制的 Lintscripts/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目标中的 oxlintMDX 内容在进入翻译管线前就有机器校验——这是对迁移文档中“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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
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 个分组sectionDevelopers 标签页有 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 链接textArticleEditContent直接删除Mintlify 侧无需对应物需要人工复核的部分ArticleTabsMintlify 的对应组件是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同文件还定义了另外四个目标构成完整的本地验证矩阵devmintlify dev启动开发服务器默认 http://localhost:3000validatemintlify validate校验文档构建是否合法对应根目录命令npx nx run twenty-docs:validatelint先跑npx oxlint -c .oxlintrc.json .通用 TS/JS 规则再跑npx tsx scripts/lint-mdx.tsMDX 专用规则串行执行testnpx vitest run --config vitest.config.mts用于脚本层单测fmtPrettier 检查/修复带缓存目录。运行前提也写得很明确package.json 声明engines为 Node^24.5.0、Yarn^4.0.2npm字段为please-use-yarn即强制 Yarnmintlify依赖版本锁定在^4.2.790。复现迁移文档的验证步骤时应使用仓库统一的 Yarn 工作区环境而不是单独npm install。五、部署流程仓库即文档源MIGRATION.md 的 Deployment 章节给出了四步上线流程核心思想是“文档以仓库文件为唯一事实来源Mintlify 只负责拉取与构建”将变更推送到代码仓库在 Mintlify 控制台关联该仓库将子目录subdirectory设置为packages/twenty-docs——即 Mintlify 不会构建整个 monorepo只以该包为文档根之后 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 质量门禁为翻译管线定制的 Lintscripts/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目标中的 oxlintMDX 内容在进入翻译管线前就有机器校验——这是对迁移文档中“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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
