llms.txt + Diátaxis:2026 docs 站双标准

影响力:llms.txt 已被 Vercel/Stripe/Anthropic/Mintlify 等部署;SE Ranking 抽样 30 万域名 ~10.13% 已挂;Claude / Perplexity 实际抓取读取(虽非 W3C 标准)。Diátaxis 是 docs 信息架构事实标准(Canonical / Python / Cloudflare / Gatsby 采用)。 干活密度:🟢 干活级 + 🔵 协议级 核心承诺:任何想被 AI 助手 / Claude Code / Cursor / Perplexity 准确引用的 docs 站,2026 都该挂一个 llms.txt

🔥 影响力卡片

• llms.txt 提案:Jeremy Howard / Answer.AI(2024-09)
• 部署示例:https://docs.anthropic.com/llms.txt · https://vercel.com/llms.txt · https://docs.ag-ui.com/llms.txt
• 工具链:Mintlify 自动生成 / starlight-llms-txt(Astro)/ firecrawl-llms-txt(GitHub Action)/ llmstxt-generator(npm)/ WordPress 插件
• Diátaxis 提出者:Daniele Procida
• 主页:https://diataxis.fr · https://github.com/evildmp/diataxis-documentation-framework

🎯 为什么必读

2026 年用户找答案的方式,已经从”搜索 → 点链接”变成”问 AI → 拿答案”。Claude Code / Cursor / Perplexity / ChatGPT 抓你 docs 的频率,可能已经超过人类访问。

如果你不挂 llms.txt,AI 抓你站点要花 100× token,精确度还低(广告 / 导航 / cookie banner 噪声多)。 如果你不用 Diátaxis,docs 越长越乱,文章之间相互交叠重复,AI 和人类都抓不到重点。

这两个 docs 站的”协议化标准”是 2026 必做的两件事。

一句话总结

llms.txt 给 AI 一份”读得懂”的精炼地图;Diátaxis 给人类 + AI 一个不混杂的信息架构 —— 两者解决不同层面的”被理解”问题。

💎 金句墙

★ “llms.txt is to AI agents what robots.txt is to crawlers and sitemap.xml is to search engines.” “llms.txt 之于 AI agent,就是 robots.txt 之于爬虫,sitemap.xml 之于搜索引擎。” —— Mintlify 博客类比。译者点评:robots.txt 控访问,sitemap 给搜索引擎,llms.txt 给 LLM 一份”读得懂”的精炼地图。三者互补 —— 都不是 W3C 标准,但都已成为事实约定

★ “Documentation has four distinct functions. They are not interchangeable.” “文档有四种不同功能。它们不能互换。” —— Daniele Procida 在 Diátaxis 主页第一句。译者点评:这是 Diátaxis 的全部论点 —— Tutorials / How-to guides / Reference / Explanation 必须严格分开,混写就会失败。这听起来像废话,但 90% 的开源项目 docs 都做不到

📋 核心精读

一、llms.txt 协议

1. 三种文件

/llms.txt              — Markdown 导航文件(给 AI 一份精炼地图)
/llms-full.txt         — 整站文档单文件(适合 RAG 一次性 ingest)
/llms-small.txt        — 极简版(只保结构,给小上下文窗模型)

2. 最简结构(~30 行就够)

# Project Name           (H1 必填)
> One-line summary       (blockquote 摘要,可选)

Optional intro paragraph(s).

## Docs                  (H2 + 链接列表)
- [Getting Started](https://example.com/docs/start.md): Quick start guide
- [API Reference](https://example.com/docs/api.md): Complete API documentation
- [Configuration](https://example.com/docs/config.md): Config options

## Examples
- [Basic example](https://example.com/examples/basic.md): Hello world
- [Advanced example](https://example.com/examples/advanced.md): Production setup

## Optional             (LLM 在 token 紧张时可丢弃)
- [Changelog](https://example.com/changelog.md): Version history
- [Migration guide](https://example.com/migrate.md): v1 → v2

🟢 译者点评:关键约定:链接 URL 末尾加 .md 让 LLM 拿到 Markdown 而不是 HTML(节省 80% token)。## Optional 段落是显式信号 —— LLM token 不足时可以跳过。

3. 工具自动生成

# Astro Starlight
npm i starlight-llms-txt

# Mintlify(自动生成,无需配置)
# Fumadocs / Docusaurus 已或正在原生支持

# 通用
npx llmstxt-generator

🟢 译者点评:Astro 用 starlight-llms-txt(delucis 维护,Starlight 官方系) 是当前 OSS docs 最简方案。Mintlify 商业方案直接默认带。

4. 关键事实(2026-05)

5. 已部署示例(可参考学习)

• https://docs.anthropic.com/llms.txt
• https://docs.ag-ui.com/llms.txt
• https://vercel.com/llms.txt
• https://stripe.com/docs/llms.txt

二、Diátaxis 框架

1. 4 类信息架构

🟢 译者点评:这 4 类不能互换。Tutorial 必须以”学习者完成第一步成功”为目标(不是教完所有功能);How-to 假设读者已胜任(不解释基础);Reference 不解释 why(只列事实);Explanation 不教步骤(讨论上下文)。

2. 顶级目录映射

docs/
├── tutorials/       # 学习者起步
├── guides/          # 已胜任的任务清单
├── reference/       # API / 配置 / CLI 速查
└── explanation/     # 设计决策 / 历史 / 权衡

🟢 译者点评:Astro Starlight / Fumadocs / Nextra 的 sidebar 直接套这 4 个顶级目录是最稳的起手式。

3. 经典实践案例

• Canonical (Ubuntu):https://documentation.ubuntu.com — Diátaxis 起源,产品文档全套架构
• Django:https://docs.djangoproject.com — 最早采用 Diátaxis 的大型 OSS
• Cloudflare:https://developers.cloudflare.com — 大规模 docs 长期维护后采用
• Python:在迁移过程中
• Gatsby:https://www.gatsbyjs.com/docs

🟢 译者点评:这些项目都是被”docs 越写越乱”逼到不得不重构的。Diátaxis 5-min intro 是必读(diataxis.fr/start-here/)。

4. 反模式

• ❌ “Getting Started” 里既教概念又写步骤(混 Tutorial + Explanation)
• ❌ “API Reference” 里穿插 “Why we chose this design”(Reference 混 Explanation)
• ❌ Tutorial 假设读者已经懂(应该 zero-experience friendly)

🟢 译者点评:90% 的 docs 都是这些反模式的混合体。Diátaxis 的价值是给你一个清晰的”分类标尺”。

三、双标准协同 docs 站结构

your-docs/
├── llms.txt              # AI 入口:精炼链接清单
├── llms-full.txt         # AI 全文 ingest
├── tutorials/            # Diátaxis 1:学习
├── guides/               # Diátaxis 2:任务
├── reference/            # Diátaxis 3:信息
├── explanation/          # Diátaxis 4:理解
└── _meta/
    ├── README.md
    └── DIATAXIS.md       # 团队对 4 类的约定

🟢 译者点评:llms.txt 引用 Diátaxis 4 个顶级目录,AI 拿到清晰地图。一个站点同时让人类和 AI 都”读得懂”。

🟢 译者总评

1. 现在就做的:/llms.txt 是低成本高收益,1 小时搞定;Diátaxis 重构需要 1-2 周,但是值
2. OSS 项目优先级:llms.txt 是”被 AI 引用的入场券”,挂上后,Claude Code / Cursor / Perplexity 引用你的概率显著提高(降低 token 成本)
3. 新 docs 站起手就上 Diátaxis:从一开始就分 4 类目录,远比后期重构便宜
4. 存量 docs 重构:先按 Diátaxis 分,再补 llms.txt —— 顺序不能反(没有清晰架构,llms.txt 只是垃圾索引)
5. 配套读:Astro Starlight / Fumadocs 是双标准最易实现的工具
6. 关键 caveat:llms.txt 不是 ranking factor;不要期望它给你 SEO 排名提升

🔗 调研来源

• llms.txt spec
• llms.txt — Answer.AI 提案
• Mintlify — Best llms.txt platforms 2026
• starlight-llms-txt
• astro-llms-txt
• Generate llms.txt with Astro
• Mintlify — Simplifying docs with llms.txt
• Diátaxis homepage
• Diátaxis in 5 minutes
• Daniele Procida — Diátaxis github
• Cloudflare developer docs (Diátaxis 实战)