核心概念

Mintlify 会将 Git 存储库中的内容构建成一个文档站点。你可以在浏览器中的编辑器里工作，在本地开发环境中工作，或者在 Slack 中向 Mintlify agent 发送提示。这三种工作流都会更新同一个存储库。Mintlify 会将存储库中的内容构建为面向人类和 agent 的优化体验。

组织 (organization) 是你的团队的工作空间。它包含你的成员、组织级别的设置以及一个或多个部署。

部署 (deployment) 是你组织中的一个文档项目。它将一个存储库、内容目录和部署分支连接到一个已发布的站点。一个组织可以为不同的产品或文档资产拥有多个部署。

在线站点 (live site) 是一个部署所发布的产物。Mintlify 默认提供一个 .mintlify.site 的 URL。你可以为你的站点连接一个自定义域名。站点包含你的内容、导航、搜索，以及你启用的任何功能，例如 AI 助手或 API playground。

你的文档存储库中包含定义站点的文件。Mintlify 会在每次构建时读取这些文件。

• 页面 (pages) 是 .mdx 文件。每个页面都包含内容和 frontmatter 元数据。
• docs.json 是必需的配置文件。它控制导航、外观、集成、API 设置以及其他站点级的行为。
• 资源 (assets) 包括页面中引用的图片、视频、字体和可下载文件。
• API 规范 (API specifications) 可以基于 OpenAPI、AsyncAPI 或 GraphQL schema 生成 API 参考页面和交互式 playground。
• 可复用文件 (reusable files) 包括 snippets 和自定义 React 组件，页面可以导入使用。

你的存储库中可以包含未发布的文件。只有当你在 docs.json 的导航中引用某个页面时，该页面才会出现在站点导航中，否则会被隐藏。隐藏页面 只能通过直接链接访问。

页面 (page) 提供某个 URL 上的内容。其 frontmatter 控制页面级的元数据和行为，包括标题、描述、图标和布局。

导航 (navigation) 决定读者如何在页面之间浏览。你可以在 docs.json 文件中使用分组、标签、下拉菜单、产品、版本和语言等元素来配置导航。文件路径决定了页面是哪个，而它在 docs.json 中的位置决定了它在导航中的位置。

这种分离让你无需移动文件就能重新组织读者的浏览体验。它还允许你将某些工具类页面从导航中排除，同时保留通过 URL 访问的能力。

你可以通过两种主要工作流来编辑同一份内容。

在编辑器中，更改会自动保存，但不会立即更新你的存储库或在线站点。当你发布时，编辑器会将更改写入 Git。之后发生的事情取决于你当前所在的分支和分支保护设置。

• 在部署分支上，发布可以直接触发在线站点的构建。
• 在功能分支上，发布可以将更改保存到该分支，或创建一个拉取请求以供审核。
• 预览部署会将拉取请求渲染到一个临时 URL，以便审核者在合并前检查结果。
• 将拉取请求合并到部署分支会触发一次生产部署。

有关完整工作流，请参阅分支与发布。

当内容进入部署分支时，Mintlify 会校验项目、渲染页面并部署站点。相同的源内容支持多种查找和消费信息的方式：

• 文档站点会为桌面和移动端用户渲染页面。
• 搜索会为站点建立索引，让读者能够找到相关页面。
• AI 助手可以基于文档回答问题，并注明其信息来源。
• 页面的 Markdown 版本、llms.txt 和 skill.md 可以帮助 AI 工具理解内容。
• 一个公开的 MCP 服务器让兼容的 AI 工具能够将文档作为结构化上下文来检索。

在发布前运行 mint validate 和 mint broken-links，可以在本地捕获常见问题。

Mintlify 为阅读、写作、自动化以及外部工具访问分别提供了不同的 AI 功能。

请参阅术语表，其中包含本文档中使用的 Mintlify、Git、发布、导航、API 和 AI 相关术语的定义。