mintlify

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Mintlify reference

Mintlify 参考指南

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.

使用Mintlify构建文档的参考指南。本文档涵盖适用于所有任务的核心内容。如需特定主题的详细参考，请阅读下方参考索引中列出的文件。

Reference index

参考索引

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).

仅在任务需要时阅读以下文件。它们位于此文件旁的

reference/

目录中。可在技能文件所在的同一目录中找到它们（例如：

.claude/skills/mintlify/reference/

）。

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

Before you start

开始之前

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.

请先阅读项目的

docs.json

文件。它定义了站点的导航、主题、颜色和配置。

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

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

File format

文件格式

Mintlify uses MDX files (

.mdx

.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

Mintlify 使用带有YAML前置元数据的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

File naming

文件命名

Match existing patterns in the directory
If no existing files or mixed file naming patterns, use kebab-case:
```
getting-started.mdx
```
Add new pages to
```
docs.json
```
navigation or they won't appear in the sidebar

匹配目录中的现有命名模式
如果没有现有文件或命名模式混杂，请使用短横线分隔命名（kebab-case）：
```
getting-started.mdx
```
需将新页面添加到
```
docs.json
```
的导航中，否则不会显示在侧边栏

Internal links

内部链接

Use root-relative paths without file extensions:
```
/getting-started/quickstart
```
Do not use relative paths (
```
../
```
) or absolute URLs for internal pages

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

Images

图片

Store images in an

images/

directory. Reference with root-relative paths. All images require descriptive alt text.

mdx

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

将图片存储在

images/

目录中。使用根相对路径引用。所有图片都需要描述性的替代文本。

mdx

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

Page frontmatter

页面前置元数据

Every page requires

title

in its frontmatter. Include

description

and

keywords

for SEO.

yaml

---
title: "Clear, descriptive title"
description: "Concise summary for SEO and navigation."
keywords: ["relevant", "search", "terms"]
---

每个页面的前置元数据中都需要包含

title

。为了SEO优化，建议包含

description

和

keywords

。

yaml

---
title: "Clear, descriptive title"
description: "Concise summary for SEO and navigation."
keywords: ["relevant", "search", "terms"]
---

Common frontmatter fields

常用前置元数字段

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.
`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"` ).

字段	类型	是否必填	描述
`title`	字符串	是	导航和浏览器标签中的页面标题。
`description`	字符串	否	用于SEO的简短描述。显示在标题下方。
`sidebarTitle`	字符串	否	侧边栏导航中使用的短标题。
`icon`	字符串	否	Lucide、Font Awesome或Tabler图标名称。也支持URL或文件路径。
`tag`	字符串	否	侧边栏页面标题旁的标签（例如："NEW"）。
`hidden`	布尔值	否	从侧边栏中移除。页面仍可通过URL访问。
`mode`	字符串	否	页面布局： `default` 、 `wide` 、 `custom` 、 `frame` 、 `center` 。
`keywords`	数组	否	用于内部搜索和SEO的搜索词。
`api`	字符串	否	交互式 playground的API端点（例如： `"POST /users"` ）。
`openapi`	字符串	否	OpenAPI端点引用（例如： `"GET /endpoint"` ）。

Quick component reference

常用组件参考

Below are the most commonly used components. For full props and all 24 components, read

reference/components.md

以下是最常用的组件。如需完整属性和全部24个组件的信息，请阅读

reference/components.md

。

Callouts

提示框

mdx

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

mdx

<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

步骤

mdx

<Steps>
  <Step title="First step">
    Instructions for step one.
  </Step>
  <Step title="Second step">
    Instructions for step two.
  </Step>
</Steps>

mdx

<Steps>
  <Step title="First step">
    Instructions for step one.
  </Step>
  <Step title="Second step">
    Instructions for step two.
  </Step>
</Steps>

Tabs and code groups

标签页和代码组

mdx

<Tabs>
  <Tab title="npm">
    ```bash
    npm install package-name
    ```
  </Tab>
  <Tab title="yarn">
    ```bash
    yarn add package-name
    ```
  </Tab>
</Tabs>

mdx

<CodeGroup>

```javascript example.js
const greeting = "Hello, world!";

python

greeting = "Hello, world!"

</CodeGroup> ```

mdx

<Tabs>
  <Tab title="npm">
    ```bash
    npm install package-name
    ```
  </Tab>
  <Tab title="yarn">
    ```bash
    yarn add package-name
    ```
  </Tab>
</Tabs>

mdx

<CodeGroup>

```javascript example.js
const greeting = "Hello, world!";

python

greeting = "Hello, world!"

</CodeGroup> ```

Cards and columns

卡片和列

mdx

<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.

mdx

<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的值。

Accordions

折叠面板

mdx

<AccordionGroup>
  <Accordion title="First section">Content one.</Accordion>
  <Accordion title="Second section">Content two.</Accordion>
</AccordionGroup>

mdx

<AccordionGroup>
  <Accordion title="First section">Content one.</Accordion>
  <Accordion title="Second section">Content two.</Accordion>
</AccordionGroup>

CLI commands

CLI 命令

```
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 validate
```
— Validate documentation builds.
```
mint upgrade
```
— Upgrade from
```
mint.json
```
to
```
docs.json
```
.

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

Writing standards

写作规范

Second-person voice ("you").
Active voice, direct language.
Sentence case for headings ("Getting started", not "Getting Started").
Sentence case for code block titles.
All code blocks must have language tags.
All images must have descriptive alt text.
No marketing language, filler phrases, or emoji.
Keep code examples simple, practical, and tested.

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

Common mistakes

常见错误

Missing language tag on a code block (use
```
```python
```
, not
```
```
```
).
Using relative paths (
```
../page
```
) instead of root-relative (
```
/section/page
```
).
Forgetting to add new pages to
```
docs.json
```
navigation.
Images without alt text.
Adding file extensions to internal links (
```
/page.mdx
```
instead of
```
/page
```
).

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