> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pflm.net/llms.txt
> Use this file to discover all available pages before exploring further.
# Dify 技术文档工程实践：如何构建面向 AI 时代的知识系统？
> 从 Gitbook 到 Mintlify，一次面向 AI 时代内容服务的基础设施重构实践
如果文档是产品的一部分，你希望获得怎样的阅读体验？文档又应该以何种姿态面向新读者——无所不在的 LLM？
大家好，我是 Allen，来自 Dify 的技术文档工程师。
从 2025 年 4 月开始，我主导并完成了 Dify 帮助文档框架的一次全量迁移工程——从 Gitbook 到 Mintlify。完成从调研选型、Demo 实测、样式兼容、链接重构到最终上线的全过程。这不只是技术栈的替换，更是一次面向 AI 时代内容服务的基础设施重构。
以下是迁移前后对比。乍一看好像没啥区别，这一切值得吗？
| 原文档（Powered by Gitbook） | 现文档（Powered by Mintlify） |
| --------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
|  |  |
## AI 时代下的知识服务
要回答这件事是否值得，取决于你是否愿意专门为 AI 提供一套适应它们阅读习惯的文档。如果单独抛开迁移这件事本身而言，而是升华到行为背后的动机，则必须回答关键问题：**面向 AI 时代的内容的知识体系，应该如何重新组织信息？**
AI 革命爆发以前，所有的软件文档皆是为人类设计的。排版布局需要考虑美观吸睛、阅读友好。信息要分层递进，逐步深入。拿常规的 SEO 而言，想要让搜索引擎精准的在茫茫内容中找到你的内容，你需要在 HTML、元数据或内容地图上下足功夫。
哪怕抛开 SEO 要素，面向人类的文档通常要求设计简洁优美，布局清晰；而对于 LLM 来说，外在都是表象，它需要的是足够长的上下文。不求精巧的排版，但求内容的充分详实。
### 不同时代下的信息检索路径
我们不妨假想一个场景，用户在什么情况下需要文档？很显然，TA 遇到了问题。过往的信息检索路径可能是：
**传统检索：**
**输入遇到的问题 / 输入产品名称 + 问题关键词 → 由搜索引擎挑选排名权重靠前的网站中的内容 → 推荐合适的解决方案**
用户行为可被抽象为三种路径：
1. 通过搜索引擎查找内容
2. 浏览文档层次结构
3. 使用文档搜索功能
[Stripe 文档](https://docs.stripe.com/)可谓是在这条路上达成了登峰造极般的程度。团内任意角色的用户，都可以在文档内快速找到所需信息。文档甚至会为已登录的用户，自动生成专属于用户团队的测试代码。
而在 LLM 互动时代，问题的解决路径变为了：
**询问 LLM → 由 LLM 给出推荐方案 → 用户提问反馈 → LLM 给出详细的手把手教学**
用户无需浏览各个部分或搜索特定页面，而是转向 LLM 寻求即时答案，而不必自行将来自不同页面的信息拼凑在一起来获取结论。
## LLM 所带来的改变
毫无疑问，**大型语言模型 (LLM) 正在改变搜索引擎优化 (SEO)**。这同时还催生出了一个新领域：**生成式引擎优化 (GEO)**。有研究预测，来自 LLM 的搜索流量将从 2024 年占所有搜索量的 0.25% 飙升至 2025 年底的 10%。
研究链接：[AI SEO Study 2024](https://previsible.io/seo-strategy/ai-seo-study-2024/)
对于一切围绕产品的使用而设计的技术文档而言，这样的趋势将颠覆客户查找信息并最终通过产品获得成功的方式。
LLM 会优先考虑提供什么样的内容？当然是它最了解和熟悉的方法，亦或是互联网上大家通常采取的策略。
它俨然已成为最大的内容消费者，疯狂地吞噬互联网上的一切内容。甚至随着 Agent 工具的出现，它终将长出手和脚，基于它所掌握的信息，代替人类完成对物理世界的交互。
而在这场变革中，技术文档工程师（Technical Writer）所输出的内容，将显著影响 LLM 对于目标产品的掌握。
若要真正做到对 LLM 友好，技术文档需具备一个关键能力：自动生成 llm.txt 文件。
llms.txt 是一个纯 Markdown 文件，它以简洁的方式概括了您最重要的内容，并以易于 LLM 阅读的方式组织结构，避免了 HTML、JavaScript 或广告的杂乱。
除了 LLM 阅读友好，作为一个开发者工具文档，本就应该确保开发者用户的交互体验。最常见的功能便是 API 文档，最好支持所见即所得的在线调试体验。至此，整套升级行动所要实现的目标也就此确立：
1. **LLM 爬取友好**
全面兼容 GMO，让产品或解决方案更容易出现在 AI 的自然语言回答中，从搜索引擎到智能助手，全面提升可见性。
2. **具备 API 文档**
提供完整且清晰的 API 文档，支持在线调试与示例调用，帮助开发者快速理解接入方式，显著提升人类程序员的开发效率与使用意愿。
3. **支持 AI 文档对话**
支持基于文档的 AI 对话，让开发者或用户可以通过自然语言提问的方式获取接口使用说明、集成指南或排障建议，减少重复咨询，提升支持效率与产品好感度。
确保文档对 AI 模型友好
具备 API 文档，并提供基础的调试功能
最好支持 AI 文档对话功能
## 先谋而后动
### 1. 明确问题，弃用 Gitbook
此前 Dify 文档使用的框架为 Gitbook，它见证了第一版的文档和整个项目的开源。但随着时间的演进，它逐渐暴露出了非常多底层的问题。来看看我自接手文档写作以来所积攒的问题列表吧（否则我也不会这么想要换掉它）：
| 序号 | 问题描述 | 问题类型 | 严重等级 |
| -- | ------------------------------------------ | ---- | ---- |
| 1 | 添加超链接时经常出现异常，有时页面卡死，无法添加或删除内容 | 功能缺陷 | 高 |
| 2 | 多人共同编辑文档时出现异常白屏 | 功能缺陷 | 高 |
| 3 | 官方客服响应体验差，提交反馈后没有出现填写反馈的对话框 | 用户体验 | 中 |
| 4 | 目录结构过于垂直，阅读体验很糟糕，无法一眼看出层级关系 | 用户体验 | 中 |
| 5 | 评论时，第一次评论无法输入文字，需再点击一次评论框才能评论 | 功能缺陷 | 低 |
| 6 | API 文档渲染异常 | 功能缺陷 | 高 |
| 7 | 自动添加多余字符，且有冲突内容需要自行排查，不提供自动排查功能 | 功能缺陷 | 中 |
| 8 | 会自动修改已创建的文档内容，导致原先的文档失效 | 功能缺陷 | 高 |
| 9 | 错误的数据应用，没有引用 GitHub 链接但自动替换为了 GitHub 链接 | 功能缺陷 | 中 |
| 10 | 不直观的隐藏更改 | 用户体验 | 低 |
| 11 | 前端显示预期不一致，代码仓库里已有正常内容，但英文前端显示异常（中日语言内容无异常） | 功能缺陷 | 中 |
| 12 | 没有完整有效的预览地址，需要在 GitBook 内部生成，跨部门内容预览体验不畅 | 用户体验 | 低 |
根本原因在于该平台的产品定位面向不具备编程能力的业务人员，旨在提供技术写作与协作能力，因此大部分操作依赖图形化界面完成。尽管平台支持通过 IDE 拉取代码进行文档维护，但由于本地环境无法预览渲染效果，使用体验受到较大限制。
> Gitbook 并不是一个 Doc as Code 的产品。
此外，平台内置编辑器的渲染效果与最终发布页面存在明显差异，实际呈现效果与预期之间常出现落差，技术实现上的不一致性为使用者带来了诸多困扰。
在处理外部用户投稿内容时也面临类似问题：部分样式或渲染代码无法实现实时预览，上线结果往往无法预测，类似"开盲盒"的体验。考虑到当前团队已明确新的发展方向，**首要决策即为停止使用 GitBook 平台，寻找新的替代**。
### 2. 围绕目标，充分调研
我始终坚持这样一种观点：**文档是产品的一部分**。正因如此，任何对文档系统的重大调整，必须在充分思考与权衡之后再做决策，尤其是在迈向 AI 化转型的关键阶段。
据不完全统计，当时 Dify 的文档总量**已超过 600 篇**，且内部嵌套的引用链接繁多、结构复杂。如果将整个文档系统比作一座建筑，这座新"大楼"的设计寿命至少应为三年以上，甚至可能在较长时间内保持稳定。因此，新的文档框架不仅要延续既有的良好体验，还需具备良好的可维护性与未来可持续扩展的能力。
为此，我对市面上的主流技术文档框架进行了调研与实际使用，并整理成对比表格，供团队参考，也希望对有类似需求的朋友有所帮助。
| 功能分类 | 功能项 | [GitBook](https://www.gitbook.com/) | [Mintlify](https://mintlify.com/) | [Starlight](https://starlight.astro.build/) | [Docusaurus](https://docusaurus.io/) | [Nextra](https://nextra.site/docs) | [Gatsbyjs](https://www.gatsbyjs.com/docs/conceptual/graphql-concepts/) |
| ----------- | ---------------- | ----------------------------------- | ---------------------------------------------------- | ------------------------------------------- | ------------------------------------ | -------------------------------------------- | ---------------------------------------------------------------------- |
| **内容展示** | 文档代码行高亮 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| | ⭐️ 本地文档预览 | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ |
| **内容管理** | ⭐️ 文档版本控制 | ❌ | ✅ | ✅ 需配合插件 | ✅ | ❌ | ✅ |
| | ⭐️ 文档多语言 | ✅ | ✅ | ✅ | ✅ | ✅ using i18n | ✅ |
| | ⭐️ 内容重定向 | ❌ | ✅ | ✅ | ✅ | ✅ for language only with middleware | ✅ |
| **内容输出** | 导出为 PDF | ✅ 但需要更高级别的付费 | ✅ | ✅ 通过插件支持 | ✅ 通过插件支持 | ❌ | ❌ |
| | ⭐️ API 文档 | ✅ 但渲染异常有 Bug | ✅ | ✅ 需配合 RapidAPI 实施 | ✅ 需配合插件 | ✅ Can customize different kind of UI with JS | ✅ |
| | MCP Server | ❌ | ✅ | ❌ | ✅ 通过插件支持 | - | - |
| **部署与运维** | 本地部署 | ❌ 仅提供 SaaS 服务 | ✅ 官方提供部署 不支持手动打包为静态网页 | ✅ | ✅ | ✅ with Next.js | ✅ |
| **用户交互与编辑** | 文档可视化编辑后台 | ✅ | ✅ | ❌ 纯代码编辑 | ❌ 纯代码编辑 | ❌ | ❌ |
| | 自定义能力支持 | ❌ | ✅ 可更改范围受限 | ✅ | ✅ | ✅ | ✅ |
| **协作与管理** | 自动显示文档作者 | ❌ | ❌ | ❌ | ✅ 需二次开发 | ❌ | ❌ |
| | 文档页的 GitHub 地址关联 | ✅ | ✅ | ✅ 需二次开发 | ✅ 需二次开发 | ✅ | ✅ |
| **开发与集成** | 开发 SDK | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ |
| **商业与支持** | 费用 | 免费计划 / 79 美元起多人协作 | 免费计划/ Pro 计划 150 美元月 | 开源项目 | 开源项目 | 开源项目 | 开源项目 |
| | 官方技术支持 | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| **参考信息** | 谁在用？ | NordVPN、Raycast、Make 等 [完整客户名单](链接) | Cursor、Anthropic、Perplexity、Zapier 了解更多：[完整客户名单](链接) | Astro项目 | 各行各业 [完整客户名单](链接) | Open-source project | 各行各业 |
在深入试用和比较之后，我将候选框架聚焦于两款：**Mintlify** 与 **Docusaurus**。
* **Mintlify** 在视觉美观性与 API 文档自动生成方面表现成熟，默认样式即可满足大部分展示需求，是一款专注于商业化文档体验的框架。
* **Docusaurus** 作为开源项目，在功能的可扩展性上略逊一筹。但 API 文档集成也需依赖额外的转换工具，虽然其开源生态活跃、可扩展性强，但其实更适合具备 React 前端开发能力的团队。
最终，综合考虑后期维护的便利性、开箱即用的表现力，以及背后团队对 AI 能力的整合与投入，我选择了 Mintlify 作为新的文档系统解决方案。同时也安利 Mintlify 的 Blog，他们输出了非常多面向 AI 时代文档建设的洞察。
## 行动
### 1. 熟悉框架，小步迭代
在确定使用 Mintlify 作为新一代文档框架后，我第一时间搭建了一个 Demo 网站，供内部技术写作团队（TW）进行实际体验。同时，我也主动组织了多轮沟通与宣讲，帮助团队充分理解新框架的优势与使用方式。通过持续的沟通与反馈收集，最终逐步赢得了团队其他成员的认同与支持。
整个迁移过程对我而言也是一次极具价值的学习经历。我几乎完整阅读并实践了 Mintlify 的官方文档（事实证明，他们在技术写作领域非常专业），对其支持的功能、可用的组件样式、内容组织方式等有了全面的掌握。
在实际使用过程中，最显著的区别之一在于：Mintlify 并未采用传统技术文档中常见的 .md（Markdown）格式，而是基于 .mdx 文件结构。这一格式结合了 Markdown 与 JSX 的能力，使文档在保持简洁语法的同时，也具备了更强的交互与组件调用能力。
但放在当下 AI 技术快速发展的背景下，内容格式的迁移与转换已不再是技术壁垒，反而是可以快速自动化解决的小问题。因此，我更看重的是其结构的未来可扩展性与智能工具的融合潜力。
| 原 Gitbook 语法结构 | Mintlify 语法结构 |
| ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
|  |  |
### 2. 明确问题，逐个攻破
随着我对两个文档框架的深入对比与实践，逐步识别出几个历史遗留问题和核心问题。如果这些问题得到有效解决，其它次要问题也将随之迎刃而解。
#### 问题 1：图片处理机制不清晰，影响长期可维护性
在原有的文档体系中，图片并未采用统一的在线图床方案进行管理。一方面，随着文档体量不断扩大，仓库体积也随之膨胀；另一方面，图片的命名方式和存储路径缺乏规范，管理混乱。现实中，很难指望每位写作者在上传图片时能做到手动重命名、规划路径、统一管理。
此外，GitBook 采用私有资源托管，查询后发现并未启用 CDN 服务。这导致在上传或访问图片时，尤其是在不同地区网络条件下，出现明显的加载延迟和不稳定性，进一步影响用户体验。
**解决办法：** 为解决上述问题，我采用 **Pico + S3 存储** 的方式自建在线图床，实现图片上传的自动化处理与统一索引管理：
* **自动命名与归档**：上传图片时系统自动生成规范化命名，避免重名与路径冲突
* **图床独立部署**：图片资源脱离主代码仓库存储，减轻 Git 压力
* **CDN 加速分发**：结合 S3 及全球 CDN 服务，实现跨地域快速加载
* **上传体验优化**：写作者可"无脑上传"，后端自动完成分类与引用路径的整理
目前该方案已在内部启用，我顺带贡献了一篇面向内部的图床使用指南。
在引入图床方案之后，**新上传图片的处理方式已有清晰方案**，通过在线图床与自动命名机制，实现了流畅且可维护的上传体验。然而，对于大量历史文档中引用的本地图片，仍然存在迁移难题：这些图片分布零散、命名混乱，且手动替换成本极高。
我让实习生帮忙写了一套自动化处理脚本，实测效果也很不错。通过 Vibe Coding，我们用很少的人力就解决了可能是整个迁移工作中最繁琐的任务——图片处理。
#### 问题 2：语法格式不统一，易出错且缺乏可维护性
文档的语法格式，通常指的是页面中用于展示视觉提示的内容样式，例如高亮块、提示框、警告框等。这类样式在不同框架中通常通过特定语法标记来实现，写作者只需在 Markdown 中插入对应代码块，即可获得对应的页面效果。
但在实际使用过程中，我始终无法理解 GitBook 对这部分的设计逻辑。它所采用的语法不仅不直观，甚至可以说是"匪夷所思"。以下是一个简单的语法对比示例（目标是实现"信息提示"效果）：
```markdown Gitbook 示例 theme={null}
## Dify
{% hint style="info" %}
The name Dify comes from **D**o **I**t **F**or **Y**ou.
{% endhint %}
```
```markdown Mintlify 示例 theme={null}
## Dify
The name Dify comes from **D**o **I**t **F**or **Y**ou.
```
可以看出，GitBook 采用了 `{% %}` 这一特殊语法标记，这种写法不仅可读性差，而且在大多数 Markdown 编辑器或网页渲染环境中容易引发错误。例如 `{` 和 `%` 是许多前端框架中保留的特殊符号，极易导致页面渲染失败或结构错乱。
**解决办法：语法格式交由 AI 转换，构建自动化工具链**
为解决这一问题，我提出了一个简单而高效的方案：将所有常用样式语法的对应关系梳理出来，并作为上下文注入到 Prompt 中，由 AI 自动完成文档语法格式的转换。
这对于 Dify 应用而言简直是小 Case，我选择使用最基础的 Chat 类型应用进行搭建，自动转换文档内容和结构。该工具支持：
* 自动识别 GitBook 中的特殊语法
* 根据预设规则转换为 Mintlify 所支持的 MDX 格式
* 统一样式语义，避免渲染错误
经过实战检验，该工具在迁移过程中取得了良好效果，能够有效规避格式不统一带来的潜在问题。效率直接拉满。
[MD 转 MDX 助手体验地址](https://udify.app/chat/nM8Mi5ZJF8yitTYK)
#### 问题 3：文档内超链接引用结构复杂，需统一管理
在大型文档系统中，**文档之间存在大量交叉引用**是极为常见的现象。例如，A 文档中嵌套引用 B 文档的链接，以实现内容跳转与结构关联。然而在旧有系统中，这类链接格式极不统一，既有完整的线上链接（如 `https://example.com/xxx`），也有文档仓库中的相对路径引用（如 `../b.md`）。不同写作者的习惯差异，加之缺乏系统性规范，导致迁移过程中链接处理变得尤为复杂、易错且繁琐。
面对这一问题，我继续采用 Vibe Coding 的方法论，并结合人类监督机制，设计了一套高效可控的处理流程，用 Python 脚本代替手动操作：
1. 自动识别文档中的所有链接引用；
2. 将引用目标在页面中高亮展示，并智能推荐替换后的链接路径；
3. 由人工快速点击确认推荐是否正确；
4. 确认后统一执行替换操作。
该流程既保留了 AI 的高效识别能力，又通过人工确认环节避免错误替换，极大缓解了需要逐个文档比对、核实的工作负担。
### 3. 最终上线：确保平稳过渡
在解决完所有显性问题后，我正式敲定了新文档框架的上线日期。在此之前，我对每一个页面的跳转路径与访问情况进行了逐一人工排查，确保用户在迁移后仍可顺利浏览各类内容。
值得一提的是，**文档重定向问题**同样是一个不可忽视的环节。由于 GitBook 与 Mintlify 所采用的文档结构存在较大差异，URL 路径的调整不可避免。为此，我一度考虑通过域名级的策略，在上线时引入 **A/B 灰度测试**，以实现平滑过渡与风险控制。然而，在尝试配置 Cloudflare 规则过程中遇到了一些技术阻碍，评估后认为对一个文档项目而言，引入过多部署复杂度并不划算，最终决定简化方案，回归核心目标：**稳定、可访问、不影响用户体验**。
完成所有准备工作后，我联系了运维团队进行正式的流量切换。上线当天，我独自在会议室中不停刷新各个关键页面，实时监控迁移效果。幸运的是，**没有翻车，甚至大多数用户都没有察觉到文档系统已完成更替**。由于两套系统在视觉风格上保持了一定程度的一致性，再加上旧链接的跳转逻辑处理得当，整个迁移过程实现了"平滑切换，零感知"。
基建完成后，API 文档部分也在 DevRel 同事的协助下顺利上线，为整个文档体系的结构化建设补上了关键一环。
为进一步提升用户反馈的响应链路，文档也部署了辅助脚本，实现对所有文档页面的自动化反馈入口嵌入。该脚本会在每个页面底部统一添加反馈模块，方便用户对内容进行评价或提出建议。
这一机制不仅提升了用户参与度，也为后续的文档迭代与优化提供了数据基础，形成了"内容发布—用户反馈—内容更新"的正向循环。
## 文档的背后，是对阅读体验的全局掌控
这场迁移不仅是一项技术挑战，更是一种角色认知的重塑。
在完成文档系统迁移与结构优化后，我已尽可能完成所有能做的工作。而 Mintlify 功能的快速迭代，也进一步验证了我的判断：这是一个**有品位、有追求的产品**。
2025 年 3 月，MCP 成为技术社区的热门议题。Mintlify 第一时间支持了文档的 MCP 化功能。我也迅速编写了相关指南，帮助我们的用户部署专属的文档问答服务：
了解如何部署专属的文档问答服务
实际测试中，文档问答的效果令人惊喜，真正实现了"在文档中与 AI 对话"的体验。
MCP 功能发布不久后，**Mintlify 官方也上线了内置的 AI 对话功能**。无论是查阅复杂内容，还是理解长段代码，用户都可以直接在页面内与 AI 进行交互，获取实时帮助。这一能力极大提升了技术文档的可读性与用户自助解决问题的效率。
| 一键全文问 AI | 实时帮助功能 |
| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
|  |  |
在那个瞬间，我突然意识到：这正是一场**两个 PLG（Product-Led Growth）产品之间的梦幻联动**。
Dify 专注于构建生产级 Agentic 应用搭建平台，Mintlify 深耕技术文档领域。双方在各自擅长的方向上付出了充足的认知与打磨，无需反复营销"卖点输出"，就能在交汇点上自然地为用户带来真实价值。
如今，**Mintlify 已成为 Claude、Cursor、Perplexity 等主流 AI 厂商的文档首选框架**，它的演进路径正在印证技术产品应有的"好看、好用、可成长"。
而我也终于可以自豪地说：作为一个技术文档工程师，所能做的远不止是写好文档。TA 的职责，更应是**文档产品的负责人**，有责任为用户提供可信的内容、流畅的阅读体验与可持续的使用路径。
在信息密度与时间成本都极高的今天，如果每个人都能在自己的力所能及处做到极致，整个系统、乃至世界，本就会自然向好。
## 参考资料
[How Generative Engine Optimization is Reshaping Docs](https://mintlify.com/blog/how-geo-is-reshaping-docs)