⚡

Mintlify文档构建与维护Skill mintlify

这个技能用于使用Mintlify平台高效构建、定制和部署文档网站，包括配置导航、添加组件、集成API参考、优化SEO和自动化部署。关键词：Mintlify、文档构建、MDX、API参考、低代码开发、SEO优化、静态站点生成。

低代码开发 0 次安装 0 次浏览 更新于 3/10/2026

name: mintlify description: 使用Mintlify构建和维护文档站点。适用于创建文档页面、配置导航、添加组件或设置API参考。 license: MIT compatibility: CLI需要Node.js。适用于任何基于Git的工作流。 metadata: author: mintlify version: “1.0” mintlify-proj: mintlify internal: true

Mintlify 最佳实践

始终参考 mintlify.com/docs 获取组件、配置和最新功能。

如果尚未连接到Mintlify MCP服务器，https://mintlify.com/docs/mcp，请添加它以更高效地搜索。

Mintlify 是一个文档平台，将MDX文件转换为文档站点。在 docs.json 文件中配置站点范围设置，使用YAML frontmatter在MDX中编写内容，并优先使用内置组件而非自定义组件。

完整模式见 mintlify.com/docs.json。

快速参考

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

组织内容

当用户询问与站点范围配置相关的内容时，首先了解 全局设置。查看 docs.json 文件中的设置是否能实现用户需求。

导航

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

选择您的主要模式:

模式 使用时机
分组 默认。单一受众，简单层次结构
标签页 不同受众（指南 vs API参考）或内容类型的独立部分
锚点 希望在侧边栏顶部有持久部分链接。适用于分离文档和外部资源
下拉菜单 用户可以在多个文档部分之间切换，但不够独立以使用标签页
产品 多产品公司，每个产品有独立文档
版本 同时维护多个API/产品版本的文档
语言 本地化内容

在您的主要模式内:

  • 分组 - 组织相关页面。可以在分组内嵌套分组，但保持层次结构浅显
  • 菜单 - 在标签页内添加下拉导航以快速跳转到特定页面
  • 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、链接页面和添加视觉上下文。从那里开始找到合适的组件。

常见决策点:

需求 使用
隐藏可选细节 <Accordion>
长代码示例 <Expandable>
用户选择一个选项 <Tabs>
链接导航卡片 <Card> 在 <Columns> 中
顺序指令 <Steps>
多语言代码 <CodeGroup>
API参数 <ParamField>
API响应字段 <ResponseField>

按严重性分类的提示框:

  • <Note> - 补充信息，可跳过
  • <Info> - 有用上下文，如权限
  • <Tip> - 推荐或最佳实践
  • <Warning> - 潜在破坏性操作
  • <Check> - 成功确认

可重用内容

何时使用代码片段:

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

何时不使用代码片段:

  • 每页需要轻微变化（导致复杂属性）

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

文档API

选择您的方法:

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

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

部署

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

代理可以配置的内容:

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

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

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

对于Vercel或Cloudflare的 /docs 子路径托管，代理可以帮助配置重写规则。查看 /docs子路径。

边缘案例

迁移

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

隐藏页面

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

排除页面

.mintignore 文件用于排除文档仓库中的文件不被处理。

常见陷阱

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

资源