mintlify

Mintlify 参考

Mintlify 项目工作参考。本文件涵盖适用于所有任务的基本内容。有关特定主题的详细参考，请阅读下方参考索引中列出的文件。

参考索引

仅在任务需要时阅读这些文件。它们位于本文件旁边的 reference/ 目录中。

文件	阅读时机
reference/components.md	添加或修改组件（提示框、卡片、步骤、标签页、折叠面板、代码组、字段、框架、图标、工具提示、徽章、树形结构、mermaid、MDX、面板、提示词、颜色、图块、更新、视图）。也涵盖表格列宽。
reference/configuration.md	更改 docs.json 设置（主题、颜色、徽标、字体、外观、导航栏、页脚、横幅、重定向、SEO、集成、API 配置）。也涵盖代码片段、隐藏页面、.mintignore、自定义 CSS/JS，以及完整的 frontmatter 字段表。
reference/navigation.md	修改网站导航结构（分组、标签、锚点、下拉菜单、产品、版本、语言、OpenAPI，以及导航中的 SDK 参考）。
reference/api-docs.md	设置 API 文档（OpenAPI、AsyncAPI、MDX 手动 API 页面、扩展、playground 配置）。
reference/cli.md	运行常见 CLI 命令（dev、validate、add-domain、analytics、score、broken-links、a11y、format 和 config）及其主要标志。
reference/product-context.md	开始大量内容工作之前（新网站、大范围重构、首次设置章节）——检查并维护 .mintlify/product-brief.md。
reference/customization/index.md	使用 CSS、JavaScript、React 代码片段、选择器或 CSS 变量自定义外观或浏览器行为。
reference/writing.md	创建页面或撰写超过一两句话之前：不得臆造规则、页面创建和编辑步骤、质量标准、受众、标题和描述、链接。
reference/publishing-and-review.md	发布、分支和拉取请求、“是否已上线”问题、撤销更改，以及通过建议和评论审核页面。
reference/project-settings.md	读取或更改控制面板设置（域名、git 源、身份验证、成员、工作流、搜索、附加组件）、了解没有工具涵盖的设置，以及分析相关问题。
reference/site-building.md	构建或迁移整个网站、一个章节或多个页面：研究规模、生成顺序、落地页、常见网站类型的结构、迁移规则。

启动新的文档站点

如果用户想要创建新的文档站点、发布文档，或还没有 docs.json，请自行运行此工作流。仅在需要用户提供你无法提供的信息或批准时，才询问用户。可以运行终端命令时，不要让用户去浏览器优先的快速入门页面。

1. 检查 node --version（v20.17.0 或更高版本）。运行 mint --version；如果未安装，请运行 npm i -g mint 安装。如果已安装，请运行 mint update。
2. 运行 mint status。如果显示了组织，请使用现有账户。否则，询问用户是否有 Mintlify 账户。如果有，请运行 mint login。如果没有，请询问用户的名字、姓氏、公司和电子邮件，并在后台运行 mint signup --firstName <first> --lastName <last> --company <company> --email <email>。该命令会等待电子邮件验证。告知用户点击验证链接，并在浏览器中完成入门流程。切勿编造注册信息。
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 可以正常加载。

用户只需使用浏览器进行电子邮件验证、OAuth 批准和连接 GitHub。

没有本地仓库

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

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

从其他平台迁移

迁移 Docusaurus、GitBook、ReadMe、Fern 或 Document360 时，请使用 Mintlify Search MCP 服务读取 https://mintlify.com/docs/migration/<platform> 中对应的指南（例如 docusaurus）。迁移其他平台时，请遵循 https://mintlify.com/docs/migration/manual。抓取工具仅支持简单的公开站点。复杂站点应从源文件迁移。移植规则见 reference/site-building.md。

MCP 服务

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

Mintlify 搜索

对 Mintlify 已发布文档的只读访问。当参考文件未涵盖特定细节、需要获取最新组件签名或验证不熟悉的配置选项时使用。

工具：

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

Mintlify 管理

对 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 放弃更改）。直接编辑部署分支时，请传入该分支。如果项目要求使用拉取请求（Push directly to your deploy branch 已关闭、分支保护要求拉取请求、部署分支编辑已锁定，或连接使用客户端或机器到机器令牌），则会拒绝对部署分支的编辑，并说明原因，且不会进行任何更改。请调用 create_branch，并将其 branchName 作为 branch 传入。 关键工具：

• create_branch — 从部署分支创建一个新分支，并使用 title 为该分支及其拉取请求命名。返回 branchName 和分支级别的 editorUrl，可用于实时预览更改。在分支上，Mintlify 会在最后一次更改约 15 秒后自动提交编辑；首次提交会创建一个拉取请求。
• list_branches — 列出现有分支；将其中任意分支作为 branch 传入。不存在的分支会被拒绝。
• list_deployments — 查明此连接可访问哪些项目。
• read / search — 获取页面的 MDX，或搜索各个页面。
• edit_page / write_page：应用定向编辑或覆盖页面。edit_page 接收 oldString 和 newString 以执行一次替换，或接收最多包含 100 项替换的 edits 列表，并按顺序应用；如果任何一项编辑失败，则不会应用任何更改。对于编辑器会丢弃的标记（例如 <script>、<style>、事件处理程序或 JavaScript 表达式），两者都会返回 notRendered，并说明应改用什么内容。
• read_comments / add_comment / suggest_edit / reply_to_comment / resolve_comment：读取页面上编辑器中未解决的评论串，在指定文本上开启评论串，提出一项修订跟踪建议（oldString 到 newString；空的 newString 表示建议删除；可选的 comment 用于说明原因，并作为 Agent 在建议评论串中的回复发布），由他人在编辑器中接受或拒绝该建议，以 Agent 身份回复，或解决评论串。添加评论、提出建议、回复和解决评论串都需要 OAuth 会话，并会对 branch 的评论串执行操作；即使部署分支上的编辑需要拉取请求，这些操作仍可在部署分支上进行。
• 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）。
• upload_image / finalize_image_upload — 将本地图片添加到 branch。调用 upload_image 时，传入目标 path（例如 images/dashboard.png）、contentType 和以字节为单位的准确 size。使用返回的 headers，通过 PUT 将文件字节上传到返回的 uploadUrl，然后调用 finalize_image_upload，并传入 uploadId 和相同的 path。在 MDX 中，或在 docs.json 的 logo 或 favicon 字段中使用返回的 src。上传到已存在的 path 会替换图片。Mintlify 的徽标和网站图标仅接受 SVG，因此请向两个工具都传入 purpose: "logo"。图片会随你在 publish 时发布的其他编辑一起发布。
• 项目管理工具 — 使用 get_deployment_settings、get_analytics_report、get_workflows 和 list_repos_and_prs 读取信息。使用 update_deployment_settings、manage_custom_domain、manage_git_source、manage_access_auth、manage_workflow 和 manage_members_sharing 写入信息。传入 subdomain（组织级连接必填；读取工具也接受最多 25 个子域名的 subdomains）以及一个 request 对象，其中的 action（或 report）用于选择操作。写入会立即应用到实时项目，并返回更新后的 state，因此请先确认预期的更改。 私有页面：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。
• 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 — 在部署分支上，仅还原你的待处理更改。在其他分支上，仅当该分支由你创建时，才会删除该分支并关闭其拉取请求；否则不会更改任何内容。

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

开始之前

Mintlify 经常更新，因此不要依赖记忆中的信息。如果此技能中没有说明某项细节，请使用 Mintlify Search MCP server 或访问 https://mintlify.com/docs 查阅当前文档。

在开展大量内容工作之前，请阅读 reference/product-context.md，并检查是否存在 .mintlify/product-brief.md。

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

如需更改外观或浏览器行为，请阅读 reference/customization/index.md。

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

阅读 2-3 个类似页面，以符合网站的语气、结构和格式。

文件格式

Mintlify 使用 MDX 文件（.mdx 或 .md），并采用 YAML 前置元数据。

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。
keywords	array	用于站内搜索和 SEO 的搜索词。
api	string	交互式 Playground 的 API 端点（例如，"POST /users"）。
openapi	string	OpenAPI 端点引用（例如，"GET /endpoint"）。

如需查看包括 searchable、boost、deprecated、related、groups 等在内的完整列表，请阅读 reference/configuration.md。

组件快速参考

以下是最常用的组件。如需查看全部 26 个组件及其所有属性，请阅读 reference/components.md。

提示框

<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。如需查看完整标志和子命令，请阅读 reference/cli.md。

写作规范

• 使用第二人称（“你”）。
• 使用主动语态和直接的表达。
• 标题使用句式大小写（“Getting started”，而非“Getting Started”）。
• 代码块标题使用句式大小写。
• 所有代码块都必须标注语言。
• 所有图片都必须提供描述性替代文本。
• 不使用营销用语、填充语或表情符号。
• 代码示例应简单、实用且经过测试。

常见错误

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