Dify 技术文档工程实践：如何构建面向 AI 时代的知识系统？
从 GitBook 迁到 Mintlify 的全过程：面向 LLM 的知识服务、框架调研，以及图片、语法和链接三类迁移问题。
本页目录
如果文档是产品的一部分，你希望获得怎样的阅读体验？文档又应该以何种姿态面向新读者——即无所不在的 LLM？
大家好，我是 Allen，来自 Dify 的技术文档工程师。
从 2025 年 4 月开始，我主导并完成了 Dify 帮助文档框架的一次全量迁移工程——从 GitBook 到 Mintlify。完成从调研选型、Demo 实测、样式兼容、链接重构到最终上线的全过程。这不只是技术栈的替换，更是一次面向 AI 时代内容服务的基础设施重构。
迁移前后对比：
原文档（Powered by GitBook）
现文档（Powered by Mintlify）
#AI 时代下的知识服务
要回答这件事是否值得，取决于你是否愿意专门为 AI 提供一套适应它们阅读习惯的文档。面向 AI 时代的知识体系，应该如何重新组织信息？
AI 革命爆发以前，所有的软件文档皆是为人类设计的。排版布局需要考虑美观吸睛、阅读友好。信息要分层递进，逐步深入。哪怕抛开 SEO，面向人类的文档通常要求设计简洁优美、布局清晰；而对于 LLM 来说，外在都是表象，它需要的是足够长的上下文。不求精巧的排版，但求内容的充分详实。
#不同时代下的信息检索路径
传统检索：输入遇到的问题 / 输入产品名称 + 问题关键词 → 由搜索引擎挑选排名靠前的内容 → 推荐合适的解决方案。
用户行为可被抽象为三种路径：
- 通过搜索引擎查找内容
- 浏览文档层次结构
- 使用文档搜索功能
Stripe 文档 在这条路上做到了极致。团内任意角色的用户，都可以各自在文档内快速找到所需信息。文档甚至会为已登录的用户，自动生成专属于用户团队的测试代码。
而在 LLM 互动时代，问题的解决路径变为了：询问 LLM → 由 LLM 给出推荐方案 → 用户提问反馈 → LLM 给出详细的手把手教学。用户无需浏览各个部分或搜索特定页面，而是转向 LLM 寻求即时答案。
#LLM 所带来的改变
大型语言模型正在改变 SEO，并催生出生成式引擎优化（GEO）。有研究预测，来自 LLM 的搜索流量将从 2024 年占所有搜索量的 0.25% 飙升至 2025 年底的 10%。
研究链接：AI SEO Study 2024
对于一切围绕产品使用而设计的技术文档而言，这样的趋势将颠覆客户查找信息并最终通过产品获得成功的方式。技术文档工程师所输出的内容，将显著影响 LLM 对于目标产品的掌握。
若要真正做到对 LLM 友好，技术文档需具备一个关键能力：自动生成 llms.txt。llms.txt 是一个纯 Markdown 文件，以简洁的方式概括最重要的内容，并以易于 LLM 阅读的方式组织结构，避免 HTML、JavaScript 或广告的杂乱。
整套升级行动的目标由此确立：
- LLM 爬取友好。 全面兼容 GEO，让产品更容易出现在 AI 的自然语言回答中。
- 具备 API 文档。 完整清晰，支持在线调试与示例调用。
- 支持 AI 文档对话。 用自然语言提问获取接口说明、集成指南或排障建议。
#先谋而后动
#1. 明确问题，弃用 GitBook
此前 Dify 文档使用 GitBook。它见证了第一版文档和整个项目的开源，但逐渐暴露出大量底层问题：超链接卡死、多人编辑白屏、目录过于垂直、API 文档渲染异常、自动改写已发布内容、没有完整有效的本地预览地址。
根本原因在于该平台面向不具备编程能力的业务人员，大部分操作依赖图形化界面。尽管支持通过 IDE 拉取代码维护文档，但本地环境无法预览渲染效果。GitBook 并不是一个 Docs as Code 的产品。编辑器渲染效果与最终发布页面也常不一致。
团队已明确新的发展方向，首要决策即为停止使用 GitBook，寻找新的替代。
#2. 围绕目标，充分调研
文档是产品的一部分。当时 Dify 的文档总量已超过 600 篇，内部嵌套引用繁多。新框架的设计寿命至少应为三年以上。我对主流技术文档框架做了调研与实测，完整对比表见：Dify 文档重构笔记。
在深入试用之后，候选聚焦于 Mintlify 与 Docusaurus。
- Mintlify 在视觉与 API 文档自动生成方面成熟，默认样式即可满足大部分展示需求。
- Docusaurus 开源、可扩展，但 API 文档集成需额外工具，更适合具备 React 能力的团队。
综合考虑后期维护、开箱即用，以及团队对 AI 能力的投入，我选择了 Mintlify。
#行动
#1. 熟悉框架，小步迭代
确定框架后，我先搭了一个 Demo，组织多轮沟通，逐步赢得团队认同。Mintlify 使用 .mdx 而不是传统 .md。在 AI 技术快速发展的背景下，内容格式转换已不再是壁垒，更看重结构的可扩展性与智能工具的融合潜力。
#2. 明确问题，逐个攻破
#问题 1：图片处理机制不清晰
原体系没有统一图床。仓库体积膨胀，命名和路径缺乏规范。GitBook 私有托管且未启用 CDN，跨地区加载不稳定。
解决办法：Pico + S3 自建图床，自动命名与归档，图片脱离主仓库，CDN 加速。历史本地图片则用脚本批量上传。
#问题 2：语法格式不统一
GitBook 的 hint 语法既不直观，也容易和前端保留符号冲突。对比：
GitBook：
{% hint style="info" %}
The name Dify comes from Do It For You.
{% endhint %}Mintlify：
<Info>
The name Dify comes from Do It For You.
</Info>
解决办法：把常用样式的对应关系注入 Prompt，用 Dify Chat 应用自动把 GitBook 语法转成 Mintlify MDX。
#问题 3：超链接引用结构复杂
既有完整线上链接，也有仓库相对路径。用 Python 脚本识别全部链接、高亮推荐替换路径、人工确认后再统一替换。
#3. 最终上线：确保平稳过渡
上线前逐页排查跳转。GitBook 与 Mintlify 的 URL 结构不同，重定向不可忽视。评估后没有上 A/B 灰度，回归核心目标：稳定、可访问、不影响用户体验。上线当天实现平滑切换，大多数用户没有察觉。API 文档随后在 DevRel 同事协助下上线，并在每页底部嵌入反馈入口。
#文档的背后，是对阅读体验的全局掌控
这场迁移不仅是技术挑战，更是角色认知的重塑。Mintlify 很快支持了文档 MCP。相关指南：在 Dify 文档中与 AI 对话。
Mintlify 官方也上线了内置 AI 对话：
Mintlify 现已成为 Claude、Cursor、Perplexity 等主流 AI 厂商的文档首选框架。
作为一个技术文档工程师，所能做的远不止写好文档。TA 的职责更应是文档产品的负责人：提供可信内容、流畅阅读体验，以及可持续的使用路径。