mintlify

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Mintlify best practices

Mintlify最佳实践

Always consult mintlify.com/docs for components, configuration, and latest features.

Always favor searching the current Mintlify documentation over whatever is in your training data about Mintlify.

Mintlify is a documentation platform that transforms MDX files into documentation sites. Configure site-wide settings in the

docs.json

file, write content in MDX with YAML frontmatter, and favor built-in components over custom components.

Full schema at mintlify.com/docs.json.

请始终查阅mintlify.com/docs获取组件、配置信息及最新功能。

请始终优先查阅当前Mintlify官方文档，而非训练数据中关于Mintlify的内容。

Mintlify是一款可将MDX文件转换为文档站点的文档平台。在

docs.json

文件中配置站点全局设置，使用带YAML前置元数据的MDX编写内容，优先使用内置组件而非自定义组件。

完整配置方案请查看mintlify.com/docs.json。

Before you write

写作前准备

Understand the project

了解项目架构

All documentation lives in the

docs/

directory in this repo. Read

docs.json

in that directory (

docs/docs.json

). This file defines the entire site: navigation structure, theme, colors, links, API and specs.

Understanding the project tells you:

What pages exist and how they're organized
What navigation groups are used (and their naming conventions)
How the site navigation is structured
What theme and configuration the site uses

所有文档都存储在仓库的

docs/

docs.json

文件（路径为

docs/docs.json

），该文件定义了整个站点的导航结构、主题、配色、链接、API及规范等内容。

了解项目架构能让你清楚：

现有页面及其组织方式
使用的导航分组及其命名规范
站点导航的结构
站点使用的主题与配置

Check for existing content

检查现有内容

Search the docs before creating new pages. You may need to:

Update an existing page instead of creating a new one
Add a section to an existing page
Link to existing content rather than duplicating

创建新页面之前，请先搜索现有文档。你可能需要：

更新现有页面而非创建新页面
向现有页面添加新章节
链接到现有内容而非重复编写

Read surrounding content

参考同类内容

Before writing, read 2-3 similar pages to understand the site's voice, structure, formatting conventions, and level of detail.

写作前，请阅读2-3篇同类页面，以熟悉站点的语气、结构、格式规范及内容详细程度。

Understand Mintlify components

熟悉Mintlify组件

Review the Mintlify components to select and use any relevant components for the documentation request that you are working on.

请查看Mintlify的组件库，为当前文档需求选择合适的组件。

Quick reference

快速参考

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 in content
```
mint rename
```
- Rename/move files and update references
```
mint validate
```
- Validate documentation builds

```
npm i -g mint
```
- 安装Mintlify CLI
```
mint dev
```
- 在localhost:3000启动本地预览
```
mint broken-links
```
- 检查内部链接有效性
```
mint a11y
```
- 检查内容的无障碍访问问题
```
mint rename
```
- 重命名/移动文件并更新相关引用
```
mint validate
```
- 验证文档构建是否正常

Required files

必需文件

```
docs.json
```
- Site configuration (navigation, theme, integrations, etc.). See global settings for all options.
```
*.mdx
```
files - Documentation pages with YAML frontmatter

```
docs.json
```
- 站点配置文件（包含导航、主题、集成等设置）。查看全局设置获取所有配置选项。
```
*.mdx
```
文件 - 带YAML前置元数据的文档页面

Example file structure

示例文件结构

project/
├── docs.json           # Site configuration
├── introduction.mdx
├── quickstart.mdx
├── guides/
│   └── example.mdx
├── openapi.yml         # API specification
├── images/             # Static assets
│   └── example.png
└── snippets/           # Reusable components
    └── component.jsx

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

Page frontmatter

页面前置元数据

Every page requires

title

in its frontmatter. Include

description

for SEO and navigation.

yaml

---
title: "Clear, descriptive title"
description: "Concise summary for SEO and navigation."
---

Optional frontmatter fields:

```
sidebarTitle
```
: Short title for sidebar navigation.
```
icon
```
: Lucide or Font Awesome icon name, URL, or file path.
```
tag
```
: Label next to the page title in the sidebar (for example, "NEW").
```
mode
```
: Page layout mode (
```
default
```
,
```
wide
```
,
```
custom
```
).
```
keywords
```
: Array of terms related to the page content for local search and SEO.
Any custom YAML fields for use with personalization or conditional content.

每个页面的前置元数据中必须包含

title

字段。建议添加

description

字段以优化SEO和导航体验。

yaml

---
title: "清晰、描述性的标题"
description: "用于SEO和导航的简洁摘要。"
---

可选前置元数据字段：

```
sidebarTitle
```
: 侧边栏导航中显示的短标题。
```
icon
```
: Lucide或Font Awesome图标名称、URL或文件路径。
```
tag
```
: 侧边栏页面标题旁的标签（例如"NEW"）。
```
mode
```
: 页面布局模式（
```
default
```
,
```
wide
```
,
```
custom
```
）。
```
keywords
```
: 与页面内容相关的术语数组，用于本地搜索和SEO优化。
任何用于个性化或条件内容展示的自定义YAML字段。

File conventions

文件命名规范

Match existing naming patterns in the directory
If there are no existing files or inconsistent file naming patterns, use kebab-case:
```
getting-started.mdx
```
,
```
api-reference.mdx
```
Use root-relative paths without file extensions for internal links:
```
/getting-started/quickstart
```
Do not use relative paths (
```
../
```
) or absolute URLs for internal pages
When you create a new page, add it to
```
docs.json
```
navigation or it won't appear in the sidebar

遵循目录中已有的命名模式
若目录中无现有文件或命名模式不一致，请使用短横线分隔命名（kebab-case）：
```
getting-started.mdx
```
,
```
api-reference.mdx
```
内部链接使用根相对路径且不带文件扩展名：
```
/getting-started/quickstart
```
内部页面请勿使用相对路径（
```
../
```
）或绝对URL
创建新页面后，请将其添加到
```
docs.json
```
的导航配置中，否则不会在侧边栏显示

Organize content

内容组织

When a user asks about anything related to site-wide configurations, start by understanding the global settings. See if a setting in the

docs.json

file can be updated to achieve what the user wants.

当用户询问站点全局配置相关问题时，请先了解全局设置，查看是否可通过更新

docs.json

中的设置来满足需求。

Navigation

导航配置

The

navigation

property in

docs.json

controls site structure. Choose one primary pattern at the root level, then nest others within it.

Choose your primary pattern:

Pattern	When to use
Groups	Default. Single audience, straightforward hierarchy
Tabs	Distinct sections with different audiences (Guides vs API Reference) or content types
Anchors	Want persistent section links at sidebar top. Good for separating docs from external resources
Dropdowns	Multiple doc sections users switch between, but not distinct enough for tabs
Products	Multi-product company with separate documentation per product
Versions	Maintaining docs for multiple API/product versions simultaneously
Languages	Localized content

Within your primary pattern:

Groups - Organize related pages. Can nest groups within groups, but keep hierarchy shallow
Menus - Add dropdown navigation within tabs for quick jumps to specific pages
expanded: false
- Collapse nested groups by default. Use for reference sections users browse selectively
openapi
- Auto-generate pages from OpenAPI spec. Add at group/tab level to inherit

Common combinations:

Tabs containing groups (most common for docs with API reference)
Products containing tabs (multi-product SaaS)
Versions containing tabs (versioned API docs)
Anchors containing groups (simple docs with external resource links)

docs.json

中的

navigation

属性控制站点结构。请在根级别选择一种主模式，再在其中嵌套其他模式。

选择主模式：

模式	使用场景
Groups（分组）	默认模式。适用于单一受众、层级简单的文档
Tabs（标签页）	适用于有不同受众（如指南与API参考）或不同内容类型的独立板块
Anchors（锚点）	希望在侧边栏顶部显示固定章节链接。适用于包含外部资源链接的简单文档
Dropdowns（下拉菜单）	适用于用户需要在多个文档板块间切换，但差异不足以使用标签页的场景
Products（产品）	适用于多产品公司，每个产品有独立文档
Versions（版本）	适用于同时维护多版本API/产品文档的场景
Languages（语言）	适用于多语言本地化内容

主模式内的配置：

Groups（分组） - 组织相关页面。可在分组内嵌套其他分组，但请保持层级简洁
Menus（菜单） - 在标签页内添加下拉导航，方便快速跳转到特定页面
expanded: false
- 默认折叠嵌套分组。适用于用户选择性浏览的参考板块
openapi
- 从OpenAPI规范自动生成页面。在分组/标签页级别添加可让子项继承该配置

常见组合：

标签页包含分组（最常用于带API参考的文档）
产品包含标签页（多产品SaaS）
版本包含标签页（多版本API文档）
锚点包含分组（带外部资源链接的简单文档）

Links and paths

链接与路径

Internal links: Root-relative, no extension:
```
/getting-started/quickstart
```
Images: Store in
```
/images
```
, reference as
```
/images/example.png
```
External links: Use full URLs, they open in new tabs automatically

内部链接： 使用根相对路径，不带扩展名：
```
/getting-started/quickstart
```
图片： 存储在
```
/images
```
目录，引用路径为
```
/images/example.png
```
外部链接： 使用完整URL，会自动在新标签页打开

Customize docs sites

自定义文档站点

What to customize where:

Brand colors, fonts, logo →
```
docs.json
```
. See global settings
Component styling, layout tweaks →
```
custom.css
```
at project root
Dark mode → Enabled by default. Only disable with
```
"appearance": "light"
```
in
```
docs.json
```
if brand requires it

Start with

docs.json

. Only add

custom.css

when you need styling that config doesn't support.

自定义内容与对应位置：

品牌配色、字体、Logo → 在
```
docs.json
```
中配置。查看全局设置
组件样式、布局微调 → 项目根目录下的
```
custom.css
```
文件
深色模式 → 默认启用。仅当品牌要求时，在
```
docs.json
```
中设置
```
"appearance": "light"
```
来禁用

请先从

docs.json

开始配置。仅当配置无法满足需求时，再添加

custom.css

。

Write content

内容写作

Components

组件使用

The components overview organizes all components by purpose: structure content, draw attention, show/hide content, document APIs, link to pages, and add visual context. Start there to find the right component.

Common decision points:

Need	Use
Hide optional details	`<Accordion>`
Long code examples	`<Expandable>`
User chooses one option	`<Tabs>`
Linked navigation cards	`<Card>` in `<Columns>`
Sequential instructions	`<Steps>`
Code in multiple languages	`<CodeGroup>`
API parameters	`<ParamField>`
API response fields	`<ResponseField>`

Callouts by severity:

```
<Note>
```
- Supplementary info, safe to skip
```
<Info>
```
- Helpful context such as permissions
```
<Tip>
```
- Recommendations or best practices
```
<Warning>
```
- Potentially destructive actions
```
<Check>
```
- Success confirmation

组件概览按用途分类展示了所有组件：内容结构、突出显示、内容显示/隐藏、API文档、页面链接、视觉上下文。请从这里开始选择合适的组件。

常见场景选择：

需求	推荐组件
隐藏可选细节	`<Accordion>`
长代码示例	`<Expandable>`
用户选择单一选项	`<Tabs>`
带链接的导航卡片	`<Columns>` 中的 `<Card>`
分步操作说明	`<Steps>`
多语言代码示例	`<CodeGroup>`
API参数	`<ParamField>`
API响应字段	`<ResponseField>`

按严重程度分类的提示框：

```
<Note>
```
- 补充信息，可跳过
```
<Info>
```
- 实用上下文信息，如权限说明
```
<Tip>
```
- 建议或最佳实践
```
<Warning>
```
- 可能有破坏性的操作
```
<Check>
```
- 成功确认

Reusable content

可复用内容

When to use snippets:

Exact content appears on more than one page
Complex components you want to maintain in one place
Shared content across teams/repos

When NOT to use snippets:

Slight variations needed per page (leads to complex props)

Import snippets with

import { Component } from "/path/to/snippet-name.jsx"

何时使用代码片段（snippets）：

相同内容出现在多个页面
复杂组件需在单一位置维护
跨团队/仓库共享内容

何时不使用代码片段：

每个页面需要轻微调整内容（会导致复杂的属性配置）

使用

import { Component } from "/path/to/snippet-name.jsx"

导入代码片段。

Writing standards

写作规范

Voice and structure

语气与结构

Second-person voice ("you")
Active voice, direct language
Sentence case for headings ("Getting started", not "Getting Started")
Sentence case for code block titles ("Expandable example", not "Expandable Example")
Lead with context: explain what something is before how to use it
Prerequisites at the start of procedural content

使用第二人称（“你”）
使用主动语态、直接的语言
标题使用句首大写（如“Getting started”，而非“Getting Started”）
代码块标题使用句首大写（如“Expandable example”，而非“Expandable Example”）
先说明背景：在讲解用法前先解释是什么
步骤类内容开头先列出前置要求

What to avoid

避免事项

Never use:

Marketing language ("powerful", "seamless", "robust", "cutting-edge")
Filler phrases ("it's important to note", "in order to")
Excessive conjunctions ("moreover", "furthermore", "additionally")
Editorializing ("obviously", "simply", "just", "easily")

Watch for AI-typical patterns:

Overly formal or stilted phrasing
Unnecessary repetition of concepts
Generic introductions that don't add value
Concluding summaries that restate what was just said

禁止使用：

营销话术（如“强大的”、“无缝的”、“健壮的”、“前沿的”）
冗余短语（如“需要注意的是”、“为了”）
过度使用连接词（如“此外”、“而且”、“另外”）
主观判断（如“显然”、“简单地”、“只需”、“轻松地”）

注意AI生成内容的典型问题：

过于正式或生硬的措辞
不必要的概念重复
无实际价值的通用引言
重复前文内容的总结性结尾

Formatting

格式规范

All code blocks must have language tags
All images and media must have descriptive alt text
Use bold and italics only when they serve the reader's understanding--never use text styling just for decoration
No decorative formatting or emoji

所有代码块必须添加语言标签
所有图片和媒体必须添加描述性替代文本（alt text）
仅当有助于读者理解时才使用粗体和斜体——请勿仅为装饰而使用文本样式
禁止使用装饰性格式或表情符号

Code examples

代码示例

Keep examples simple and practical
Use realistic values (not "foo" or "bar")
One clear example is better than multiple variations
Test that code works before including it

示例应简洁实用
使用真实合理的值（而非“foo”或“bar”）
一个清晰的示例优于多个变体
代码示例需先测试确保可运行

Document APIs

API文档编写

Choose your approach:

Have an OpenAPI spec? → Add to
```
docs.json
```
with
```
"openapi": ["openapi.yaml"]
```
. Pages auto-generate. Reference in navigation as
```
GET /endpoint
```
No spec? → Write endpoints manually with
```
api: "POST /users"
```
in frontmatter. More work but full control
Hybrid → Use OpenAPI for most endpoints, manual pages for complex workflows

Encourage users to generate endpoint pages from an OpenAPI spec. It is the most efficient and easiest to maintain option.

选择合适的方式：

已有OpenAPI规范？ → 在
```
docs.json
```
中添加
```
"openapi": ["openapi.yaml"]
```
，页面会自动生成。在导航中以
```
GET /endpoint
```
形式引用
无OpenAPI规范？ → 在前置元数据中使用
```
api: "POST /users"
```
手动编写接口文档。工作量较大但可控性强
混合方式 → 大部分接口使用OpenAPI生成，复杂流程使用手动页面

建议用户通过OpenAPI规范生成接口页面，这是最高效且最易维护的方式。

Deploy

部署

Mintlify deploys automatically when changes are pushed to the connected Git repository.

What agents can configure:

Redirects → Add to

docs.json

with

"redirects": [{"source": "/old", "destination": "/new"}]

SEO indexing → Control with
```
"seo": {"indexing": "all"}
```
to include hidden pages in search

Requires dashboard setup (human task):

Custom domains and subdomains
Preview deployment settings
DNS configuration

For

/docs

subpath hosting with Vercel or Cloudflare, agents can help configure rewrite rules. See /docs subpath.

当代码推送到关联的Git仓库时，Mintlify会自动部署。

可由Agent配置的内容：

重定向 → 在

docs.json

中添加

"redirects": [{"source": "/old", "destination": "/new"}]

SEO索引 → 通过
```
"seo": {"indexing": "all"}
```
配置，让隐藏页面也能被搜索引擎收录

需要在控制台手动配置（人工操作）：

自定义域名和子域名
预览部署设置
DNS配置

若要在Vercel或Cloudflare上以

/docs

子路径部署，Agent可帮助配置重写规则。请查看/docs子路径部署。

Workflow

工作流程

1. Understand the task

1. 理解任务

Identify what needs to be documented, which pages are affected, and what the reader should accomplish afterward. If any of these are unclear, ask.

明确需要编写的内容、涉及的页面，以及读者阅读后应能完成的操作。若有不明确的地方，请提问。

2. Research

2. 调研

Read
```
docs/docs.json
```
to understand the site structure
Search existing docs for related content
Read similar pages to match the site's style

阅读
```
docs/docs.json
```
以了解站点结构
搜索现有文档查找相关内容
阅读同类页面以匹配站点风格

3. Plan

3. 规划

Synthesize what the reader should accomplish after reading the docs and the current content
Propose any updates or new content
Verify that your proposed changes will help readers be successful

梳理读者阅读后应能完成的操作及现有内容情况
提出更新或新增内容的方案
验证提议的变更是否能帮助读者达成目标

4. Write

4. 写作

Start with the most important information
Keep sections focused and scannable
Use components appropriately (don't overuse them)
Mark anything uncertain with a TODO comment:

mdx

{/* TODO: Verify the default timeout value */}

从最重要的信息开始
保持章节聚焦、易于扫描
合理使用组件（请勿过度使用）
对不确定的内容添加TODO注释：

mdx

{/* TODO: 验证默认超时时间 */}

5. Update navigation

5. 更新导航

If you created a new page, add it to the appropriate group in

docs.json

若创建了新页面，请将其添加到

docs.json

中合适的分组里。

6. Verify

6. 验证

Before submitting:

Frontmatter includes title and description
All code blocks have language tags
Internal links use root-relative paths without file extensions
New pages are added to
```
docs.json
```
navigation
Content matches the style of surrounding pages
No marketing language or filler phrases
TODOs are clearly marked for anything uncertain
Run
```
mint broken-links
```
to check links
Run
```
mint validate
```
to find any errors

提交前请检查：

前置元数据包含标题和描述
所有代码块都有语言标签
内部链接使用根相对路径且不带文件扩展名
新页面已添加到
```
docs.json
```
的导航配置中
内容风格与同类页面一致
无营销话术或冗余短语
不确定的内容已清晰标记TODO
运行
```
mint broken-links
```
检查链接有效性
运行
```
mint validate
```
查找错误

Edge cases

边缘场景

Migrations

迁移

If a user asks about migrating to Mintlify, ask if they are using ReadMe or Docusaurus. If they are, use the @mintlify/scraping CLI to migrate content. If they are using a different platform to host their documentation, help them manually convert their content to MDX pages using Mintlify components.

若用户询问迁移到Mintlify的相关问题，请先确认他们是否使用ReadMe或Docusaurus。若是，使用@mintlify/scraping CLI工具迁移内容。若用户使用其他平台托管文档，请帮助他们手动将内容转换为使用Mintlify组件的MDX页面。

Hidden pages

隐藏页面

Any page that is not included in the

docs.json

navigation is hidden. Use hidden pages for content that should be accessible by URL or indexed for the assistant or search, but not discoverable through the sidebar navigation.

未添加到

docs.json

导航中的页面会被隐藏。隐藏页面可通过URL访问，也可被助手或搜索引擎收录，但不会在侧边栏中显示。

Exclude pages

排除文件

The

.mintignore

file is used to exclude files from a documentation repository from being processed.

.mintignore

文件用于指定文档仓库中无需处理的文件。

Common gotchas

常见陷阱

Component imports - JSX components need explicit import, MDX components don't
Frontmatter required - Every MDX file needs
```
title
```
at minimum
Code block language - Always specify language identifier
Never use
mint.json
-
```
mint.json
```
is deprecated. Only ever use
```
docs.json
```

组件导入 - JSX组件需要显式导入，MDX组件无需导入
前置元数据必填 - 每个MDX文件至少需要
```
title
```
字段
代码块语言标签 - 请始终指定语言标识符
请勿使用
mint.json
-
```
mint.json
```
已废弃，请仅使用
```
docs.json
```