Mintlify

学完能做什么 / 解决什么问题

通过本教程，你将掌握如何利用 Mintlify 为你的初创企业、企业内部项目或 AI 代理构建一个自动更新、无需手动维护的知识平台。你将学会：

• 从代码仓库自动同步文档，消除手动发布流程
• 为 AI 代理提供结构化、可搜索的知识库，提升回答准确率
• 快速搭建专业级开发者文档站点，支持多版本、API 参考和交互式示例

前置条件

• 一个 Mintlify 账户（免费注册于 https://www.mintlify.com/）
• 一个 GitHub 或 GitLab 仓库，用于存放文档内容（Markdown 文件）
• 基础 Markdown 语法知识
• 对要文档化的项目（如 API、SDK、产品功能）有基本了解

分步操作

步骤 1：创建 Mintlify 项目并连接仓库

1. 登录 Mintlify 控制台，点击 New Project。
2. 输入项目名称（例如 my-api-docs），选择 Public 或 Private 可见性。
3. 在 Repository 区域，选择你的 GitHub/GitLab 仓库（例如 org/docs-repo）。
4. 选择要同步的分支（默认 main 或 master）。
5. 点击 Create Project，Mintlify 会自动在仓库中创建 .mintlify 目录和配置文件。

预期结果：仓库中出现 .mintlify/config.json 文件，Mintlify 控制台显示项目已就绪。

步骤 2：配置文档结构

1. 在仓库根目录下创建 docs/ 文件夹（或按 config.json 中 navigation 指定的路径）。
2. 在 docs/ 内创建 Markdown 文件，例如 getting-started.md、api-reference.md。
3. 编辑 .mintlify/config.json，定义导航栏结构：

{
  "navigation": [
    { "group": "入门指南", "pages": ["docs/getting-started"] },
    { "group": "API 参考", "pages": ["docs/api-reference"] }
  ]
}

4. 提交并推送代码到仓库分支。

预期结果：Mintlify 自动检测到文件变更，站点导航栏显示你定义的分组和页面。

步骤 3：启用自动更新

1. 在 Mintlify 控制台，进入项目 Settings → Webhooks。
2. 确认 Auto-sync 开关已开启（默认开启）。
3. 在仓库设置中，添加 Mintlify 提供的 Webhook URL（从控制台复制）。
4. 配置触发事件：选择 Push events（仅推送至同步分支时触发）。

预期结果：每次推送代码到仓库，Mintlify 自动重建站点，无需手动部署。

步骤 4：为 AI 代理添加知识库

1. 在 Mintlify 控制台，进入项目 AI → Knowledge Base。
2. 点击 Add Source，选择 Documentation（或 Files，如上传 PDF）。
3. 选择要索引的文档页面（例如所有 docs/ 下的文件）。
4. 点击 Index，等待处理完成（通常 1-5 分钟）。
5. 在 AI → Chat 中测试查询，例如“如何开始使用 API？”。

预期结果：AI 代理能基于你的文档回答用户问题，并引用具体页面链接。

步骤 5：自定义品牌与域名

1. 在 Settings → Branding 中，上传 Logo（建议 512x512px PNG）。
2. 设置主色调（如 #2563EB）和字体（可选 Google Fonts）。
3. 在 Settings → Domain 中，输入自定义域名（如 docs.yourcompany.com）。
4. 按提示在 DNS 提供商处添加 CNAME 记录指向 mintlify.app。

预期结果：站点显示你的品牌风格，并通过自定义域名访问。

常见问题

注意事项与边界

• 文档格式：Mintlify 支持标准 Markdown 及扩展语法（表格、代码块、数学公式）。不支持 HTML 嵌入或自定义 CSS。
• 多版本：如需管理多个 API 版本（如 v1、v2），在 config.json 中通过 versions 字段定义，并为每个版本创建独立目录。
• 权限：私有项目需要团队成员登录 Mintlify 账户才能访问。企业版支持 SSO 集成。
• 失败排查：若站点持续构建失败，检查 .mintlify/config.json 的 JSON 格式是否合法，或查看控制台 Build Logs 中的错误信息。