mintlify

Mintlify 参考

使用 Mintlify 构建文档的参考。本文件涵盖适用于所有任务的基础知识。如需了解特定主题的详细参考，请阅读下方参考索引中列出的文件。

参考索引

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

文件	阅读时机
reference/components.md	添加或修改组件（提示框、卡片、步骤、标签页、折叠面板、代码组、字段、框架、图标、工具提示、徽章、树形结构、mermaid、面板、提示词、颜色、平铺项、更新、视图）。
reference/configuration.md	更改 docs.json 设置（主题、颜色、徽标、字体、外观、导航栏、页脚、横幅、重定向、SEO、集成、API 配置）。还涵盖代码片段、隐藏页面、.mintignore、自定义 CSS/JS 以及完整的 frontmatter 字段表。
reference/navigation.md	修改网站导航结构（分组、标签页、锚点、下拉菜单、产品、版本、语言、导航栏中的 OpenAPI）。
reference/api-docs.md	设置 API 文档（OpenAPI、AsyncAPI、MDX 手动 API 页面、扩展、交互式演练场配置）。

开始之前

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

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

阅读 2-3 个类似页面，以匹配网站的风格、结构和格式。

文件格式

Mintlify 使用带有 YAML frontmatter 的 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/ 目录中。使用根相对路径引用。所有图片都必须包含描述性替代文本。

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

页面 frontmatter

每个页面的 frontmatter 都必须包含 title。为 SEO 添加 description 和 keywords。

---
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	否	交互式演练场的 API 端点（例如，"POST /users"）。
openapi	string	否	OpenAPI 端点引用（例如，"GET /endpoint"）。

常用组件快速参考

以下是最常用的组件。要查看全部 24 个组件的完整属性，请阅读 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!"

```

Cards and columns

<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 — 安装 Mintlify CLI。
• mint dev — 在 localhost:3000 上本地预览。
• mint broken-links — 检查内部链接。
• mint a11y — 检查无障碍问题。
• mint validate — 验证文档构建。
• mint upgrade — 从 mint.json 升级到 docs.json。

写作规范

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

常见错误

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