mintlify

Mintlify 参考

使用 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 安装 CLI。

本地开发

• mint dev — 在 localhost:3000 启动本地预览。--no-open 可跳过启动浏览器。--groups <names> 可模拟用户组。
• mint validate — 严格验证构建；遇到警告或错误时返回非零退出码。
• mint export — 导出用于气隙部署的静态站点压缩包。--output <file> 可设置输出路径（默认值：export.zip）。

内容质量

• mint broken-links — 检查损坏的内部链接。--check-anchors 可验证 # 锚点。--check-external 可检查外部 URL。--check-snippets 可检查 <Snippet> 组件中的链接。
• mint a11y — 检查无障碍功能（替代文本、颜色对比度）。使用 --skip-contrast 或 --skip-alt-text 可缩小检查范围。

分析

• mint analytics stats — 查看关键绩效指标数据（浏览量、访客、搜索次数）。选项：--subdomain、--from、--to、--format（table/plain/json/graph）；使用 --agents/--humans 筛选流量，使用 --page 筛选单个路径。
• mint analytics search — 查看搜索分析数据。--query 可按搜索词子字符串筛选。
• mint analytics feedback — 查看反馈分析数据。--type（code 或 page）。
• mint analytics conversation list — 列出助手对话。
• mint analytics conversation view <id> — 查看单条对话。
• mint analytics conversation buckets list — 列出对话类别分组。
• mint analytics conversation buckets view <id> — 查看某个分组中的对话。

身份验证

• mint login — 验证你的 Mintlify 帐户。
• mint logout — 退出你的帐户。
• mint status — 显示当前身份验证状态。

配置

• mint config set <key> <value> — 持久化保存配置值。有效键：subdomain、dateFrom、dateTo。
• mint config get <key> — 读取已存储的配置值。
• mint config clear <key> — 移除已存储的配置值。

项目设置

• mint new [directory] — 搭建新的 Mintlify 文档站点。--theme 和 --name 可设置初始配置。
• mint workflow — 向文档仓库添加工作流。

维护

• mint update — 将 CLI 更新到最新版本。
• mint version — 显示已安装的 CLI 和客户端版本。

写作规范

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

常见错误

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