mintlify

Mintlify 参考

使用 Mintlify 项目的参考指南。本文件涵盖适用于所有任务的要点。如需了解特定主题的详细参考，请阅读下方参考索引中列出的文件。

Mintlify CLI 还会从实时文档中获取当前指南，介绍如何在 Mintlify 中完成特定任务。运行 mint instructions 列出主题，然后运行 mint instructions <topic> 获取说明。如果无法识别该命令，请运行 npx mint@latest instructions。如果它与本文件内容不同，请遵循 mint instructions。

参考索引

仅在任务需要时阅读。每个链接都指向 Mintlify 文档页面；对于 Agent 工作流指南，则指向 GitHub 上的源文件。

参考资料	阅读时机
组件	添加或修改组件（提示框、卡片、步骤、标签页、折叠面板、代码组、字段、框架、图标、工具提示、徽章、树形图、mermaid、MDX、面板、提示词、颜色、磁贴、更新、视图）。也涵盖表格列宽。
全局设置	更改 docs.json 设置（主题、颜色、徽标、字体、外观、导航栏、页脚、横幅、重定向、SEO、集成、API 配置）。也涵盖代码片段、隐藏页面、.mintignore、自定义 CSS/JS，以及完整的 frontmatter 字段表。
导航	修改网站导航结构（分组、标签页、锚点、下拉菜单、产品、版本、语言、OpenAPI，以及导航中的 SDK 参考资料）。
API 交互区	设置 API 文档（OpenAPI、AsyncAPI、MDX 手动编写的 API 页面、扩展、交互区配置）。
CLI 命令	运行常见 CLI 命令（dev、validate、add-domain、analytics、score、broken-links、a11y、format 和 config）及其关键标志。
产品背景	开展重要的内容工作之前（新建网站、大范围重组、首次设置章节）——检查并维护 .mintlify/product-brief.md。
自定义脚本	使用 CSS、JavaScript、React 代码片段、选择器或 CSS 变量自定义外观或浏览器行为。
编写页面	创建页面或撰写超过一两句话的内容之前：了解禁止臆造规则、页面创建和编辑步骤、质量标准、受众、标题和描述、链接。
发布与审核	发布、分支和拉取请求、“是否已上线”相关问题、撤销更改，以及通过建议和评论审核页面。
项目设置	查看或更改控制台设置（域名、Git 来源、身份验证、成员、工作流、搜索、附加功能）、查阅工具无法覆盖的设置，以及分析相关问题。
小组件	编写或重写解释取决于输入、流程、结构、比较或 UI 的值的页面之前：使用实时 React 小组件，而不是截图、录屏或 Mermaid。涵盖何时构建小组件及其具体限制。
构建网站	构建或迁移整个网站、一个章节或多于少数几个页面时：了解调研范围、生成顺序、首页、常见网站类型的结构和迁移规则。

开始搭建新的文档网站

如果用户想要新建文档网站、发布文档，或尚无 docs.json，请自行运行此工作流。仅向用户询问你无法提供的信息或无法自行批准的事项。建议使用 CLI 引导流程。如果用户更愿意在浏览器中完成引导，或你无法运行终端命令，请让他们访问 mintlify.com/start。

1. 检查 node --version（v20.17.0 或更高版本）。运行 mint --version；如果未安装，则运行 npm i -g mint 安装。如果已安装，则运行 mint update。然后运行 mint instructions new-site，查看当前设置指南。
2. 运行 mint status。如果显示了组织，请使用该账户并按照 已有账户 操作。如果用户有账户但尚未登录，请运行 mint login。如果用户没有账户，请按照 没有账户 操作。不要自行运行 mint signup：从 Agent 或任何非交互式 shell 中运行时，它只会输出 https://mintlify.com/auth.md，不会创建账户。

已有账户：

3. 运行 mint status，确认组织和子域名。如果没有显示子域名，请让用户在浏览器中完成入门设置，选择或连接 GitHub 仓库，然后重试。
4. 除非你已经在该仓库中工作，否则请向用户索要已连接仓库的 URL（mint status 不会显示该 URL），并克隆仓库。如果用户连接的是自己的文档仓库，请保留其中的内容；如果没有 docs.json，则添加一个。如果仓库由 Mintlify 创建，其中包含起始内容；请用用户已有的 Markdown 文档替换这些内容，而不是编写占位页面。只有当用户想要的主题不同于起始主题时，才使用 mint new <directory> --name <name> --theme <theme>，并在新的空目录中生成框架。切勿对包含用户文件的目录使用 --force。
5. 在包含 docs.json 的目录中，将 mint dev --no-open 作为后台进程运行。向用户提供本地 URL 供其预览。运行 mint validate 和 mint broken-links，并修复由你造成的问题。
6. 提交并推送到已连接的仓库以部署。
7. 报告 URL 前，请确认 https://<subdomain>.mintlify.site 可以正常加载。

没有账户： 无需账户即可创建站点，然后交由用户接管。

3. 在包含 docs.json 的目录中准备文档：使用用户已有的 Markdown 文档，或在新的空目录中运行 mint new <directory> --name <name> --theme <theme>。将 mint dev --no-open 作为后台进程运行以供预览，然后运行 mint validate 和 mint broken-links，并修复由你造成的问题。
4. 在该目录中运行 mint deploy --subdomain <subdomain>，并按照它输出的 Git 命令操作：将托管仓库克隆到单独的目录中，将 docs.json、页面和资源复制到该仓库的根目录，提交并推送到 main。切勿在远程 URL 中输出、提交或保存写入令牌。
5. 报告 URL 前，请确认 https://<subdomain>.mintlify.site 可以正常加载。
6. 如果没有人认领，站点会过期。询问用户要将哪个邮箱设为站点所有者（切勿编造邮箱），然后运行 mint claim --email <email>。让用户打开链接、登录或创建账户，并读出代码，然后运行 mint claim --code <code>。这两个命令都必须在 mint deploy 所在目录中运行。
7. 如果文档存放在 GitHub 仓库中，且用户希望每次推送时都自动部署，请在认领前运行 mint deploy --github --subdomain <subdomain>，并提交它生成的 .github/workflows/mintlify.yml。此操作需要 GitHub origin 远程仓库和已登录的 GitHub CLI，且仅适用于尚未认领的站点。

在任一流程中发布之前，请主动询问用户是否要将其编码 Agent 连接到项目。如果用户同意，且 Node.js 版本为 v22.20 或更高，请在项目目录中运行 mint agent setup --agent <agent>，其中 <agent> 为 claude-code、codex 或 cursor。此命令会安装 Mintlify 技能，并将管理 MCP 添加到 Agent 的项目配置中。请传入 --agent；如果没有交互式终端，该命令会配置检测到的所有 Agent。然后，用户需在 Agent 中完成 OAuth 登录。请参阅 CLI 命令。

用户只需使用浏览器进行 OAuth 授权、连接 GitHub 和认领站点。

没有本地仓库

如果没有本地检出，也没有 CLI（例如，通过 Mintlify Admin MCP 服务或在 Mintlify 编辑器中进行编辑），请跳过此技能中的 mint、git 和文件系统步骤：

• 使用 Admin MCP 工具在 branch 上读取和修改页面、导航和 docs.json。
• 使用 create_node 创建页面；write_page 只会替换现有页面。
• 使用工具返回的 editorUrl 进行预览，而不是运行 mint dev。每次写入都会运行验证，因此请修复写入操作返回的任何错误，而不是运行 mint validate。
• 使用 publish 发布，而不是推送；仅在用户提出要求时发布。
• 将 Product context 中的产品简介保留在对话中，而不是写入 .mintlify/product-brief.md。
• 对于新站点，请根据现有项目遵循 Site building。

从其他平台迁移

CLI 会为 Agent 输出迁移说明：mint migrate 会显示工作流，并列出其涵盖的主题和源平台。运行 mint migrate --from <platform> 获取相应平台的指南，运行 mint migrate --topic <name> 获取单个主题的指南。对于 Docusaurus、GitBook、ReadMe、Fern 或 Document360，请使用 Mintlify Search MCP 服务读取对应的指南：https://mintlify.com/docs/migration/<platform>.md（例如 docusaurus.md）。对于其他平台，请遵循 https://mintlify.com/docs/migration/manual.md。抓取工具仅支持简单的公开站点。复杂站点应从源文件迁移。移植规则见 Site building。

MCP 服务

有两个 Mintlify MCP 服务可用。请将它们与此技能中的参考文件配合使用。

Mintlify Search

只读访问 Mintlify 已发布的文档。当参考文件未涵盖某个具体细节、需要获取最新的组件签名，或需要核实不熟悉的配置选项时，请使用此服务。

工具：

• search_mintlify — 按查询搜索 Mintlify 知识库。适合查找指南、示例和 API 参考。
• query_docs_filesystem_mintlify — 浏览文档文件树（ls、cat、grep、find 等）。适合读取特定文档页面。
• submit_feedback — 报告存在错误、过时、令人困惑或不完整的文档页面。路径（相对路径或完整 URL）必须与已发布页面或重定向源匹配；否则工具会返回错误且不会记录任何内容。

Mintlify Admin

对 Mintlify 项目的写入权限。首次使用时需要 OAuth。出现提示时，请在浏览器中完成身份验证。

当用户希望编辑 Mintlify 内容、重新组织导航或创建拉取请求时，请使用此服务。每个内容工具都接受 branch 参数：编辑、publish、discard 和评论写入时必须提供；读取时可选（默认使用部署分支）。调用之间不会保留任何信息，因此每次都要传入 branch。在部署分支上的编辑会成为尚未发布的更改，直到调用 publish。在其他分支上的编辑会通过拉取请求提交。项目管理工具所做的更改会立即应用到线上项目，不需要分支或拉取请求。 工作流：使用 read/search/edit_page/write_page/list_nodes/create_node/update_node/move_node/delete_node/update_config，并指定 branch 进行更改；然后调用 publish，并指定 branch 和 title 以发布（或调用 discard 放弃更改）。传入部署分支可直接编辑。如果项目要求创建拉取请求（直接推送到部署分支处于关闭状态、分支保护要求创建拉取请求、部署分支编辑已锁定，或连接使用客户端或机器对机器令牌），则对部署分支的编辑会被拒绝，并说明原因，且不会做出任何更改。请调用 create_branch，并将其 branchName 作为 branch 传入。在启用自动发布的项目中，没有分支：请传入部署分支，更改会自动提交。在此类项目中，create_branch 和其他分支操作会被拒绝，且不适用拉取请求要求。 关键工具：

• create_branch — 使用 title 从部署分支新建分支；该标题也会用作其拉取请求的名称。返回 branchName 和分支级别的 editorUrl，可用于实时预览更改。在分支上，Mintlify 会在最后一次更改约 15 秒后自动提交编辑；首次提交会创建一个拉取请求。
• list_branches — 列出已有分支；将其中任意分支作为 branch 传入。不存在的分支会被拒绝。
• list_deployments — 查明此连接可以访问哪些项目。
• read / search：获取页面的 MDX，或搜索多个页面。read、edit_page 和 write_page 接受页面路径（例如 guides/setup），或编辑器 URL 的最后一段；该段是页面 ID，前面可能带有标题。使用编辑器 URL 中的页面 ID 时，请将该 URL 对应的分支作为 branch 传入。read 会返回一个 filePath，可将其作为 path 传给 edit_page 和 write_page。
• edit_page / write_page：执行定向编辑或覆盖页面。使用 update_node 而不是 edit_page 来更改 frontmatter。edit_page 接受用于进行一次替换的 oldString 和 newString，或最多包含 100 项替换的 edits 列表，并按顺序应用；如果任一编辑失败，则全部不应用。对于编辑器会丢弃的标记（例如 <script>、<style>、事件处理器或 JavaScript 表达式），两者都会返回 notRendered，并说明应改用什么。
• read_page_history：列出页面在 branch 上保存的版本（按时间从新到旧排列，可使用 cursor 分页），或传入 versionId 读取该版本的 MDX。此工具为只读；若要恢复某个版本，请将其 content 传给 write_page。
• read_comments / add_comment / suggest_edit / reply_to_comment / resolve_comment：读取页面上尚未解决的编辑器评论串；针对精确文本发起评论串；提出带修订跟踪的建议（oldString 替换为 newString；空的 newString 表示建议删除；可选的 comment 用于说明原因，并作为 Agent 的回复发布在建议评论串中），由他人在编辑器中接受或拒绝；以 Agent 身份回复；或解决评论串。添加评论、提出建议、回复和解决评论串都需要 OAuth 会话，并针对 branch 上的评论串操作；即使部署分支上的编辑需要拉取请求，这些操作在部署分支上也能进行。
• read_inbox：列出连接用户在某个项目中的仪表板收件箱内容（评论和提及、建议的编辑、与该用户共享的私有页面和文件夹），按最近活动时间从新到旧排列，默认只列出未处理项目。可用 state、section、filter、dateFrom 和 dateTo 缩小范围；将 nextCursor 作为 cursor 传入，以获取较早的项目。对于 target.thread 尚未解决且不在私有页面上的项目，请对 target.thread.filePath 调用 read_comments，并对 target.thread.branch 调用 reply_to_comment。此工具为只读；需要 OAuth 会话。
• list_nodes / create_node / update_node / move_node / delete_node：管理导航树。如果调用 create_node、update_node、move_node 或 delete_node 后导航无效（例如，根目录中某个页面与标签页并列），响应会包含 navigationErrors 字段。请在调用 publish 前修复这些错误，因为 Mintlify 可能会在已发布的导航中丢弃无效节点。如果 branch 上的 path 已有页面，create_node 会将新内容写入该页面，保留其在导航中的位置，并返回 updated: true。
• update_config — 更改顶层 docs.json 字段（主题、颜色、徽标、导航栏、页脚、重定向、集成、SEO）。它无法设置 navigation；请改用节点工具。无效配置会整体被拒绝。
• upload_file / finalize_file_upload：上传本地文件。若要将图片添加到 branch，请调用 upload_file 并传入目标 path（例如 images/dashboard.png）、contentType 和精确的字节数 size。将文件字节 PUT 到返回的 uploadUrl，并附上返回的 headers，然后调用 finalize_file_upload，传入 uploadId 和相同的 path。在 MDX 中或 docs.json 的 logo、favicon 字段中使用返回的 src。上传到已有的 path 会替换图片。只有徽标和 favicon 上传可以使用 SVG：对于 docs.json 的 logo 或 favicon，请在两个工具中都传入 purpose: "logo"。页面图片不能使用 SVG。图片会在调用 publish 时与其他编辑一同发布。若要从本地文件写入大型页面，请调用 upload_file，传入 .md 或 .mdx 格式的 path 和 contentType: "text/markdown"（无需传入 branch），然后 PUT 文件；接着在 10 分钟内，将 uploadId 代替 content 传给 write_page，或作为 data.uploadId 传给 create_node；无需调用 finalize_file_upload。每个 uploadId 只能使用一次。
• 项目管理工具：使用 get_deployment_settings、get_analytics_report、get_analytics_schema、query_analytics、get_workflows 和 list_repos_and_prs 读取信息。使用 update_deployment_settings、manage_custom_domain、manage_git_source、manage_access_auth、manage_workflow、manage_workflow_prs 和 manage_members_sharing 写入信息。传入 subdomain（组织级连接执行写入时必填；省略时，读取操作默认使用连接中唯一的项目；读取工具也接受最多包含 25 个项目的 subdomains）以及一个 request 对象；其中的 action（或 report）用于选择操作。写入会立即应用到线上项目并返回更新后的 state，因此请先确认预期更改。
• diff — 查看 branch 相对于部署分支的所有更改。
• status — 列出 branch 上尚未发布的已编辑文件、docs.json 键和导航更改。在部署分支上，仅列出你的更改。
• publish — 使用 title 发布 branch。仅当用户要求发布、交付或合并时才调用，编辑后切勿自行调用。在部署分支上，仅提交你尚未提交的更改。在其他分支上，提交所有待处理更改并返回该分支的拉取请求；如果尚无拉取请求，则创建一个。仅当用户提出要求且允许编辑部署分支时，才传入 merge: true 以同时合并该拉取请求；否则会返回 merge_not_allowed，并保持拉取请求打开。publish 会忽略 mode。如果没有待提交的更改，也没有拉取请求，则返回 no_pending_changes。响应中包含 editorUrl，可打开第一个新建或更新的页面。更改进入部署分支后，还会返回 commitSha 和 deployment 对象。
• deployment_status — 检查已发布的更改是否已上线。传入 publish 返回的 commitSha，或省略该参数以检查最新部署。返回 state（pending、queued、building、live、not_live、failed 或 skipped）、live 布尔值和 message。只有当 live 为 true 时，更改才算上线。大约每 30 秒再次检查一次；如果状态为 failed、not_live（网站仍在提供较早的版本）或 skipped，请报告 message。
• discard — 在部署分支上，仅还原你尚未提交的更改。在其他分支上，仅当该分支由你创建时才删除分支并关闭其拉取请求；否则不做任何更改。

私有页面（仅限工作区项目；其他项目会返回 private_pages_unavailable）：list_nodes 接受 visibility: "private"，用于列出 OAuth 用户可访问的私有页面和文件夹（会忽略其他筛选条件，并返回每个节点的 role）。read、edit_page、write_page、update_node 和 delete_node 接受 private-page-<uuid> 或 private-folder-<uuid> 节点 ID；create_node 接受 visibility: "private"，且 data.type 为 "page" 或 "group"。私有页面操作需要 OAuth 会话（管理型 MCP 会拒绝客户端令牌和机器间令牌），无需 branch，并强制执行角色要求：读取需要 read 权限，写入和更新需要 editor 或更高权限，删除需要 manager 权限。创建节点的调用者将成为该节点的 manager。

每个分支只专注于一项更改。较小的分支更便于审查拉取请求。打开 editorUrl 查看更改的实时渲染效果。优先使用 create_node 或 publish 返回的页面级 editorUrl，而不是 create_branch 返回的链接。

开始之前

Mintlify 经常变化，因此不要依赖记忆中的信息。如果本技能未涵盖某项内容，请通过 Mintlify Search MCP 服务或访问 https://mintlify.com/docs 查看最新文档。每个文档页面都有对应的 Markdown 版本，只需在其 URL 后加上 .md（例如 https://mintlify.com/docs/organize/navigation.md）；https://mintlify.com/docs/llms.txt 则列出了所有页面；请获取这些文件，而不是 HTML 页面。

开始大量内容工作之前，请阅读产品背景，并检查是否存在 .mintlify/product-brief.md。

首先阅读项目的 docs.json 文件。它定义了网站的导航、主题、颜色和配置。

如需更改外观或浏览器行为，请阅读自定义脚本。

创建新页面之前，请先搜索现有内容。你可能需要更新现有页面、添加章节，或链接到现有内容，而不是重复创建。

阅读 2 到 3 个相似页面，以匹配网站的语气、结构和格式。

文件格式

Mintlify 使用带有 YAML 前置元数据的 MDX 文件（.mdx 或 .md）。

project/
├── docs.json           # Site configuration (required)
├── index.mdx
├── quickstart.mdx
├── guides/
│   └── example.mdx
├── openapi.yml         # API specification (optional)
├── images/             # Static assets
│   └── example.png
└── snippets/           # Reusable components
    └── component.jsx

文件命名

• 遵循目录中的现有命名模式
• 如果没有现有文件，或文件命名模式不一致，请使用 kebab-case：getting-started.mdx
• 将新页面添加到 docs.json 导航中，否则它们不会显示在侧边栏

内部链接

• 使用不带文件扩展名的根相对路径：/getting-started/quickstart
• 内部页面不要使用相对路径（../）或绝对 URL

图片

将图片存放在 images/ 目录中，并使用根相对路径引用。所有图片都必须添加描述性替代文本。

Mintlify 会自动优化存储在仓库中并使用根相对路径引用的图片：支持时会提供 AVIF 或 WebP 格式，压缩图片，生成宽度最大为 2500px 的缩放版本，并添加宽度和高度。请勿自行转换或缩放这些图片。GIF、SVG 和 ICO 文件、通过绝对 URL 引用的图片，以及认证页面上的图片不会经过优化，因此添加 GIF 和托管在外部的图片前，请先进行压缩。

![Dashboard showing analytics overview](/images/dashboard.png)

页面 frontmatter

在 frontmatter 中填写 title、description 和 keywords。严格来说，title 是可选的（如果省略，Mintlify 会根据文件路径自动生成标题），但请明确设置，以提高清晰度并优化 SEO。

---
title: "Clear, descriptive title"
description: "Concise summary for SEO and navigation."
keywords: ["relevant", "search", "terms"]
---

常用 frontmatter 字段

字段	类型	说明
title	string	导航栏和浏览器标签页中的页面标题。如果省略，会根据路径自动生成。
description	string	用于 SEO 的简短描述，显示在标题下方。
sidebarTitle	string	侧边栏导航中显示的简短标题。
icon	string	Lucide、Font Awesome 或 Tabler 图标名称。也接受单个表情符号、URL 或文件路径。
tag	string	侧边栏中显示在页面标题旁的标签（例如，“NEW”）。
hidden	boolean	从侧边栏中移除。页面仍可通过 URL 访问。
mode	string	页面布局：default、wide、custom、frame、center、assistant。
keywords	array	用于站内搜索和 SEO 的搜索词。
api	string	交互式演练场的 API 端点（例如，"POST /users"）。
openapi	string	OpenAPI 端点引用（例如，"GET /endpoint"）。

如需查看完整列表，包括 searchable、boost、deprecated、related、groups 等字段，请阅读 页面。

组件快速参考

以下是最常用的组件。如需了解完整属性和全部 26 个组件，请阅读 组件。

提示框

<Note>Supplementary information, safe to skip.</Note>
<Info>Helpful context such as permissions or prerequisites.</Info>
<Tip>Recommendations or best practices.</Tip>
<Warning>Potentially destructive actions or important caveats.</Warning>
<Check>Success confirmation or completed status.</Check>
<Danger>Critical warnings about data loss or breaking changes.</Danger>

步骤

<Steps>
  <Step title="First step">
    Instructions for step one.
  </Step>
  <Step title="Second step">
    Instructions for step two.
  </Step>
</Steps>

标签页和代码组

<Tabs>
  <Tab title="npm">
    ```bash
    npm install package-name
    ```
  </Tab>
  <Tab title="yarn">
    ```bash
    yarn add package-name
    ```
  </Tab>
</Tabs>

<CodeGroup>

```javascript example.js
const greeting = "Hello, world!";
```

```python example.py
greeting = "Hello, world!"
```

</CodeGroup>

卡片和列

<Columns cols={2}>
  <Card title="First card" icon="rocket" href="/quickstart">
    Card description text.
  </Card>
  <Card title="Second card" icon="book" href="/guides">
    Card description text.
  </Card>
</Columns>

使用 <Columns> 将卡片（或其他内容）排列成网格。cols 可设为 1-4。

折叠面板

<AccordionGroup>
  <Accordion title="First section">Content one.</Accordion>
  <Accordion title="Second section">Content two.</Accordion>
</AccordionGroup>

CLI 命令

使用 npm i -g mint 安装。常用命令：mint dev（本地预览）、mint validate、mint broken-links、mint a11y、mint score、mint analytics（流量、搜索、反馈和助手对话；适用于 Pro 和 Enterprise 计划）、mint new、mint signup、mint instructions（完成特定任务的当前指南）。如需查看完整标志和子命令，请阅读 CLI 命令。

编辑页面后，运行 mint validate --no-build --format json 快速检查，并运行 mint validate --fix 应用自动修复。推送前请运行完整的 mint validate。

写作规范

• 使用第二人称（“你”）。
• 使用主动语态和直接的措辞。
• 标题使用句首字母大写格式（“入门指南”，而非“入门指南”）。
• 代码块标题使用句首字母大写格式。
• 所有代码块都必须标注语言。
• 所有图片都必须添加描述性替代文本。
• 不要使用营销语言、填充语或表情符号。
• 保持代码示例简单、实用且经过测试。

常见错误

• 使用 mint.json——它已弃用。配置文件始终是 docs.json。
• 代码块缺少语言标签（使用 ```python，而不是 ```）。
• 使用相对路径（../page），而不是以根目录为基准的路径（/section/page）。
• 忘记将新页面添加到 docs.json 导航中。
• 图片没有替代文本。
• 在内部链接中添加文件扩展名（使用 /page，而不是 /page.mdx）。