npx skills add https://github.com/mintlify/docs --skill mintlify使用 Mintlify 构建文档的参考。本文档涵盖了适用于每个任务的基本要素。关于特定主题的详细参考,请阅读下方参考索引中列出的文件。
仅当你的任务需要时才阅读这些文件。它们位于本文件旁边的 reference/ 目录中。要找到它们,请查看与本技能文件相同的目录(例如,.claude/skills/mintlify/reference/)。
| 文件 | 何时阅读 |
|---|---|
reference/components.md | 添加或修改组件(标注框、卡片、步骤、选项卡、手风琴、代码组、字段、框架、图标、工具提示、徽章、树状图、Mermaid 图表、面板、提示框、颜色、磁贴、更新、视图)。 |
reference/configuration.md | 更改 docs.json 设置(主题、颜色、徽标、字体、外观、导航栏、页脚、横幅、重定向、SEO、集成、API 配置)。还涵盖代码片段、隐藏页面、.mintignore、自定义 CSS/JS 以及完整的前言字段表。 |
reference/navigation.md |
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
| 修改站点导航结构(分组、选项卡、锚点、下拉菜单、产品、版本、语言、导航中的 OpenAPI)。 |
reference/api-docs.md | 设置 API 文档(OpenAPI、AsyncAPI、MDX 手动 API 页面、扩展、Playground 配置)。 |
首先阅读项目的 docs.json 文件。它定义了站点的导航、主题、颜色和配置。
在创建新页面之前,先搜索现有内容。你可能需要更新现有页面、添加章节或链接到现有内容,而不是重复创建。
阅读 2-3 个类似的页面,以匹配站点的语气、结构和格式。
Mintlify 使用带有 YAML 前言的 MDX 文件(.mdx 或 .md)。
project/
├── docs.json # 站点配置(必需)
├── index.mdx
├── quickstart.mdx
├── guides/
│ └── example.mdx
├── openapi.yml # API 规范(可选)
├── images/ # 静态资源
│ └── example.png
└── snippets/ # 可复用组件
└── component.jsx
getting-started.mdxdocs.json 导航中,否则它们不会出现在侧边栏中/getting-started/quickstart../)或绝对 URL将图片存储在 images/ 目录中。使用根相对路径引用。所有图片都需要描述性的替代文本。

每个页面都需要在其前言中包含 title。为 SEO 考虑,请包含 description 和 keywords。
---
title: "清晰、描述性的标题"
description: "用于 SEO 和导航的简洁摘要。"
keywords: ["相关", "搜索", "关键词"]
---
| 字段 | 类型 | 必需 | 描述 |
|---|---|---|---|
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")。 |
以下是最常用的组件。有关完整属性和全部 24 个组件,请阅读 reference/components.md。
<Note>补充信息,可以安全跳过。</Note>
<Info>有用的上下文,例如权限或先决条件。</Info>
<Tip>建议或最佳实践。</Tip>
<Warning>潜在破坏性操作或重要注意事项。</Warning>
<Check>成功确认或完成状态。</Check>
<Danger>关于数据丢失或破坏性更改的严重警告。</Danger>
<Steps>
<Step title="第一步">
第一步的说明。
</Step>
<Step title="第二步">
第二步的说明。
</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!"
```
<Columns cols={2}>
<Card title="第一张卡片" icon="rocket" href="/quickstart">
卡片描述文本。
</Card>
<Card title="第二张卡片" icon="book" href="/guides">
卡片描述文本。
</Card>
</Columns>
使用 <Columns> 在网格中排列卡片(或其他内容)。cols 接受 1-4 的值。
<AccordionGroup>
<Accordion title="第一部分">内容一。</Accordion>
<Accordion title="第二部分">内容二。</Accordion>
</AccordionGroup>
npm i -g mint — 安装 Mintlify CLI。mint dev — 在 localhost:3000 进行本地预览。mint broken-links — 检查内部链接。mint a11y — 检查可访问性问题。mint rename — 重命名/移动文件并更新引用。mint validate — 验证文档构建。mint upgrade — 从 mint.json 升级到 docs.json。../page)而不是根相对路径(/section/page)。docs.json 导航中。/page.mdx 而不是 /page)。每周安装量
122
代码仓库
GitHub 星标数
360
首次出现
2026年2月4日
安全审计
安装于
codex120
opencode120
github-copilot119
gemini-cli118
cursor116
claude-code108
Reference for building documentation with Mintlify. This file covers essentials that apply to every task. For detailed reference on specific topics, read the files listed in the reference index below.
Read these files only when your task requires them. They are in the reference/ directory next to this file. To find them, look in the same directory as this skill file (e.g., .claude/skills/mintlify/reference/).
| File | When to read |
|---|---|
reference/components.md | Adding or modifying components (callouts, cards, steps, tabs, accordions, code groups, fields, frames, icons, tooltips, badges, trees, mermaid, panels, prompts, colors, tiles, updates, views). |
reference/configuration.md | Changing docs.json settings (theme, colors, logo, fonts, appearance, navbar, footer, banner, redirects, SEO, integrations, API config). Also covers snippets, hidden pages, .mintignore, custom CSS/JS, and the complete frontmatter fields table. |
reference/navigation.md | Modifying site navigation structure (groups, tabs, anchors, dropdowns, products, versions, languages, OpenAPI in nav). |
reference/api-docs.md | Setting up API documentation (OpenAPI, AsyncAPI, MDX manual API pages, extensions, playground config). |
Read the project's docs.json file first. It defines the site's navigation, theme, colors, and configuration.
Search for existing content before creating new pages. You may need to update an existing page, add a section, or link to existing content rather than duplicating.
Read 2-3 similar pages to match the site's voice, structure, and formatting.
Mintlify uses MDX files (.mdx or .md) with YAML frontmatter.
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
getting-started.mdxdocs.json navigation or they won't appear in the sidebar/getting-started/quickstart../) or absolute URLs for internal pagesStore images in an images/ directory. Reference with root-relative paths. All images require descriptive alt text.

Every page requires title in its frontmatter. Include description and keywords for SEO.
---
title: "Clear, descriptive title"
description: "Concise summary for SEO and navigation."
keywords: ["relevant", "search", "terms"]
---
| Field | Type | Required | Description |
|---|---|---|---|
title | string | Yes | Page title in navigation and browser tabs. |
description | string | No | Brief description for SEO. Displays under the title. |
sidebarTitle | string | No | Short title for sidebar navigation. |
icon | string | No | Lucide, Font Awesome, or Tabler icon name. Also accepts a URL or file path. |
Below are the most commonly used components. For full props and all 24 components, read 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!";
greeting = "Hello, world!"
<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>
Use <Columns> to arrange cards (or other content) in a grid. cols accepts 1-4.
<AccordionGroup>
<Accordion title="First section">Content one.</Accordion>
<Accordion title="Second section">Content two.</Accordion>
</AccordionGroup>
npm i -g mint — Install the Mintlify CLI.mint dev — Local preview at localhost:3000.mint broken-links — Check internal links.mint a11y — Check for accessibility issues.mint rename — Rename/move files and update references.mint validate — Validate documentation builds.mint upgrade — Upgrade from mint.json to docs.json.../page) instead of root-relative (/section/page).docs.json navigation./page.mdx instead of /page).Weekly Installs
122
Repository
GitHub Stars
360
First Seen
Feb 4, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
codex120
opencode120
github-copilot119
gemini-cli118
cursor116
claude-code108
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
120,000 周安装
tag | string | No | Label next to page title in sidebar (e.g., "NEW"). |
hidden | boolean | No | Remove from sidebar. Page still accessible by URL. |
mode | string | No | Page layout: default, wide, custom, frame, center. |
keywords | array | No | Search terms for internal search and SEO. |
api | string | No | API endpoint for interactive playground (e.g., "POST /users"). |
openapi | string | No | OpenAPI endpoint reference (e.g., "GET /endpoint"). |