Twenty 文档站实战指南基于 Mintlify 的多语言文档体系构建与导航生成机制【免费下载链接】twentyThe open alternative to Salesforce, designed for AI.项目地址: https://gitcode.com/GitHub_Trending/tw/twenty本文以 Twenty开源 CRM仓库中的packages/twenty-docs文档包为对象系统讲解 Twenty 官方文档站的完整构建与本地运行流程如何用 Mintlify 在本地预览文档、如何按 MDX 规范编写页面与插图、以及基线导航结构 Crowdin 翻译 生成脚本三件套如何共同产出多语言docs.json。读完本文你可以独立完成文档页面的新增与修改、正确运行导航/路径常量的生成命令并理解 Twenty 文档站多语言切换背后的工程化设计。一、文档包概览文档站在 monorepo 中的位置Twenty 的官方文档由 packages/twenty-docs 目录承载基于 Mintlify 构建。从 package.json 可以看到关键依赖与版本约束核心依赖mintlify版本^4.2.790负责站点渲染与本地开发服务engines字段要求 Node.js^24.5.0、Yarn^4.0.2并且通过npm: please-use-yarn明确禁止使用 npm与整个 monorepo 的 Yarn 工作区约定一致开发依赖中引用了twenty-sharedworkspace:*与vitest说明文档脚本需要复用共享包中的常量如支持的语言列表并配有单元测试。按 README 的说明文档内容分为三大部分内容板块规模目录User Guide用户指南46 页user-guide/Developers开发者文档24 页developers/入门内容Getting Started含核心概念等getting-started/翻译内容则按语言存放在l/language/下当前仓库覆盖ar、cs、de、es、fr、it、ja、ko、pt、ro、ru、tr、zh等 13 个非英语语言目录每个目录约 200 个翻译后的 MDX 页面。二、本地开发dev / validate / lint 三类命令文档站通过 Nx 工作区管理project.json 中定义了dev、validate、lint、fmt、test五个 target其中dev与validate分别直接执行mintlify dev和mintlify validate工作目录为{projectRoot}即packages/twenty-docs。2.1 本地预览在 Twenty monorepo 根目录下执行npx nx run twenty-docs:dev启动后文档站运行在http://localhost:3000。由于 Mintlify 会监听文件变化编辑任何 MDX 页面都会即时反映在浏览器中这也是官方推荐的贡献流程中的本地验证环节。2.2 构建校验# Validate the documentation build npx nx run twenty-docs:validate该命令调用mintlify validate用于在提交前检查文档构建的合法性如断链、配置错误等。2.3 Lintoxlint 自研 MDX 规则project.json中的linttarget 实际是两条串行命令commands: [ npx oxlint -c .oxlintrc.json ., npx tsx scripts/lint-mdx.ts ]第二条命令运行 scripts/lint-mdx.ts这是一个非常有针对性的自研检查器解决的是Crowdin 翻译往返过程中的占位符丢失问题。文件头部的注释说明了动机Crowdin 会把正文中的foo解析为 HTML 标签而非字面文本导致翻译后的页面里尖括号占位符被丢弃或变形而花括号写法{foo}可以安全往返。因此该脚本递归收集packages/twenty-docs下所有.mdx文件忽略node_modules、l、images、scripts目录即只检查英文源页面先精确识别 fenced code block正确处理了不同长度的反引号围栏与行内 code 区间避免误报代码中的内容对正文中出现的xxx形式占位符排除真实 HTML 元素名与 URL 前缀场景逐处报错提示reads as a tag in Crowdin, use {xxx} instead发现任何违规即以退出码 1 终止。这一机制保证了所有需要进入翻译流程的模板变量都使用对翻译平台安全的写法。三、内容编写规范MDX 页面、Frontmatter 与图片3.1 MDX 页面格式所有文档页面使用 MDX 格式并携带 frontmatter基本结构如下--- title: Page Title description: Page description image: /images/path/to/image.png --- Your content here...title页面标题用于导航展示description页面描述会用于 SEO 与摘要image页面级图片供分享卡片等场景使用。新增或修改页面的入口目录为user-guide/ —— 用户文档developers/ —— 开发者文档。3.2 添加图片将图片放入 images/ 目录该目录下已有core/、docs/、lab/、releases/、user-guide/等子目录其中user-guide/下有近 150 张用户指南截图在 MDX 中直接引用Alt text或使用 Mintlify 的 Frame 组件包裹以获得统一边框样式Frame img src/images/your-image.png altDescription / /Frame四、导航与国际化架构从 base-structure 到 docs.json 的完整链路这是文档站工程化设计的核心。README 的 Editing Content 与 Configuration 两节定义了五个关键文件及其职责分工文件职责是否上传 Crowdinnavigation/base-structure.jsontabs / groups / 图标 / 页面 slug 的唯一事实源Source of truth仅英文否navigation/navigation.template.json自动生成的翻译模板仅含 labels是唯一上传统译平台的文件l/language/navigation.json从 Crowdin 拉回的各语言标签文件仅含 labels页面 slug 始终来自基线结构否docs.json生成的 Mintlify 站点配置导航部分由脚本重写—package.json / project.json依赖、脚本与 Nx 工作区配置—4.1 base-structure.json 的结构navigation/base-structure.json 顶层是tabs数组每个 tab 含key、label与groupsgroup 可含icon如database、cloud-arrow-up与pages。pages既可以直接是页面 slug 字符串如user-guide/data-model/overview也可以是嵌套子 group 对象如 contenteditable="false">【免费下载链接】twentyThe open alternative to Salesforce, designed for AI.项目地址: https://gitcode.com/GitHub_Trending/tw/twenty创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Twenty 文档站实战指南基于 Mintlify 的多语言文档体系构建与导航生成机制【免费下载链接】twentyThe open alternative to Salesforce, designed for AI.项目地址: https://gitcode.com/GitHub_Trending/tw/twenty本文以 Twenty开源 CRM仓库中的packages/twenty-docs文档包为对象系统讲解 Twenty 官方文档站的完整构建与本地运行流程如何用 Mintlify 在本地预览文档、如何按 MDX 规范编写页面与插图、以及基线导航结构 Crowdin 翻译 生成脚本三件套如何共同产出多语言docs.json。读完本文你可以独立完成文档页面的新增与修改、正确运行导航/路径常量的生成命令并理解 Twenty 文档站多语言切换背后的工程化设计。一、文档包概览文档站在 monorepo 中的位置Twenty 的官方文档由 packages/twenty-docs 目录承载基于 Mintlify 构建。从 package.json 可以看到关键依赖与版本约束核心依赖mintlify版本^4.2.790负责站点渲染与本地开发服务engines字段要求 Node.js^24.5.0、Yarn^4.0.2并且通过npm: please-use-yarn明确禁止使用 npm与整个 monorepo 的 Yarn 工作区约定一致开发依赖中引用了twenty-sharedworkspace:*与vitest说明文档脚本需要复用共享包中的常量如支持的语言列表并配有单元测试。按 README 的说明文档内容分为三大部分内容板块规模目录User Guide用户指南46 页user-guide/Developers开发者文档24 页developers/入门内容Getting Started含核心概念等getting-started/翻译内容则按语言存放在l/language/下当前仓库覆盖ar、cs、de、es、fr、it、ja、ko、pt、ro、ru、tr、zh等 13 个非英语语言目录每个目录约 200 个翻译后的 MDX 页面。二、本地开发dev / validate / lint 三类命令文档站通过 Nx 工作区管理project.json 中定义了dev、validate、lint、fmt、test五个 target其中dev与validate分别直接执行mintlify dev和mintlify validate工作目录为{projectRoot}即packages/twenty-docs。2.1 本地预览在 Twenty monorepo 根目录下执行npx nx run twenty-docs:dev启动后文档站运行在http://localhost:3000。由于 Mintlify 会监听文件变化编辑任何 MDX 页面都会即时反映在浏览器中这也是官方推荐的贡献流程中的本地验证环节。2.2 构建校验# Validate the documentation build npx nx run twenty-docs:validate该命令调用mintlify validate用于在提交前检查文档构建的合法性如断链、配置错误等。2.3 Lintoxlint 自研 MDX 规则project.json中的linttarget 实际是两条串行命令commands: [ npx oxlint -c .oxlintrc.json ., npx tsx scripts/lint-mdx.ts ]第二条命令运行 scripts/lint-mdx.ts这是一个非常有针对性的自研检查器解决的是Crowdin 翻译往返过程中的占位符丢失问题。文件头部的注释说明了动机Crowdin 会把正文中的foo解析为 HTML 标签而非字面文本导致翻译后的页面里尖括号占位符被丢弃或变形而花括号写法{foo}可以安全往返。因此该脚本递归收集packages/twenty-docs下所有.mdx文件忽略node_modules、l、images、scripts目录即只检查英文源页面先精确识别 fenced code block正确处理了不同长度的反引号围栏与行内 code 区间避免误报代码中的内容对正文中出现的xxx形式占位符排除真实 HTML 元素名与 URL 前缀场景逐处报错提示reads as a tag in Crowdin, use {xxx} instead发现任何违规即以退出码 1 终止。这一机制保证了所有需要进入翻译流程的模板变量都使用对翻译平台安全的写法。三、内容编写规范MDX 页面、Frontmatter 与图片3.1 MDX 页面格式所有文档页面使用 MDX 格式并携带 frontmatter基本结构如下--- title: Page Title description: Page description image: /images/path/to/image.png --- Your content here...title页面标题用于导航展示description页面描述会用于 SEO 与摘要image页面级图片供分享卡片等场景使用。新增或修改页面的入口目录为user-guide/ —— 用户文档developers/ —— 开发者文档。3.2 添加图片将图片放入 images/ 目录该目录下已有core/、docs/、lab/、releases/、user-guide/等子目录其中user-guide/下有近 150 张用户指南截图在 MDX 中直接引用Alt text或使用 Mintlify 的 Frame 组件包裹以获得统一边框样式Frame img src/images/your-image.png altDescription / /Frame四、导航与国际化架构从 base-structure 到 docs.json 的完整链路这是文档站工程化设计的核心。README 的 Editing Content 与 Configuration 两节定义了五个关键文件及其职责分工文件职责是否上传 Crowdinnavigation/base-structure.jsontabs / groups / 图标 / 页面 slug 的唯一事实源Source of truth仅英文否navigation/navigation.template.json自动生成的翻译模板仅含 labels是唯一上传统译平台的文件l/language/navigation.json从 Crowdin 拉回的各语言标签文件仅含 labels页面 slug 始终来自基线结构否docs.json生成的 Mintlify 站点配置导航部分由脚本重写—package.json / project.json依赖、脚本与 Nx 工作区配置—4.1 base-structure.json 的结构navigation/base-structure.json 顶层是tabs数组每个 tab 含key、label与groupsgroup 可含icon如database、cloud-arrow-up与pages。pages既可以直接是页面 slug 字符串如user-guide/data-model/overview也可以是嵌套子 group 对象如 contenteditable="false">【免费下载链接】twentyThe open alternative to Salesforce, designed for AI.项目地址: https://gitcode.com/GitHub_Trending/tw/twenty创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
