llmtxt.info
简体中文
English Français Deutsch Español Italiano Русский العربية 日本語
验证文件

面向文档网站的 llms.txt

文档网站是 llms.txt 的理想用例。开发者经常向 AI 助手询问文档相关问题，下面介绍如何帮助它们获得准确答案。

最近更新:

为什么文档网站受益最多

文档站点，例如用 Mintlify、GitBook、Docusaurus 托管，或用 MkDocs 或 Nextra 等工具自建，都是 llms.txt 的理想使用场景。原因很直接： 开发者经常用 AI 助手来浏览文档。像“how do I set up authentication with Acme?”、“what are the webhooks supported by Acme?” 和 “show me the Acme SDK for Python?” 这样的提问，都是文档类问题。

当开发者在 AI 助手中提出这些问题时，助手要么使用 训练数据（可能已有数月之久），要么从网络获取实时内容，要么从一个配置为获取 llms.txt 的兼容工作流中加载 文档。在这三种情况下，答案质量都取决于它能够访问到的文档质量。

llms.txt 是一种告诉兼容客户端哪些页面最重要的机制。对于文档网站，当接收工作流已知且可测试时，这种筛选很有用。

应包含的内容

对于文档网站，以下页面类型通常都应收录在 llms.txt 中：

  • 快速入门指南这是大多数新用户和 AI 助手首先进入的页面。 应引导用户走完获得可用结果的最短路径。如果只包含一个 页面，就包含这一页。
  • 核心概念，即用于解释产品思维模型的一个或多个页面。基本实体有哪些？产品的数据模型如何运作？关键术语是什么？
  • API 参考，即 API 端点、参数和响应架构的完整参考。如果它是一个很长的单页，请链接顶级页面。如果按资源类型分页，请链接资源级页面。
  • SDK 和客户端库指南，每种官方支持的语言或平台各提供一个链接。
  • 身份验证和授权，以及用户和应用如何认证。这是 AI 助手最常被问到的文档问题之一。
  • 常见问题或故障排除指南；如果你有完整的常见问题页面，就值得添加链接。AI 助手可以利用它准确回答常见问题。
  • 更新日志，帮助检索系统区分当前行为与过时的训练数据。

要排除什么

文档站点中的并非每个页面都属于 llms.txt：

  • 内部笔记或团队文档；如果你的文档平台同时托管公开文档和内部团队 Wiki，请仅包含公开文档。
  • 草稿或未列出的页面；尚未准备好供用户访问的页面不应列入 llms.txt。AI 如果引用草稿页面，就是在引用你尚未批准使用的内容。
  • 需认证内容，受登录墙保护的文档无法被 AI 爬虫或代理框架抓取。只包含可公开访问的页面。
  • 已弃用文档，如果你维护产品旧版本的文档，请排除这些页面或明确标注。你不会希望 AI 助手向用户教授已弃用的模式。
  • 非常细粒度的子页面，如果你的 API 参考包含 200 个独立端点页面，不要把这 200 个页面全部链接进去。应链接到顶层参考页，让 AI 从那里继续导航。llms.txt 是内容筛选层，不是站点地图。
  • 营销或销售页面，定价、案例研究和对比页面都是 有用的内容，但它们不是文档。如果你要包含它们，请把它们放在 ## Optional 分节中。

优先级排序

在 llms.txt 的每个部分中，链接顺序很重要。读取该文件的 AI 客户端会将较早出现的链接视为优先级更高。当受到上下文长度限制时，它们可能会在文件中途停止读取。请将最重要的页面放在最前面。

开发者文档网站的建议优先顺序如下：

  1. 快速开始 / 入门
  2. 核心概念或架构概述
  3. API 参考（顶层页面或最常用资源）
  4. 认证 / 授权
  5. SDK 指南（最常用的语言优先）
  6. Webhooks 参考（如适用）
  7. 故障排查 / 常见问题
  8. 更新日志（在 Optional 部分）
  9. 迁移指南（位于可选部分）

从你的导航自动生成

对于页面很多的文档站点，手动维护 llms.txt 并不现实。更好的 做法是在构建时根据文档结构自动生成它。通用 做法：

  1. 使用导航配置作为来源。 大多数文档平台都会在配置文件（sidebar.json、mint.json、mkdocs.yml 等）中定义 导航。这个配置 本身就代表了你整理过、按顺序排列的文档视图，它是生成 llms.txt 的自然输入。
  2. 筛选顶层和第二层条目。 不要包含导航树中的每个叶节点。 提取顶级部分及其直接子项。这样通常会得到 10 至 30 个页面， 这是 llms.txt 的合适范围。
  3. 将每一项映射到绝对 URL。 你的导航配置大概率使用相对路径。 请用你配置的 base URL 将它们转换为绝对 URL。
  4. 将页面标题用作链接文本，将页面描述用作链接描述。 如果页面有元描述，请使用它们。否则，请使用每个页面的第一段。
  5. 输出到公共目录。 将生成的文件写入静态文件所在的位置，以便通过 /llms.txt.

在每次文档构建时运行此生成流程，让 llms.txt 自动与你的导航结构保持同步。

Mintlify 如何处理它

Mintlify 是一个被面向开发者的公司广泛使用的文档平台（许多 AI 时代的开发者工具都在使用它）。Mintlify 会自动生成 llms.txt 和 llms-full.txt ，覆盖其平台上托管的每个文档网站。

从概念上看，Mintlify 的生成方式如下：

  • 网站导航在一个 mint.json 配置文件。该文件指定页面层级，包括哪些页面显示在侧边栏的哪些分节中。
  • 构建时，Mintlify 会读取导航结构并生成一个 llms.txt 文件，其中每个导航项都会成为相应分节中的一个链接条目。
  • 对于 llms-full.txt，Mintlify 会将每个页面的完整 Markdown 内容内联到其链接下方，从而在单个文件中向 AI 检索系统提供完整文档语料库。
  • 两个文件都与文档网站一同部署，并通过标准路径提供（/llms.txt 和 /llms-full.txt).

因此，Mintlify 上的文档网站无需任何手动筛选即可自动获得符合规范的 llms.txt 文件。代价是该文件反映导航结构，而不是手工确定的优先级顺序，因此可能包含人工作者本会放入 Optional 章节或完全排除的低优先级页面。

其他文档平台，如 GitBook、Docusaurus、ReadMe 等，对 llms.txt 的支持程度各不相同。请查看你所用平台的文档或发布说明，了解当前 支持状态。

示例结构

以下是一个虚构开发者文档网站的 llms.txt 示例。此结构适用于大多数提供 REST API 的产品文档网站： 

# Acme Documentation

> Acme is a platform for real-time inventory management. This documentation covers the
> REST API, SDKs for Python and Node.js, and integration guides for common e-commerce
> platforms. The API is used by developers building stock tracking, warehouse management,
> and demand forecasting applications.

## Getting started

- [Introduction](https://docs.acme.example/introduction/): what Acme is and how it works.
- [Quickstart](https://docs.acme.example/quickstart/): create your first integration in five minutes.
- [Authentication](https://docs.acme.example/authentication/): API key setup and OAuth 2.0.
- [Core concepts](https://docs.acme.example/concepts/): products, locations, stock records, and events.

## API reference

- [API overview](https://docs.acme.example/api/): base URL, versioning, and conventions.
- [Products](https://docs.acme.example/api/products/): create, read, update, and delete products.
- [Stock adjustments](https://docs.acme.example/api/stock/): record stock movements and reconcile inventory.
- [Webhooks](https://docs.acme.example/api/webhooks/): event types, payloads, and signature verification.
- [Rate limits](https://docs.acme.example/api/rate-limits/): limits by plan tier.
- [Errors](https://docs.acme.example/api/errors/): error codes and handling recommendations.

## SDKs

- [Python SDK](https://docs.acme.example/sdk/python/): official Python client library.
- [Node.js SDK](https://docs.acme.example/sdk/node/): official Node.js client library.

## Optional

- [Changelog](https://docs.acme.example/changelog/): release notes and breaking changes.
- [FAQ](https://docs.acme.example/faq/): common questions from developers.
- [Migration guide (v1 to v2)](https://docs.acme.example/migration/): upgrading from v1.

继续阅读

来源