Clarify

从 Mintlify 迁移到 Clarify

Clarify 的设计参考了 Mintlify 的优秀实践，并提供了兼容的配置格式，让迁移尽可能平滑。

配置兼容

Mintlify 的 docs.json 与 Clarify 的 clarify.json 字段基本兼容：

MintlifyClarify说明
nametitle同义
descriptiondescription直接对应
logologo直接对应
colors.primarytheme.tokens.colors.primary路径调整，可与 theme.preset 搭配使用

Clarify 会接受未知的 Mintlify 字段并静默忽略（附带警告），提供平滑的迁移路径。

迁移步骤

1. 重命名配置文件

mv docs.json clarify.json

2. 调整字段

// 之前 (docs.json)
{
  "name": "我的文档",
  "colors": {
    "primary": "#00D492"
  }
}

// 之后 (clarify.json)
{
  "title": "我的文档",
  "theme": {
    "preset": "default",
    "tokens": {
      "colors": {
        "primary": "#00D492"
      }
    }
  }
}

3. 迁移内容文件

Mintlify 使用 .mdx 或 .md 文件，Clarify 同样支持 MDX：

  • 将内容文件复制到 source/ 目录
  • 确保文件结构和路由期望一致
  • 检查并更新 frontmatter 格式

4. 安装依赖并构建

pnpm add -D @clarify-labs/cli
pnpm exec clarify build

差异说明

功能MintlifyClarify
托管方式托管服务自托管，构建为静态文件
路由配置navigation 字段tabs 显式配置 + 文件路由
组件库内置 Mintlify 组件MDX + Clarify 内置组件 + 自定义 React 组件
OpenAPI托管平台能力OpenAPI 文件作为一等内容源，可生成 Reference 和嵌入接口
i18n支持内置 locale 目录、语言切换和缺失翻译策略
AI 读取平台能力静态输出 Markdown、OpenAPI 和 llms.txt

需要帮助？

如果在迁移过程中遇到问题，欢迎通过以下渠道获取支持：