mintlify

Mintlify 参考

使用 Mintlify 构建文档的参考。本文档涵盖适用于所有任务的基本内容。有关特定主题的详细参考，请阅读下面参考索引中列出的文件。

参考索引

仅当您的任务需要时才阅读这些文件。它们位于此文件旁边的 reference/ 目录中。要找到它们，请查看与此技能文件相同的目录（例如 .claude/skills/mintlify/reference/）。

文件	何时阅读
reference/components.md	添加或修改组件（callouts、cards、steps、tabs、accordions、code groups、fields、frames、icons、tooltips、badges、trees、mermaid、panels、prompts、colors、tiles、updates、views）。
reference/configuration.md	更改 docs.json 设置（主题、颜色、logo、字体、外观、导航栏、页脚、横幅、重定向、SEO、集成、API 配置）。还涵盖 snippets、隐藏页面、.mintignore、自定义 CSS/JS 以及完整的 frontmatter 字段表。
reference/navigation.md	修改站点导航结构（groups、tabs、anchors、dropdowns、products、versions、languages、OpenAPI 在导航中）。
reference/api-docs.md	设置 API 文档（OpenAPI、AsyncAPI、MDX 手动 API 页面、扩展、playground 配置）。

开始之前

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

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

阅读 2-3 个类似页面以匹配站点的语气、结构和格式。

文件格式

Mintlify 使用带有 YAML frontmatter 的 MDX 文件（.mdx 或 .md）。

project/
├── docs.json           # 站点配置（必需）
├── index.mdx
├── quickstart.mdx
├── guides/
│   └── example.mdx
├── openapi.yml         # API 规范（可选）
├── images/             # 静态资源
│   └── example.png
└── snippets/           # 可复用组件
    └── component.jsx

文件命名

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

内部链接

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

图片

将图片存储在 images/ 目录中。使用根相对路径引用。所有图片都需要描述性替代文本。

![显示分析概览的仪表板](/images/dashboard.png)

页面 frontmatter

每个页面都需要在 frontmatter 中包含 title。包含 description 和 keywords 以优化 SEO。

---
title: "清晰、描述性的标题"
description: "用于 SEO 和导航的简洁摘要。"
keywords: ["相关", "搜索", "术语"]
---

常用 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"）。

快速组件参考

以下是最常用的组件。有关完整属性和所有 24 个组件，请阅读 reference/components.md。

Callouts

<Note>补充信息，可以跳过。</Note>
<Info>有用的上下文，例如权限或先决条件。</Info>
<Tip>建议或最佳实践。</Tip>
<Warning>可能具有破坏性的操作或重要注意事项。</Warning>
<Check>成功确认或完成状态。</Check>
<Danger>关于数据丢失或重大变更的关键警告。</Danger>

Steps

<Steps>
  <Step title="第一步">
    第一步的说明。
  </Step>
  <Step title="第二步">
    第二步的说明。
  </Step>
</Steps>

Tabs 和代码组

<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!"

</CodeGroup>

#### Cards 和列

```mdx
<Columns cols={2}>
  <Card title="第一张卡片" icon="rocket" href="/quickstart">
    卡片描述文本。
  </Card>
  <Card title="第二张卡片" icon="book" href="/guides">
    卡片描述文本。
  </Card>
</Columns>

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

Accordions

<AccordionGroup>
  <Accordion title="第一部分">内容一。</Accordion>
  <Accordion title="第二部分">内容二。</Accordion>
</AccordionGroup>

CLI 命令

• npm i -g mint — 安装 Mintlify CLI。
• mint dev — 在 localhost:3000 本地预览。
• mint broken-links — 检查内部链接。
• mint a11y — 检查可访问性问题。
• mint validate — 验证文档构建。
• mint upgrade — 从 mint.json 升级到 docs.json。

写作标准

• 第二人称（"你"）。
• 主动语态，直接语言。
• 标题使用句子大小写（"Getting started"，而不是 "Getting Started"）。
• 代码块标题使用句子大小写。
• 所有代码块必须带有语言标签。
• 所有图片必须带有描述性替代文本。
• 不使用营销语言、填充短语或表情符号。
• 保持代码示例简单、实用且经过测试。

常见错误

• 代码块缺少语言标签（使用 ```python，而不是 ```）。
• 使用相对路径（../page）而不是根相对路径（/section/page）。
• 忘记将新页面添加到 docs.json 导航中。
• 图片没有替代文本。
• 在内部链接中添加文件扩展名（/page.mdx 而不是 /page）。