前言在开源项目迭代日益频繁、技术文档需求激增的当下一款高效、美观、贴合开发者习惯的文档自动化工具早已成为团队协作和项目落地的必备利器。上一篇文章中我们对Mintlify这款文档自动化生成工具做了初步简介相信经常浏览GitHub代码的开发者对它并不陌生——无论是前阵子爆火的开源项目openClaw还是大模型记忆管理工具Mem0其项目文档都采用了Mintlify搭建。Mintlify之所以能成为开源项目的“文档首选”核心在于它对GitHub的天然适配性以及简约、清晰、符合程序员审美的页面风格。不同于传统文档工具的繁琐配置Mintlify主打“轻量化实操、AI原生赋能”哪怕是刚接触的新手也能快速上手生成专业级别的技术文档。今天我们就从实操角度出发一步步拆解Mintlify文档生成的全流程从环境准备、Skill安装到文档生成、接口文档适配再到高级功能初探帮大家彻底掌握Mintlify的核心用法让技术文档编写效率翻倍告别“写文档比写代码还累”的困境。为什么选择Mintlify在正式进入实操之前我们先简单回顾并补充Mintlify的核心优势——理解这些优势能让我们在后续实操中更清楚“为什么要这么做”也能更好地发挥它的价值。首先对开发者极度友好。Mintlify的设计初衷就是服务于开发者页面风格简约大气没有多余的装饰重点突出代码块、接口说明、步骤指引等核心内容完美契合程序员“简洁高效”的审美需求。同时它支持“文档即代码”Docs-as-Code的开发模式能与Git、GitHub、GitLab等版本控制工具无缝衔接开发者可以像管理代码一样管理文档实现文档的版本控制、分支协作、预览部署极大降低了团队协作的成本。其次AI原生赋能自动化程度高。Mintlify最突出的特点就是“AI驱动”内置的AI助手、智能代理Agent等功能能自动完成文档的更新、优化、问答等操作。比如我们可以通过AI生成文档内容、自动翻译多语言版本、通过Slack或PR触发文档更新甚至可以让AI助手直接回答用户关于文档的疑问大幅减少手动维护文档的工作量。再者适配性极强生态完善。无论是个人开发者的小项目还是企业级的大型开源项目Mintlify都能完美适配。它支持OpenAPI、AsyncAPI等规范能一键生成API接口文档支持多种开发框架Spring Boot、FastAPI等能直接读取框架生成的openapi.json文件同时它还能与Cursor、Claude、Discord、Slack等工具集成形成完整的文档开发、维护、分发生态。最后轻量化部署开箱即用。不同于一些需要复杂配置的文档工具Mintlify无需搭建复杂的服务器环境通过简单的CLI命令就能完成部署和启动哪怕是新手也能在几分钟内完成首个文档站点的搭建和预览。正是这些优势让Mintlify在开源社区中迅速崛起成为越来越多开发者的首选文档工具。接下来我们就进入最核心的实操环节一步步教大家如何用Mintlify生成属于自己的文档。实操准备环境搭建与核心概念说明在开始实操之前我们需要先完成基础环境的搭建同时了解几个核心概念——这是后续实操的基础避免大家在操作过程中出现困惑。2.1 基础环境要求Mintlify的安装和使用依赖Node.js环境官方推荐使用Node.js 20.0及以上版本这是因为高版本的Node.js能更好地支持Mintlify的CLI工具和AI相关功能避免出现兼容性问题。我们可以通过以下步骤检查本机的Node.js版本打开电脑的终端Windows系统可使用CMD、PowerShellMac/Linux系统可使用Terminal在终端中输入命令node -v若终端输出的版本号≥20.0.0则说明环境符合要求若版本低于20.0.0或提示“node不是内部或外部命令”则需要先安装或升级Node.js。Node.js的安装非常简单直接访问官方网站https://nodejs.org/下载对应系统Windows、Mac、Linux的LTS版本长期支持版本按照安装向导一步步操作即可。安装完成后重新打开终端输入node -v确认版本符合要求即可。这里需要注意安装Node.js时会自动安装npmNode.js的包管理工具后续我们使用的npx命令用于执行npm包会依赖npm因此无需额外安装npm。2.2 Skill是什么在后续的实操中我们会频繁提到“Skill”这个概念很多新手可能会困惑Skill到底是什么为什么要用Skill这里我们用最通俗的语言给大家解释清楚。简单来说Skill就是一段经过优化和沉淀的提示词脚本。我们都知道用AI生成内容时提示词的质量直接决定了生成结果的准确性和规范性。如果我们自己手动编写提示词很容易出现偏差比如生成的文档不符合Mintlify的规范、格式混乱、内容缺失等。而Mintlify的Skill就是官方或社区开发者总结的“最优提示词脚本”它包含了Mintlify文档的编写规范、组件使用方法、最佳实践等核心信息相当于“前人已经帮我们踩好了坑总结好了经验”。我们通过调用Skill就能让AI按照Mintlify的标准生成文档大幅提高生成结果的准确性和规范性避免手动编写提示词的弊端。举个例子如果我们想让AI生成一篇Mintlify的组件使用文档手动编写提示词可能会遗漏组件的参数说明、使用场景等关键信息而使用官方提供的SkillAI会自动按照Mintlify的规范完整生成组件的介绍、参数、示例代码、注意事项等内容无需我们额外补充。此外Skill还支持自定义修改。当我们熟悉了Mintlify的规范后可以根据自己的项目需求、个人习惯修改Skill中的提示词让它更贴合自己的使用场景。比如我们可以在Skill中添加自己项目的专属组件、文档模板等实现个性化的文档生成。了解完基础环境和核心概念后我们就正式进入实操步骤从Skill安装开始一步步完成Mintlify文档的生成。实操步骤一安装Mintlify-Skill接入AI工具Mintlify官方推荐的使用方式是通过CLI命令将Mintlify的文档接入到我们常用的AI工具如Cursor、Claude等中而这个过程的核心就是安装Mintlify-Skill。安装完成后我们的AI工具就能基于Mintlify的官方文档结构、组件规范、最佳实践快速生成符合要求的文档。具体操作步骤如下全程无需复杂配置跟着终端命令一步步执行即可3.1 确认环境就绪再次打开终端输入node -v和npm -v确认Node.js和npm都已正常安装。如果终端能正常输出版本号说明环境就绪可以进入下一步操作。3.2 执行Skill安装命令我们不需要手动下载Skill文件直接通过npx命令就能完成安装。操作如下打开终端进入你常用的工作目录比如桌面的“code”文件夹、项目根目录等任意目录均可不影响后续使用在终端中输入以下命令然后按下回车npx skills add https://mintlify.com/docs这里我们详细解释一下这个命令的含义-npx是npm的一个扩展命令用于执行npm包中的可执行文件无需先安装包直接执行非常方便-skills add是Skill工具的核心命令用于添加一个新的Skill格式为npx skills add docs-入口-URL-https://mintlify.com/docs是Mintlify官方文档的入口URLSkill工具会自动访问这个URL读取官方文档中的llms.txt、skill.md等核心文件从而获取Mintlify的文档规范、组件信息、最佳实践等内容生成对应的Skill脚本。3.3 安装过程与结果验证输入命令后终端会自动开始下载和安装相关依赖过程大概需要1-2分钟具体时间取决于网络速度期间终端会显示安装进度。当终端输出“Successfully added skill: mintlify”或类似的成功提示时说明Mintlify-Skill已经安装成功。安装成功后我们的AI工具以Cursor为例就会自动接入Mintlify的Skill此时我们在Cursor中输入相关的自然语言指令比如“帮我生成一个Mintlify的Tabs组件使用文档”“教我配置Mintlify的docs.json文件”AI就会基于Mintlify的官方规范生成准确、规范的内容。3.4 拓展给自定义文档站创建Skill如果我们已经搭建了自己的文档站想让AI工具能基于自己的文档规范生成内容也可以通过同样的方式创建自定义Skill。具体要求和操作如下确保你的文档站根路径下已经存在llms.txt和skill.md两个文件- llms.txt用于告诉AI工具你的文档站的结构、索引方式、核心内容等方便AI读取和理解- skill.md用于定义AI生成文档的规范、模板、提示词等相当于自定义的Skill脚本。这两个文件的具体编写规范可以参考Mintlify官方文档中的说明https://www.mintlify.com/docs/ai/llmstxt.md 和 https://www.mintlify.com/docs/ai/skillmd.md按照官方规范编写即可。编写完成后在终端中执行以下命令添加自定义Skillnpx skills add https://你的文档域名比如你的文档站域名为“docs.example.com”则命令为npx skills add https://docs.example.com。执行完成后AI工具就会自动读取你文档站中的llms.txt和skill.md文件生成自定义的Skill后续就能基于你的文档规范生成内容了。四、实操步骤二使用/mintlify命令让AI生成文档装好Mintlify-Skill后我们就可以通过AI工具使用/mintlify命令自然语言描述快速生成符合Mintlify规范的文档了。这一步是Mintlify文档生成的核心也是最能体现其“高效、便捷”优势的环节。4.1 核心操作逻辑很多小伙伴可能会问“既然AI能直接生成文档为什么还要多此一举安装Skill” 这里我们再强调一下如果不使用Skill直接让AI生成Mintlify文档AI没有明确的规范参考很可能会出现格式混乱、内容不符合Mintlify要求、遗漏核心信息等问题。比如AI可能会生成不符合Mintlify组件规范的代码示例或者文档结构与Mintlify的推荐结构不一致后续还需要我们手动修改反而增加了工作量。而使用Skill后相当于给AI提供了“标准答案”——AI会严格按照Skill中定义的Mintlify规范、模板、最佳实践来生成文档生成的内容不仅格式规范、内容完整还能直接适配Mintlify的部署要求无需我们手动修改大幅提高效率。简单来说使用Skill生成文档就是“站在巨人的肩膀上”复用前人总结的经验避免踩坑提高文档生成的成功率和规范性。4.2 具体操作步骤以Cursor为例我们以常用的AI代码编辑器Cursor为例演示如何使用/mintlify命令生成文档。其他AI工具如Claude、ChatGPT等的操作逻辑类似大家可以根据自己的使用习惯调整。打开Cursor编辑器新建一个空白的MDX文件Mintlify文档推荐使用MDX格式支持Markdown语法和React组件后续我们会详细说明在文件中输入命令/mintlify然后按下空格输入自然语言描述说明你想要生成的文档内容比如我们想要生成一个“Mintlify Accordions组件的使用文档”可以输入/mintlify 生成Mintlify Accordions组件的使用文档包含组件介绍、参数说明、示例代码、注意事项输入完成后按下回车AI就会基于Mintlify-Skill自动生成符合Mintlify规范的Accordions组件使用文档生成内容将包含两个核心文件分别对应文档内容与导航配置具体说明如下1.mdx格式文档文件这是文档的核心内容文件用于承载Accordions组件的详细说明也是我们后续部署到Mintlify中的主要文档文件里面会完整包含组件相关的所有内容2.docs.json配置文件这是文档的导航配置文件Mintlify会通过该文件自动生成文档站点的左侧导航栏方便用户快速定位和访问Accordions组件文档同时可通过该文件配置导航名称、层级、排序等相关参数让文档结构更清晰。4.3 自定义修改Skill提示词当我们熟悉了Mintlify的规范后如果觉得官方Skill的提示词不符合自己的使用习惯或者想添加个性化的内容可以手动修改Skill的提示词。Skill文件会保存在固定的文件夹中不同AI工具的保存路径略有不同这里以Cursor为例1. 打开电脑的文件管理器进入Cursor的Skill保存目录.cursor/skills/mintlify2. 找到其中的skill.md文件这就是Skill的核心提示词文件用文本编辑器如VS Code、记事本等打开3. 根据自己的需求修改文件中的提示词内容。比如我们可以添加自己项目中常用的组件模板、修改文档的结构、补充个性化的说明等4. 修改完成后保存文件重新打开AI工具此时AI就会按照修改后的Skill提示词生成文档。这里需要注意修改Skill提示词时尽量不要破坏原有的规范结构避免AI生成的文档出现混乱。如果不确定如何修改可以参考Mintlify官方文档中的Skill编写规范谨慎调整。五、实操步骤三启动Mintlify预览和查看文档生成文档内容后我们需要启动Mintlify服务在网页上预览和查看文档确认文档的格式、内容是否符合要求。这一步非常简单只需执行一个CLI命令即可完成。5.1 启动Mintlify服务1. 打开终端进入你存放文档文件的目录比如你刚才在Cursor中新建的MDX文件所在的目录2. 在终端中输入以下命令按下回车npx mintlify dev这个命令的作用是启动Mintlify的本地开发服务用于预览文档。执行命令后终端会开始启动服务期间会显示启动进度。当终端输出“Local development server running at: http://localhost:3000”或类似的提示时说明Mintlify服务已经成功启动。5.2 预览和查看文档1. 打开电脑的浏览器输入终端提示的地址默认是http://localhost:3000按下回车2. 此时浏览器会显示Mintlify的文档预览页面页面风格简约清晰左侧是文档导航栏右侧是文档内容区域3. 我们可以在导航栏中找到自己生成的文档点击查看确认文档的格式、内容、组件显示是否符合要求4. 如果发现文档有问题比如内容错误、格式混乱、组件无法正常显示可以返回AI工具或文本编辑器中修改文档内容修改完成后浏览器会自动刷新无需重新启动Mintlify服务非常便捷。5.3 补充说明Mintlify的本地开发特性Mintlify的npx mintlify dev命令不仅能用于预览文档还具备以下实用特性方便我们进行文档开发和调试- 实时刷新修改文档内容后浏览器会自动刷新实时显示修改后的效果无需手动刷新页面- 错误提示如果文档中存在语法错误比如MDX语法错误、组件参数错误终端会显示详细的错误提示帮助我们快速定位和解决问题- 导航自动生成Mintlify会根据文档的标题层级如h1、h2、h3自动生成左侧的导航栏无需我们手动配置导航。当我们确认文档无误后就可以将文档部署到线上比如GitHub Pages、自定义域名等供其他人访问。关于Mintlify的线上部署我们会在后续的进阶教程中详细讲解本次重点聚焦于本地实操。六、进阶实操基于openapi.json生成OpenAPI接口文档除了手动生成普通文档Mintlify还有一个非常实用的功能——基于openapi.json文件一键生成专业的OpenAPI接口文档。对于Web开发开发者来说这个功能尤为重要能大幅减少接口文档的编写工作量。我们都知道文档自动化并不是一个新概念比如我们可以通过IDEA的YAPI插件一键生成接口文档还能进行接口调试。而这些工具的核心原理都是基于openapi.json文件——openapi.json是符合OpenAPI规范的接口描述文件包含了接口的路径、请求方法、参数、响应体、状态码等所有核心信息任何支持OpenAPI规范的工具都能读取这个文件并生成接口文档。Mintlify同样支持读取openapi.json文件并且能生成美观、可交互的OpenAPI接口文档。下面我们就详细讲解如何操作。6.1 前提获取openapi.json文件首先我们需要获取自己项目的openapi.json文件。目前主流的Web开发框架如Spring Boot、FastAPI等都支持自动生成openapi.json文件我们只需简单配置就能通过浏览器访问并下载该文件。这里我们分别以Spring Boot和FastAPI为例简单说明如何获取openapi.json文件详细的框架配置大家可以参考对应框架的官方文档6.1.1 FastAPI框架自动生成无需额外依赖FastAPI框架原生支持OpenAPI规范无需添加任何额外依赖就能自动生成openapi.json文件。具体操作如下1. 编写FastAPI应用代码简单示例from fastapi import FastAPI from pydantic import BaseModel app FastAPI( docs_urlNone, redoc_urlNone, openapi_url/openapi.json, # 指定openapi.json的访问路径 swagger_ui_oauth2_redirect_urlNone ) # 数据模型 class Item(BaseModel): name: str price: float is_offer: bool None # 接口定义 app.get(/items/{item_id}) async def read_item(item_id: int, q: str None): return {item_id: item_id, q: q} app.post(/items/) async def create_item(item: Item): return {name: item.name, price: item.price}2. 启动FastAPI应用访问http://localhost:8000/openapi.json就能看到自动生成的openapi.json文件内容3. 复制页面中的JSON内容保存为openapi.json文件存放到自己的文档目录中。6.1.2 Spring Boot框架需添加依赖Spring Boot本身不内置OpenAPI生成能力需要添加springdoc-openapi依赖才能自动生成openapi.json文件。具体操作如下1. 在pom.xmlMaven或build.gradleGradle中添加依赖以Spring Boot 3.x为例Maven依赖dependencygroupIdorg.springdoc/groupIdartifactIdspringdoc-openapi-starter-webmvc-ui/artifactIdversion2.5.0/version/dependency2. 在application.yml中添加配置指定openapi.json的访问路径springdoc:api-docs:path: /openapi.json # 自定义访问路径enabled: true3. 编写Spring Boot接口代码简单示例启动应用4. 访问http://localhost:8080/openapi.json复制JSON内容保存为openapi.json文件存放到文档目录中。6.2 将openapi.json关联到Mintlify文档获取openapi.json文件后我们需要将其关联到Mintlify的文档文件中让Mintlify自动读取并生成接口文档。具体操作如下1. 将保存好的openapi.json文件放到Mintlify文档目录的根路径下和我们之前生成的MDX文档文件同级2. 新建一个MDX文件比如命名为openapi-docs.mdx在文件中添加以下代码用于关联openapi.json文件import { OpenAPI } from mintlify/components; OpenAPI specUrl/openapi.json /这段代码的作用是引入Mintlify的OpenAPI组件并指定openapi.json文件的路径这里因为openapi.json文件在根路径下所以路径为“/openapi.json”。或者直接将openapi.json 文件引入到docs.json 中即可。3. 保存文件重新启动Mintlify服务npx mintlify dev4. 打开浏览器访问http://localhost:3000找到openapi-docs.mdx文件点击查看就能看到Mintlify自动生成的OpenAPI接口文档。6.3 生成的OpenAPI接口文档特点Mintlify生成的OpenAPI接口文档具备以下特点非常贴合开发者的使用需求美观简洁页面风格与Mintlify整体保持一致简约清晰重点突出接口信息可交互支持接口参数预览、响应体预览还能直接在文档中测试接口内置API Playground功能结构清晰自动按照接口路径、请求方法分类左侧导航栏可快速定位到具体接口信息完整包含接口的参数说明、数据类型、默认值、响应状态码、响应示例等所有核心信息自动更新如果openapi.json文件发生修改Mintlify会自动更新接口文档无需手动重新生成。通过这种方式我们只需维护好项目的openapi.json文件就能自动生成专业的接口文档大幅减少手动编写接口文档的工作量同时保证接口文档的准确性和规范性。实践总结与高级功能初探到这里Mintlify文档生成的核心实操步骤就已经全部讲解完毕了。我们回顾一下本次的实操内容从环境搭建安装Node.js到安装Mintlify-Skill、接入AI工具再到使用/mintlify命令生成文档、启动Mintlify预览文档最后到基于openapi.json生成接口文档整个流程非常简洁无需复杂配置新手也能快速上手。通过本次实践我们可以发现Mintlify的核心优势在于“AI赋能轻量化实操高适配性”它不仅能帮助我们快速生成符合规范的技术文档还能与主流开发框架、AI工具、版本控制工具无缝衔接极大提升文档编写和维护的效率。对于开发者来说使用Mintlify我们可以将更多的精力放在代码开发上而不是繁琐的文档编写上。需要说明的是本次讲解的只是Mintlify的基础实操功能事实上Mintlify还原生支持很多基于AI的高级操作这些功能能进一步提升我们的文档管理效率大家可以在后续的使用中慢慢探索7.1 页面语义检索Mintlify内置语义检索功能支持用户通过自然语言搜索文档内容哪怕是输入的关键词与文档中的文字不完全一致也能精准定位到相关内容。比如用户输入“如何配置自定义域名”Mintlify会自动检索文档中与“自定义域名配置”相关的内容快速返回结果提升文档的查找效率。7.2 基于MCP的查询MCPModel Context Protocol模型上下文协议是Mintlify的核心协议之一通过MCP我们可以将自己的文档和API接口连接到AI工具中实现更智能的查询和交互。比如我们可以通过MCP协议让AI工具直接读取文档中的内容回答用户关于API接口的疑问无需用户手动查找文档。7.3 基于GitHub、GitLab的关联发布Mintlify对GitHub、GitLab的适配非常完善我们可以将Mintlify文档与GitHub/GitLab仓库关联实现文档的自动发布和更新。比如当我们向GitHub仓库提交代码时Mintlify会自动检测文档的修改同步更新线上文档同时还能实现PR预览功能在合并代码之前就能预览文档的修改效果避免文档与代码不一致的问题。7.4 多语言支持与自动翻译Mintlify支持多语言文档生成通过AI自动翻译功能我们可以快速将文档翻译成多种语言如英文、中文、日文等无需手动翻译满足国际化项目的需求。同时还能自定义翻译内容确保翻译的准确性。7.5 文档数据分析Mintlify还支持文档数据分析功能能统计文档的访问量、用户搜索关键词、用户反馈等信息帮助我们了解文档的使用情况优化文档内容提升文档的实用性。结束语在技术快速迭代的今天高效的文档管理已经成为团队协作和项目成功的关键。Mintlify作为一款AI原生的文档自动化工具以其简约的风格、便捷的操作、强大的功能成为了开发者的得力助手。本次的实操教程希望能帮助大家快速掌握Mintlify的核心用法摆脱繁琐的文档编写工作。当然Mintlify还有很多细节功能和高级用法需要我们在实际使用中慢慢探索和熟悉。相信只要大家多动手、多尝试就能充分发挥Mintlify的价值让技术文档成为项目的“加分项”而不是“负担”。最后祝愿每一位开发者都能高效编码、轻松写文档在技术的道路上稳步前行。如果大家在使用Mintlify的过程中遇到问题可以参考Mintlify官方文档https://www.mintlify.com/docs也可以在评论区留言我们一起交流探讨。