为什么选择 Mintlify？
Mintlify 是一款 AI 原生的文档自动化工具，核心优势在于对 GitHub 的天然适配性，以及简约、清晰、符合程序员审美的页面风格。不同于传统文档工具的繁琐配置，Mintlify 主打'轻量化实操、AI 原生赋能'，支持'文档即代码'（Docs-as-Code）模式，能与 Git、GitHub 等版本控制工具无缝衔接。
- 对开发者极度友好：页面风格简约大气，重点突出代码块、接口说明，支持文档的版本控制、分支协作。
- AI 原生赋能：内置 AI 助手和智能代理，能自动完成文档的更新、优化、问答等操作，大幅减少手动维护工作量。
- 适配性极强：支持 OpenAPI、AsyncAPI 等规范，能一键生成 API 接口文档；支持多种开发框架，能与 Cursor、Claude 等工具集成。
- 轻量化部署：无需搭建复杂服务器环境，通过简单的 CLI 命令即可完成部署和启动。
实操准备：环境搭建与核心概念说明
基础环境要求
Mintlify 的安装和使用依赖 Node.js 环境，官方推荐使用 Node.js 20.0 及以上版本。
检查本机 Node.js 版本：
- 打开终端（Windows 使用 CMD/PowerShell，Mac/Linux 使用 Terminal）。
- 输入命令：
node -v。 - 若输出版本号≥20.0.0，则环境符合要求；否则需安装或升级。
Node.js 安装完成后会自动安装 npm，后续使用的 npx 命令会依赖 npm。
Skill 是什么？
Skill 是一段经过优化和沉淀的提示词脚本。Mintlify 的 Skill 包含了官方文档的编写规范、组件使用方法、最佳实践等核心信息。通过调用 Skill，能让 AI 按照 Mintlify 的标准生成文档，大幅提高生成结果的准确性和规范性。
此外，Skill 还支持自定义修改。熟悉规范后，可根据项目需求修改 Skill 中的提示词，实现个性化的文档生成。
实操步骤一：安装 Mintlify-Skill，接入 AI 工具
Mintlify 官方推荐通过 CLI 命令将文档接入常用的 AI 工具（如 Cursor、Claude）。核心是安装 Mintlify-Skill。
确认环境就绪
再次打开终端，输入 node -v 和 npm -v，确认 Node.js 和 npm 已正常安装。
执行 Skill 安装命令
不需要手动下载文件，直接通过 npx 命令完成安装：
npx skills add https://mintlify.com/docs
npx：执行 npm 包中的可执行文件。skills add：添加新 Skill 的核心命令。https://mintlify.com/docs：Mintlify 官方文档入口 URL。
安装过程与结果验证
终端输出'Successfully added skill: mintlify'时，说明安装成功。此时在 AI 工具中输入自然语言指令（如'帮我生成一个 Mintlify 的 Tabs 组件使用文档'），AI 即可基于官方规范生成内容。
拓展：给自定义文档站创建 Skill
若已搭建自己的文档站，可在根路径下确保存在 llms.txt 和 skill.md 两个文件，然后执行：
npx skills add https://你的文档域名
AI 工具会自动读取文件生成自定义 Skill。
实操步骤二：使用/mintlify 命令，让 AI 生成文档
装好 Mintlify-Skill 后，可通过 AI 工具使用 /mintlify 命令 + 自然语言描述，快速生成符合规范的文档。
核心操作逻辑
使用 Skill 相当于给 AI 提供了'标准答案'，AI 会严格按照定义的规范、模板生成文档，格式规范且无需手动修改。
具体操作步骤（以 Cursor 为例）
- 打开 Cursor 编辑器，新建空白 MDX 文件。
- 输入命令：
/mintlify，按下空格，输入自然语言描述。例如：
/mintlify 生成 Mintlify Accordions 组件的使用文档，包含组件介绍、参数说明、示例代码、注意事项 - 按下回车，AI 自动生成符合规范的文档，包含 mdx 格式文档文件和 docs.json 配置文件。
自定义修改 Skill 提示词
熟悉规范后，可手动修改 Skill 提示词。以 Cursor 为例，保存目录为 .cursor/skills/mintlify，找到 skill.md 文件进行修改。注意不要破坏原有规范结构。
实操步骤三：启动 Mintlify，预览和查看文档
生成文档内容后，需启动 Mintlify 服务进行预览。
启动 Mintlify 服务
- 打开终端，进入存放文档文件的目录。
- 输入命令：
npx mintlify dev
当终端输出'Local development server running at: http://localhost:3000'时，服务启动成功。
预览和查看文档
- 浏览器访问
http://localhost:3000。 - 在导航栏中找到生成的文档，点击查看。
- 修改文档内容后，浏览器会自动刷新，无需重新启动服务。
进阶实操：基于 openapi.json 生成 OpenAPI 接口文档
Mintlify 支持基于 openapi.json 文件，一键生成专业的 OpenAPI 接口文档。
前提：获取 openapi.json 文件
主流 Web 开发框架（如 Spring Boot、FastAPI）都支持自动生成 openapi.json 文件。
FastAPI 框架
FastAPI 原生支持 OpenAPI 规范。启动应用后，访问 http://localhost:8000/openapi.json 即可获取文件。
示例代码：
from fastapi import FastAPI
app = FastAPI(openapi_url="/openapi.json")
Spring Boot 框架
需添加 springdoc-openapi 依赖。在 application.yml 中配置访问路径，启动后访问对应地址获取 JSON 文件。
将 openapi.json 关联到 Mintlify 文档
- 将
openapi.json文件放到 Mintlify 文档目录根路径下。 - 新建 MDX 文件（如
openapi-docs.mdx），添加以下代码引入 OpenAPI 组件：
import { OpenAPI } from "@mintlify/components";
<OpenAPI specUrl="/openapi.json" />
- 保存文件，重新启动 Mintlify 服务（
npx mintlify dev）。 - 浏览器访问并查看生成的接口文档。
生成的 OpenAPI 接口文档具备美观简洁、可交互（支持测试）、结构清晰、信息完整及自动更新等特点。
高级功能初探
Mintlify 还支持以下高级操作：
- 页面语义检索：支持用户通过自然语言搜索文档内容。
- 基于 MCP 的查询：通过模型上下文协议连接文档和 API 接口。
- 基于 GitHub/GitLab 的关联发布：实现文档的自动发布和 PR 预览。
- 多语言支持与自动翻译：快速将文档翻译成多种语言。
- 文档数据分析：统计访问量、搜索关键词等信息。
总结
Mintlify 作为一款 AI 原生的文档自动化工具，以其简约的风格、便捷的操作、强大的功能，成为开发者的得力助手。通过本文的实操教程，可以快速掌握 Mintlify 的核心用法，包括环境搭建、Skill 安装、文档生成、预览及接口文档生成，大幅提升技术文档编写和维护的效率。
