快速参考

CLI 命令

• npm i -g mint - 安装 Mintlify CLI
• mint dev - 在 localhost:3000 进行本地预览
• mint broken-links - 检查内部链接
• mint a11y - 检查内容中的无障碍访问问题
• mint rename - 重命名/移动文件并更新引用
• mint validate - 验证文档构建

必需文件

• docs.json - 站点配置（导航、主题、集成等）。所有选项请参见全局设置。
• *.mdx 文件 - 带有 YAML frontmatter 的文档页面

示例文件结构

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

页面 frontmatter

每个页面都需要在其 frontmatter 中包含 title。为 SEO 和导航包含 description。

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

可选的 frontmatter 字段：

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

文件约定

• 匹配目录中现有的命名模式
• 如果没有现有文件或文件命名模式不一致，请使用 kebab-case：getting-started.mdx、api-reference.mdx
• 内部链接使用不带文件扩展名的根相对路径：/getting-started/quickstart
• 不要对内部页面使用相对路径（../）或绝对 URL
• 创建新页面时，请将其添加到 docs.json 导航中，否则它不会出现在侧边栏中

组织内容

当用户询问任何与全站配置相关的内容时，首先了解全局设置。查看 docs.json 文件中的设置是否可以更新以实现用户想要的效果。

导航

docs.json 中的 navigation 属性控制站点结构。在根级别选择一个主要模式，然后在其中嵌套其他模式。

选择您的主要模式：

在您的主要模式内：

• Groups - 组织相关页面。可以在组内嵌套组，但保持层次结构较浅
• Menus - 在标签页内添加下拉导航，以便快速跳转到特定页面
• expanded: false - 默认情况下折叠嵌套组。用于用户选择性浏览的参考部分
• openapi - 从 OpenAPI 规范自动生成页面。在组/标签页级别添加以继承

常见组合：

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

链接和路径

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

自定义文档站点

在何处自定义什么：

• 品牌颜色、字体、徽标 → docs.json。参见全局设置
• 组件样式、布局调整 → 项目根目录下的 custom.css
• 深色模式 → 默认启用。仅在品牌要求时，在 docs.json 中使用 "appearance": "light" 来禁用它

从 docs.json 开始。仅当您需要配置不支持的自定义样式时才添加 custom.css。

编写内容

组件

组件概述 按用途组织所有组件：结构化内容、引起注意、显示/隐藏内容、记录 API、链接到页面以及添加视觉上下文。从那里开始寻找合适的组件。

常见决策点：

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

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

可复用内容

何时使用代码片段：

• 完全相同的内容出现在多个页面上
• 您希望在一个地方维护的复杂组件
• 跨团队/仓库共享的内容

何时不使用代码片段：

• 每个页面需要略有不同的变体（会导致复杂的属性）

使用 import { Component } from "/path/to/snippet-name.jsx" 导入代码片段。

编写标准

语气和结构

• 第二人称语气（"您"）
• 主动语态，直接的语言
• 标题使用句子大小写（"Getting started"，而非 "Getting Started"）
• 代码块标题使用句子大小写（"Expandable example"，而非 "Expandable Example"）
• 先提供上下文：在使用方法之前解释它是什么
• 在流程性内容开头列出先决条件

应避免的事项

切勿使用：

• 营销语言（"强大"、"无缝"、"稳健"、"尖端"）
• 填充短语（"值得注意的是"、"为了"）
• 过多的连接词（"此外"、"而且"、"另外"）
• 主观评论（"显然"、"简单地"、"只是"、"容易地"）

注意典型的 AI 模式：

• 过于正式或生硬的措辞
• 不必要地重复概念
• 不增加价值的通用介绍
• 重复刚说过内容的总结性结尾

格式

• 所有代码块必须有语言标签
• 所有图片和媒体必须有描述性的替代文本
• 仅当有助于读者理解时才使用粗体和斜体——切勿仅为了装饰而使用文本样式
• 不要使用装饰性格式或表情符号

代码示例

• 保持示例简单实用
• 使用现实的值（而不是 "foo" 或 "bar"）
• 一个清晰的示例优于多个变体
• 在包含代码之前测试其是否有效

记录 API

选择您的方法：

• 有 OpenAPI 规范吗？ → 使用 "openapi": ["openapi.yaml"] 添加到 docs.json。页面自动生成。在导航中引用为 GET /endpoint
• 没有规范？ → 在 frontmatter 中使用 api: "POST /users" 手动编写端点。工作量更大但控制更全面
• 混合 → 对大多数端点使用 OpenAPI，对复杂工作流使用手动页面

鼓励用户从 OpenAPI 规范生成端点页面。这是最高效且最容易维护的选项。

部署

当更改推送到连接的 Git 仓库时，Mintlify 会自动部署。

代理可以配置的内容：

• 重定向 → 使用 "redirects": [{"source": "/old", "destination": "/new"}] 添加到 docs.json
• SEO 索引 → 使用 "seo": {"indexing": "all"} 控制，以便在搜索中包含隐藏页面

需要仪表板设置（人工任务）：

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

对于使用 Vercel 或 Cloudflare 的 /docs 子路径托管，代理可以帮助配置重写规则。请参见 /docs 子路径。

工作流程

1. 理解任务

确定需要记录什么、哪些页面会受到影响，以及读者阅读后应该完成什么。如果其中任何一点不清楚，请提问。

2. 研究

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

3. 计划

• 综合读者在阅读文档和当前内容后应该完成什么
• 提出任何更新或新内容
• 验证您提出的更改将有助于读者成功

4. 编写

• 从最重要的信息开始
• 保持章节重点突出且易于浏览
• 适当使用组件（不要过度使用）
• 用 TODO 注释标记任何不确定的内容：

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

5. 更新导航

如果您创建了新页面，请将其添加到 docs.json 中的相应组。

6. 验证

提交前检查：

• Frontmatter 包含标题和描述
• 所有代码块都有语言标签
• 内部链接使用不带文件扩展名的根相对路径
• 新页面已添加到 docs.json 导航中
• 内容与周围页面的风格一致
• 没有营销语言或填充短语
• 不确定的内容已用 TODO 明确标记
• 运行 mint broken-links 检查链接
• 运行 mint validate 查找任何错误

边缘情况

迁移

如果用户询问迁移到 Mintlify，请询问他们是否正在使用 ReadMe 或 Docusaurus。如果是，请使用 @mintlify/scraping CLI 迁移内容。如果他们使用其他平台托管文档，请帮助他们使用 Mintlify 组件手动将其内容转换为 MDX 页面。

隐藏页面

任何未包含在 docs.json 导航中的页面都是隐藏的。使用隐藏页面存放那些应可通过 URL 访问或为助手或搜索建立索引，但不应通过侧边栏导航发现的内容。

排除页面

.mintignore 文件用于从文档仓库中排除某些文件，使其不被处理。

常见陷阱

1. 组件导入 - JSX 组件需要显式导入，MDX 组件则不需要
2. 必需 frontmatter - 每个 MDX 文件至少需要 title
3. 代码块语言 - 始终指定语言标识符
4. 切勿使用 mint.json - mint.json 已弃用。始终只使用 docs.json

资源

• 文档
• 配置模式
• 功能请求
• 错误和反馈

每周安装量

670

来源

mintlify.com/docs

首次出现

2026年2月28日

安全审计

SocketPass

安装于

opencode656

codex655

cursor648

github-copilot646

kimi-cli645

gemini-cli645

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

Understand Mintlify components

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

Quick reference

CLI commands

• 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

Required files

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

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

Page frontmatter

Every page requires title in its frontmatter. Include description for SEO and navigation.

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

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

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.

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:

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)

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

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.

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:

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

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

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

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

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

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

Document APIs

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.

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.

Workflow

1. Understand the task

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

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

3. Plan

• 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

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

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

5. Update navigation

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

6. Verify

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

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.

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.

Exclude pages

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

Common gotchas

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

Resources

• Documentation
• Configuration schema
• Feature requests
• Bugs and feedback

Weekly Installs

670

Source

mintlify.com/docs

First Seen

Feb 28, 2026

Security Audits

SocketPass

Installed on

opencode656

codex655

cursor648

github-copilot646

kimi-cli645

gemini-cli645