Dify 技术文档工程实践：如何构建面向 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 对话，让开发者或用户可以通过自然语言提问的方式获取接口使用说明、集成指南或排障建议，减少重复咨询，提升支持效率与产品好感度。

先谋而后动

1. 明确问题，弃用 Gitbook

此前 Dify 文档使用的框架为 Gitbook，它见证了第一版的文档和整个项目的开源。但随着时间的演进，它逐渐暴露出了非常多底层的问题。来看看我自接手文档写作以来所积攒的问题列表吧（否则我也不会这么想要换掉它）：

根本原因在于该平台的产品定位面向不具备编程能力的业务人员，旨在提供技术写作与协作能力，因此大部分操作依赖图形化界面完成。尽管平台支持通过 IDE 拉取代码进行文档维护，但由于本地环境无法预览渲染效果，使用体验受到较大限制。

Gitbook 并不是一个 Doc as Code 的产品。

此外，平台内置编辑器的渲染效果与最终发布页面存在明显差异，实际呈现效果与预期之间常出现落差，技术实现上的不一致性为使用者带来了诸多困扰。

在处理外部用户投稿内容时也面临类似问题：部分样式或渲染代码无法实现实时预览，上线结果往往无法预测，类似"开盲盒"的体验。考虑到当前团队已明确新的发展方向，首要决策即为停止使用 GitBook 平台，寻找新的替代。

2. 围绕目标，充分调研

我始终坚持这样一种观点：文档是产品的一部分。正因如此，任何对文档系统的重大调整，必须在充分思考与权衡之后再做决策，尤其是在迈向 AI 化转型的关键阶段。

据不完全统计，当时 Dify 的文档总量已超过 600 篇，且内部嵌套的引用链接繁多、结构复杂。如果将整个文档系统比作一座建筑，这座新"大楼"的设计寿命至少应为三年以上，甚至可能在较长时间内保持稳定。因此，新的文档框架不仅要延续既有的良好体验，还需具备良好的可维护性与未来可持续扩展的能力。

为此，我对市面上的主流技术文档框架进行了调研与实际使用，并整理成对比表格，供团队参考，也希望对有类似需求的朋友有所帮助。

如果微信表格渲染有异常，请在浏览器打开原文链接：https://docs.pflm.net/zh-hans/insights/dify-docs-restructure

在深入试用和比较之后，我将候选框架聚焦于两款：Mintlify 与 Docusaurus。

• Mintlify 在视觉美观性与 API 文档自动生成方面表现成熟，默认样式即可满足大部分展示需求，是一款专注于商业化文档体验的框架。

• Docusaurus 作为开源项目，在功能的可扩展性上略逊一筹。但 API 文档集成也需依赖额外的转换工具，虽然其开源生态活跃、可扩展性强，但其实更适合具备 React 前端开发能力的团队。

最终，综合考虑后期维护的便利性、开箱即用的表现力，以及背后团队对 AI 能力的整合与投入，我选择了 Mintlify 作为新的文档系统解决方案。同时也安利 Mintlify 的 Blog，他们输出了非常多面向 AI 时代文档建设的洞察。

行动

1. 熟悉框架，小步迭代

在确定使用 Mintlify 作为新一代文档框架后，我第一时间搭建了一个 Demo 网站，供内部技术写作团队进行实际体验。同时，我也主动组织了多轮沟通与宣讲，帮助团队充分理解新框架的优势与使用方式。通过持续的沟通与反馈收集，最终逐步赢得了团队其他成员的认同与支持。

整个迁移过程对我而言也是一次极具价值的学习经历。我几乎完整阅读并实践了 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 对这部分的设计逻辑。它所采用的语法不仅不直观，甚至可以说是"匪夷所思"。以下是一个简单的语法对比示例（目标是实现"信息提示"效果）：

## Dify{% hint style="info"%}The name Dify comes from**D**o **I**t **F**or**Y**ou.{% endhint %}

## Dify<Info>The name Dify comes from**D**o **I**t **F**or**Y**ou.</Info>

可以看出，GitBook 采用了 {%%} 这一特殊语法标记，这种写法不仅可读性差，而且在大多数 Markdown 编辑器或网页渲染环境中容易引发错误。例如 { 和 % 是许多前端框架中保留的特殊符号，极易导致页面渲染失败或结构错乱。

解决办法：语法格式交由 AI 转换，构建自动化工具链

为解决这一问题，我提出了一个简单而高效的方案：将所有常用样式语法的对应关系梳理出来，并作为上下文注入到 Prompt 中，由 AI 自动完成文档语法格式的转换。

这对于 Dify 应用而言简直是小 Case，我选择使用最基础的 Chat 类型应用进行搭建，自动转换文档内容和结构。该工具支持：

• 自动识别 GitBook 中的特殊语法
• 根据预设规则转换为 Mintlify 所支持的 MDX 格式
• 统一样式语义，避免渲染错误

经过实战检验，该工具在迁移过程中取得了良好效果，能够有效规避格式不统一带来的潜在问题。效率直接拉满。

MD 转 MDX 助手体验地址：https://cloud.dify.ai/app/4fd52bb9-ab93-40f1-8bb0-6c76bd336206/configuration

问题 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 化功能。我也迅速编写了相关指南，帮助我们的用户部署专属的文档问答服务：https://docs.dify.ai/zh-hans/learn-more/extended-reading/dify-docs-mcp

实际测试中，文档问答的效果令人惊喜，真正实现了"在文档中与 AI 对话"的体验。

MCP 功能发布不久后，Mintlify 官方也上线了内置的 AI 对话功能。无论是查阅复杂内容，还是理解长段代码，用户都可以直接在页面内与 AI 进行交互，获取实时帮助。这一能力极大提升了技术文档的可读性与用户自助解决问题的效率。

一键全文问 AI	实时文档对话功能

在那个瞬间，我突然意识到：这正是一场两个 PLG（Product-Led Growth）产品之间的梦幻联动。

Dify 专注于构建生产级 Agentic 应用搭建平台，Mintlify 深耕技术文档领域。双方在各自擅长的方向上付出了充足的认知与打磨，无需反复营销"卖点输出"，就能在交汇点上自然地为用户带来真实价值。

如今，Mintlify 已成为 Claude、Cursor、Perplexity 等主流 AI 厂商的文档首选框架，它的演进路径正在印证技术产品应有的"好看、好用、可成长"。

而我也终于可以自豪地说：作为一个技术文档工程师，所能做的远不止是写好文档。TA 的职责，更应是文档产品的负责人，有责任为用户提供可信的内容、流畅的阅读体验与可持续的使用路径。

在信息密度与时间成本都极高的今天，如果每个人都能在自己的力所能及处做到极致，整个系统、乃至世界，本就会自然向好。