企业官网建设流程全解析

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-shared（workspace:*）与vitest，说明文档脚本需要复用共享包中的常量（如支持的语言列表），并配有单元测试。

按 README 的说明，文档内容分为三大部分：

翻译内容则按语言存放在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 Lint：oxlint + 自研 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}可以安全往返。因此该脚本：

1. 递归收集packages/twenty-docs下所有.mdx文件（忽略node_modules、l、images、scripts目录，即只检查英文源页面）；
2. 先精确识别 fenced code block（正确处理了不同长度的反引号围栏）与行内 code 区间，避免误报代码中的内容；
3. 对正文中出现的<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 添加图片

1. 将图片放入 images/ 目录（该目录下已有core/、docs/、lab/、releases/、user-guide/等子目录，其中user-guide/下有近 150 张用户指南截图）；
2. 在 MDX 中直接引用：Alt text；
3. 或使用 Mintlify 的 Frame 组件包裹以获得统一边框样式：

<Frame> <img src="/images/your-image.png" alt="Description" /> </Frame>

四、导航与国际化架构：从 base-structure 到 docs.json 的完整链路

这是文档站工程化设计的核心。README 的 "Editing Content" 与 "Configuration" 两节定义了五个关键文件及其职责分工：

4.1 base-structure.json 的结构

navigation/base-structure.json 顶层是tabs数组，每个 tab 含key、label与groups；group 可含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