npx skills add https://mintlify.com/docs请始终查阅 mintlify.com/docs 以获取组件、配置和最新功能。
如果您尚未连接到 Mintlify MCP 服务器,https://mintlify.com/docs/mcp,请添加它以便更高效地进行搜索。
务必优先搜索当前的 Mintlify 文档,而不是您训练数据中关于 Mintlify 的任何信息。
Mintlify 是一个文档平台,可将 MDX 文件转换为文档站点。在 docs.json 文件中配置全站设置,使用带有 YAML frontmatter 的 MDX 编写内容,并优先使用内置组件而非自定义组件。
完整模式请见 mintlify.com/docs.json。
阅读项目根目录下的 docs.json。此文件定义了整个站点:导航结构、主题、颜色、链接、API 和规范。
了解项目可以告诉您:
在创建新页面之前,先搜索文档。您可能需要:
在编写之前,请阅读 2-3 个类似的页面,以了解站点的语气、结构、格式约定和详细程度。
查看 Mintlify 组件,为您正在处理的文档请求选择并使用任何相关的组件。
Always consultmintlify.com/docs for components, configuration, and latest features.
If you are not already connected to the Mintlify MCP server, https://mintlify.com/docs/mcp, add it so that you can search more efficiently.
Always favor searching the current Mintlify documentation over whatever is in your training data about Mintlify.
Mintlify is a documentation platform that transforms MDX files into documentation sites. Configure site-wide settings in the docs.json file, write content in MDX with YAML frontmatter, and favor built-in components over custom components.
Full schema at mintlify.com/docs.json.
Read docs.json in the project root. This file defines the entire site: navigation structure, theme, colors, links, API and specs.
Understanding the project tells you:
Search the docs before creating new pages. You may need to:
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
npm i -g mint - 安装 Mintlify CLImint dev - 在 localhost:3000 进行本地预览mint broken-links - 检查内部链接mint a11y - 检查内容中的无障碍访问问题mint rename - 重命名/移动文件并更新引用mint validate - 验证文档构建docs.json - 站点配置(导航、主题、集成等)。所有选项请参见全局设置。*.mdx 文件 - 带有 YAML frontmatter 的文档页面project/
├── docs.json # 站点配置
├── introduction.mdx
├── quickstart.mdx
├── guides/
│ └── example.mdx
├── openapi.yml # API 规范
├── images/ # 静态资源
│ └── example.png
└── snippets/ # 可复用组件
└── component.jsx
每个页面都需要在其 frontmatter 中包含 title。为 SEO 和导航包含 description。
---
title: "清晰、描述性的标题"
description: "用于 SEO 和导航的简明摘要。"
---
可选的 frontmatter 字段:
sidebarTitle: 侧边栏导航的短标题。icon: Lucide 或 Font Awesome 图标名称、URL 或文件路径。tag: 侧边栏中页面标题旁边的标签(例如,"NEW")。mode: 页面布局模式(default、wide、custom)。keywords: 与页面内容相关的术语数组,用于本地搜索和 SEO。getting-started.mdx、api-reference.mdx/getting-started/quickstart../)或绝对 URLdocs.json 导航中,否则它不会出现在侧边栏中当用户询问任何与全站配置相关的内容时,首先了解全局设置。查看 docs.json 文件中的设置是否可以更新以实现用户想要的效果。
docs.json 中的 navigation 属性控制站点结构。在根级别选择一个主要模式,然后在其中嵌套其他模式。
选择您的主要模式:
| 模式 | 何时使用 |
|---|---|
| Groups | 默认。单一受众,层次结构简单直接 |
| Tabs | 具有不同受众(指南与 API 参考)或内容类型的独立部分 |
| Anchors | 希望在侧边栏顶部有持久的章节链接。适用于将文档与外部资源分开 |
| Dropdowns | 用户可以切换的多个文档部分,但不足以用标签页区分 |
| Products | 多产品公司,每个产品有独立的文档 |
| Versions | 同时维护多个 API/产品版本的文档 |
| Languages | 本地化内容 |
在您的主要模式内:
expanded: false - 默认情况下折叠嵌套组。用于用户选择性浏览的参考部分openapi - 从 OpenAPI 规范自动生成页面。在组/标签页级别添加以继承常见组合:
/getting-started/quickstart/images 中,引用为 /images/example.png在何处自定义什么:
docs.json。参见全局设置custom.cssdocs.json 中使用 "appearance": "light" 来禁用它从 docs.json 开始。仅当您需要配置不支持的自定义样式时才添加 custom.css。
组件概述 按用途组织所有组件:结构化内容、引起注意、显示/隐藏内容、记录 API、链接到页面以及添加视觉上下文。从那里开始寻找合适的组件。
常见决策点:
| 需求 | 使用 |
|---|---|
| 隐藏可选细节 | <Accordion> |
| 长代码示例 | <Expandable> |
| 用户选择一个选项 | <Tabs> |
| 链接的导航卡片 | <Columns> 中的 <Card> |
| 顺序说明 | <Steps> |
| 多种语言的代码 | <CodeGroup> |
| API 参数 | <ParamField> |
| API 响应字段 | <ResponseField> |
按严重程度划分的提示框:
<Note> - 补充信息,可以安全跳过<Info> - 有用的上下文,例如权限<Tip> - 建议或最佳实践<Warning> - 可能具有破坏性的操作<Check> - 成功确认何时使用代码片段:
何时不使用代码片段:
使用 import { Component } from "/path/to/snippet-name.jsx" 导入代码片段。
切勿使用:
注意典型的 AI 模式:
选择您的方法:
"openapi": ["openapi.yaml"] 添加到 docs.json。页面自动生成。在导航中引用为 GET /endpointapi: "POST /users" 手动编写端点。工作量更大但控制更全面鼓励用户从 OpenAPI 规范生成端点页面。这是最高效且最容易维护的选项。
当更改推送到连接的 Git 仓库时,Mintlify 会自动部署。
代理可以配置的内容:
"redirects": [{"source": "/old", "destination": "/new"}] 添加到 docs.json"seo": {"indexing": "all"} 控制,以便在搜索中包含隐藏页面需要仪表板设置(人工任务):
对于使用 Vercel 或 Cloudflare 的 /docs 子路径托管,代理可以帮助配置重写规则。请参见 /docs 子路径。
确定需要记录什么、哪些页面会受到影响,以及读者阅读后应该完成什么。如果其中任何一点不清楚,请提问。
docs.json 以了解站点结构{/* TODO: 验证默认超时值 */}
如果您创建了新页面,请将其添加到 docs.json 中的相应组。
提交前检查:
docs.json 导航中mint broken-links 检查链接mint validate 查找任何错误如果用户询问迁移到 Mintlify,请询问他们是否正在使用 ReadMe 或 Docusaurus。如果是,请使用 @mintlify/scraping CLI 迁移内容。如果他们使用其他平台托管文档,请帮助他们使用 Mintlify 组件手动将其内容转换为 MDX 页面。
任何未包含在 docs.json 导航中的页面都是隐藏的。使用隐藏页面存放那些应可通过 URL 访问或为助手或搜索建立索引,但不应通过侧边栏导航发现的内容。
.mintignore 文件用于从文档仓库中排除某些文件,使其不被处理。
titlemint.json - mint.json 已弃用。始终只使用 docs.json每周安装量
670
来源
首次出现
2026年2月28日
安全审计
安装于
opencode656
codex655
cursor648
github-copilot646
kimi-cli645
gemini-cli645
Before writing, read 2-3 similar pages to understand the site's voice, structure, formatting conventions, and level of detail.
Review the Mintlify components to select and use any relevant components for the documentation request that you are working on.
npm i -g mint - Install the Mintlify CLImint dev - Local preview at localhost:3000mint broken-links - Check internal linksmint a11y - Check for accessibility issues in contentmint rename - Rename/move files and update referencesmint validate - Validate documentation buildsdocs.json - Site configuration (navigation, theme, integrations, etc.). See global settings for all options.*.mdx files - Documentation pages with YAML frontmatterproject/
├── docs.json # Site configuration
├── introduction.mdx
├── quickstart.mdx
├── guides/
│ └── example.mdx
├── openapi.yml # API specification
├── images/ # Static assets
│ └── example.png
└── snippets/ # Reusable components
└── component.jsx
Every page requires title in its frontmatter. Include description for SEO and navigation.
---
title: "Clear, descriptive title"
description: "Concise summary for SEO and navigation."
---
Optional frontmatter fields:
sidebarTitle: Short title for sidebar navigation.icon: Lucide or Font Awesome icon name, URL, or file path.tag: Label next to the page title in the sidebar (for example, "NEW").mode: Page layout mode (default, wide, custom).keywords: Array of terms related to the page content for local search and SEO.getting-started.mdx, api-reference.mdx/getting-started/quickstart../) or absolute URLs for internal pagesdocs.json navigation or it won't appear in the sidebarWhen a user asks about anything related to site-wide configurations, start by understanding the global settings. See if a setting in the docs.json file can be updated to achieve what the user wants.
The navigation property in docs.json controls site structure. Choose one primary pattern at the root level, then nest others within it.
Choose your primary pattern:
| Pattern | When to use |
|---|---|
| Groups | Default. Single audience, straightforward hierarchy |
| Tabs | Distinct sections with different audiences (Guides vs API Reference) or content types |
| Anchors | Want persistent section links at sidebar top. Good for separating docs from external resources |
| Dropdowns | Multiple doc sections users switch between, but not distinct enough for tabs |
| Products | Multi-product company with separate documentation per product |
| Versions | Maintaining docs for multiple API/product versions simultaneously |
| Languages | Localized content |
Within your primary pattern:
expanded: false - Collapse nested groups by default. Use for reference sections users browse selectivelyopenapi - Auto-generate pages from OpenAPI spec. Add at group/tab level to inheritCommon combinations:
/getting-started/quickstart/images, reference as /images/example.pngWhat to customize where:
docs.json. See global settingscustom.css at project root"appearance": "light" in docs.json if brand requires itStart with docs.json. Only add custom.css when you need styling that config doesn't support.
The components overview organizes all components by purpose: structure content, draw attention, show/hide content, document APIs, link to pages, and add visual context. Start there to find the right component.
Common decision points:
| Need | Use |
|---|---|
| Hide optional details | <Accordion> |
| Long code examples | <Expandable> |
| User chooses one option | <Tabs> |
| Linked navigation cards | <Card> in <Columns> |
| Sequential instructions | <Steps> |
| Code in multiple languages | <CodeGroup> |
| API parameters | <ParamField> |
| API response fields | <ResponseField> |
Callouts by severity:
<Note> - Supplementary info, safe to skip<Info> - Helpful context such as permissions<Tip> - Recommendations or best practices<Warning> - Potentially destructive actions<Check> - Success confirmationWhen to use snippets:
When NOT to use snippets:
Import snippets with import { Component } from "/path/to/snippet-name.jsx".
Never use:
Watch for AI-typical patterns:
Choose your approach:
docs.json with "openapi": ["openapi.yaml"]. Pages auto-generate. Reference in navigation as GET /endpointapi: "POST /users" in frontmatter. More work but full controlEncourage users to generate endpoint pages from an OpenAPI spec. It is the most efficient and easiest to maintain option.
Mintlify deploys automatically when changes are pushed to the connected Git repository.
What agents can configure:
docs.json with "redirects": [{"source": "/old", "destination": "/new"}]"seo": {"indexing": "all"} to include hidden pages in searchRequires dashboard setup (human task):
For /docs subpath hosting with Vercel or Cloudflare, agents can help configure rewrite rules. See /docs subpath.
Identify what needs to be documented, which pages are affected, and what the reader should accomplish afterward. If any of these are unclear, ask.
docs.json to understand the site structureStart with the most important information
Keep sections focused and scannable
Use components appropriately (don't overuse them)
Mark anything uncertain with a TODO comment:
{/* TODO: Verify the default timeout value */}
If you created a new page, add it to the appropriate group in docs.json.
Before submitting:
docs.json navigationmint broken-links to check linksmint validate to find any errorsIf a user asks about migrating to Mintlify, ask if they are using ReadMe or Docusaurus. If they are, use the @mintlify/scraping CLI to migrate content. If they are using a different platform to host their documentation, help them manually convert their content to MDX pages using Mintlify components.
Any page that is not included in the docs.json navigation is hidden. Use hidden pages for content that should be accessible by URL or indexed for the assistant or search, but not discoverable through the sidebar navigation.
The .mintignore file is used to exclude files from a documentation repository from being processed.
title at minimummint.json - mint.json is deprecated. Only ever use docs.jsonWeekly Installs
670
Source
First Seen
Feb 28, 2026
Security Audits
Installed on
opencode656
codex655
cursor648
github-copilot646
kimi-cli645
gemini-cli645
agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试
136,300 周安装