llms.txt 格式

llms.txt 是一种专为 AI 和大型语言模型 (LLM) 优化的文档格式标准。本章探讨如何创建和使用 llms.txt 文件来提高文档的 AI 可发现性和可读性。

什么是 llms.txt?

概述

llms.txt 是一种结构化文本格式,旨在使文档对 AI 模型更易于理解。它提供标准化的方式来组织和展示文档内容,使 LLM 能够更有效地索引和检索信息。

text

# 项目名称

项目的简短描述。

## 快速开始

安装和使用的基本说明。

## API 参考

核心 API 和功能的详细信息。

为什么使用 llms.txt?

AI 优化: 使内容更易于 AI 模型理解
改进搜索: 增强基于 AI 的搜索功能
标准化: 提供一致的文档结构
可发现性: 帮助 LLM 找到相关信息
上下文: 为 AI 辅助提供更好的上下文

基本结构

文件格式

llms.txt 文件使用简单的 Markdown 样式格式:

text

# 主标题

## 部分 1
内容描述第一部分。

### 子部分 1.1
详细信息和示例。

## 部分 2
另一个主要部分的内容。

## 标签
关键词、标签、元数据

必需部分

项目标题: 清晰的项目名称
描述: 项目简介
快速开始: 基本使用说明
主要功能: 关键特性列表
文档链接: 指向完整文档的链接

text

# Rspress

Rspress 是一个基于 React 的快速静态站点生成器。

## 描述
Rspress 为文档站点提供强大的功能,具有 MDX 支持、
主题定制和优秀的性能。

## 快速开始
npm install rspress
npx rspress init
npx rspress dev

## 主要功能
- MDX 支持
- 快速构建
- 主题定制
- SSG/SSR 支持

## 文档
完整文档: https://rspress.dev

创建 llms.txt

手动创建

在项目根目录创建 llms.txt:

text

# 我的文档项目

技术文档的综合指南。

## 概述
本文档涵盖我们的 API、指南和最佳实践。

## 安装
npm install my-package

## 配置
// my-config.js
export default {
  theme: 'default',
  title: 'My Docs'
};

## API 端点

### GET /api/users
获取所有用户
返回: 用户对象数组

### POST /api/users
创建新用户
参数: name, email
返回: 创建的用户对象

## 示例

### 基本用法
import { createUser } from 'my-package';

const user = await createUser({
  name: 'John Doe',
  email: 'john@example.com'
});

## 最佳实践
- 始终验证输入
- 正确处理错误
- 使用 TypeScript 以提高类型安全性

## 故障排除

### 常见问题
Q: 为什么我的导入失败?
A: 确保正确安装了包。

### 错误消息
"Module not found" - 检查 package.json 依赖项

## 资源
- GitHub: https://github.com/user/project
- 文档: https://docs.example.com
- 支持: support@example.com

## 标签
javascript, typescript, api, documentation, web development

自动生成

使用脚本从现有文档生成:

javascript

// scripts/generate-llms-txt.js
import fs from 'fs';
import path from 'path';
import matter from 'gray-matter';

function generateLlmsTxt(docsDir, outputPath) {
  let content = '# 文档索引\n\n';

  // 读取所有 markdown 文件
  const files = fs.readdirSync(docsDir)
    .filter(f => f.endsWith('.md'));

  files.forEach(file => {
    const filePath = path.join(docsDir, file);
    const fileContent = fs.readFileSync(filePath, 'utf-8');
    const { data, content: markdown } = matter(fileContent);

    // 提取标题和描述
    const title = data.title || file.replace('.md', '');
    const description = markdown.split('\n')[0];

    content += `## ${title}\n`;
    content += `${description}\n\n`;

    // 提取代码示例
    const codeBlocks = markdown.match(/```[\s\S]*?```/g);
    if (codeBlocks) {
      content += '### 示例\n';
      content += codeBlocks[0] + '\n\n';
    }
  });

  // 写入 llms.txt
  fs.writeFileSync(outputPath, content);
  console.log(`生成 ${outputPath}`);
}

generateLlmsTxt('./docs', './llms.txt');

运行生成器:

bash

node scripts/generate-llms-txt.js

与 Rspress 集成

在 rspress.config.ts 中配置:

typescript

import { defineConfig } from 'rspress/config';

export default defineConfig({
  // ... 其他配置
  builderConfig: {
    output: {
      copy: [
        {
          from: './llms.txt',
          to: './llms.txt'
        }
      ]
    }
  }
});

最佳实践

内容组织

分层结构: 使用清晰的标题层次结构

text

# 主标题 (H1)
## 主要部分 (H2)
### 子部分 (H3)
#### 详细主题 (H4)

简洁性: 保持描述清晰简洁

text

# 好的示例
## 身份验证
使用 JWT token 进行 API 身份验证。

# 不好的示例
## 这是如何在我们的系统中执行身份验证的
我们的身份验证系统使用 JSON Web Tokens,
通常称为 JWT,这是一种流行的标准...

代码示例: 包含实用的、可运行的示例

text

## 获取用户

// 好的 - 完整示例
import { getUser } from './api';

const user = await getUser('123');
console.log(user.name);

// 不好的 - 不完整
getUser('123')

关键词和标签

在文件末尾包含相关关键词:

text

## 标签
react, static-site-generator, documentation, mdx, typescript,
rspress, web-development, markdown, javascript, ssg

元数据

添加有用的元数据:

text

## 元数据
版本: 1.0.0
最后更新: 2024-01-26
作者: 文档团队
许可证: MIT
仓库: https://github.com/user/project

高级功能

多语言支持

为不同语言创建单独的文件:

text

llms.txt        # 英文版本
llms.zh.txt     # 中文版本
llms.ja.txt     # 日文版本
llms.es.txt     # 西班牙语版本

在每个文件中指定语言:

text

# 项目名称
语言: 中文 (zh-CN)

项目描述...

版本化

维护不同版本的 llms.txt:

text

llms.txt        # 最新版本
llms.v1.txt     # 版本 1.x
llms.v2.txt     # 版本 2.x

在内容中包含版本:

text

# Rspress v1.0

版本 1.0 功能和文档

## 新功能 (v1.0)
- MDX 支持
- 改进的路由

链接文档

链接到详细的文档页面:

text

## API 参考

### 配置
简要描述...
详细信息: https://docs.example.com/config

### 插件
插件系统概述...
详细信息: https://docs.example.com/plugins

索引策略

内容优先级

按重要性组织内容:

text

# 项目名称

## 快速开始 (优先级: 高)
立即开始的关键信息...

## 核心概念 (优先级: 高)
基本概念和术语...

## API 参考 (优先级: 中)
详细的 API 文档...

## 高级主题 (优先级: 低)
复杂用例...

搜索优化

为搜索优化内容:

text

## 安装和设置

关键词: 安装、设置、初始化、开始

### npm 安装
npm install rspress

别名: package-manager, npm, installation

### yarn 安装
yarn add rspress

别名: package-manager, yarn, installation

代码文档

完整记录代码示例:

text

## 创建配置

目的: 设置项目配置
语言: TypeScript
文件: rspress.config.ts

// rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  title: 'My Site',
  description: 'Site description',
  themeConfig: {
    navbar: [/* ... */],
    sidebar: {/* ... */}
  }
});

解释:
- title: 站点标题 (必需)
- description: SEO 元描述
- themeConfig: 主题自定义选项

自动化

GitHub Actions

使用 GitHub Actions 自动生成:

yaml

# .github/workflows/generate-llms-txt.yml
name: Generate llms.txt

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm install

      - name: Generate llms.txt
        run: node scripts/generate-llms-txt.js

      - name: Commit changes
        run: |
          git config user.name "GitHub Actions"
          git config user.email "actions@github.com"
          git add llms.txt
          git diff --quiet && git diff --staged --quiet || git commit -m "Update llms.txt"
          git push

预构建钩子

在构建前生成:

javascript

// scripts/prebuild.js
import { generateLlmsTxt } from './generate-llms-txt.js';

async function prebuild() {
  console.log('生成 llms.txt...');
  await generateLlmsTxt('./docs', './public/llms.txt');
  console.log('完成!');
}

prebuild();

在 package.json 中:

json

{
  "scripts": {
    "prebuild": "node scripts/prebuild.js",
    "build": "rspress build"
  }
}

验证和测试

验证脚本

验证 llms.txt 格式:

javascript

// scripts/validate-llms-txt.js
import fs from 'fs';

function validateLlmsTxt(filePath) {
  const content = fs.readFileSync(filePath, 'utf-8');
  const errors = [];

  // 检查是否有主标题
  if (!content.match(/^# /m)) {
    errors.push('缺少主标题 (# )');
  }

  // 检查是否有必需部分
  const requiredSections = ['快速开始', '描述', '文档'];
  requiredSections.forEach(section => {
    if (!content.includes(`## ${section}`)) {
      errors.push(`缺少必需部分: ${section}`);
    }
  });

  // 检查代码块格式
  const codeBlocks = content.match(/```/g);
  if (codeBlocks && codeBlocks.length % 2 !== 0) {
    errors.push('未闭合的代码块');
  }

  if (errors.length > 0) {
    console.error('验证错误:');
    errors.forEach(err => console.error(`- ${err}`));
    process.exit(1);
  }

  console.log('验证通过!');
}

validateLlmsTxt('./llms.txt');

质量检查

检查内容质量:

javascript

function checkQuality(content) {
  const issues = [];

  // 检查部分长度
  const sections = content.split(/^## /m);
  sections.forEach((section, i) => {
    if (i > 0 && section.length < 50) {
      issues.push(`部分 ${i} 太短 (${section.length} 字符)`);
    }
  });

  // 检查代码示例
  const codeBlocks = content.match(/```[\s\S]*?```/g) || [];
  if (codeBlocks.length < 3) {
    issues.push('代码示例太少');
  }

  return issues;
}

故障排除

常见问题

格式错误

text

问题: 标题未正确渲染
解决方案: 确保 # 后面有空格
错误: #标题
正确: # 标题

缺少部分

text

问题: AI 无法找到某些信息
解决方案: 添加所有必需部分:
- 项目描述
- 快速开始
- 主要功能
- 文档链接

代码块问题

text

问题: 代码未正确格式化
解决方案: 使用正确的代码围栏
```javascript
// 代码在这里
```（反引号）

调试提示

启用详细日志记录:

javascript

function generateWithLogging(docsDir) {
  console.log('开始生成...');
  console.log(`文档目录: ${docsDir}`);

  const files = fs.readdirSync(docsDir);
  console.log(`找到 ${files.length} 个文件`);

  files.forEach(file => {
    console.log(`处理: ${file}`);
    // 处理文件...
  });

  console.log('生成完成!');
}

实际示例

完整的 llms.txt 模板

text

# Rspress - 现代文档框架

Rspress 是一个强大的、基于 React 的静态站点生成器,
专为文档网站设计。

## 描述

Rspress 将 Vite 的速度与 React 的强大功能相结合,
提供优秀的文档体验。支持 MDX、主题定制、
国际化等功能。

## 快速开始

### 安装
npm install -g rspress

### 创建项目
rspress init my-docs
cd my-docs

### 开发
rspress dev

### 构建
rspress build

## 核心功能

- **MDX 支持**: 在 Markdown 中编写 React 组件
- **快速构建**: 使用 Vite 实现闪电般快速的构建
- **主题定制**: 完全可定制的主题系统
- **SSG/SSR**: 静态站点生成和服务器端渲染
- **国际化**: 内置多语言支持
- **自动路由**: 基于文件的自动路由
- **搜索**: 内置全文搜索
- **响应式**: 移动优先设计

## 配置

### 基本配置
// rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  title: '我的文档',
  description: '站点描述',
  themeConfig: {
    navbar: [],
    sidebar: {}
  }
});

### 主题配置
themeConfig: {
  navbar: [
    { text: '首页', link: '/' },
    { text: '指南', link: '/guide/' }
  ],
  sidebar: {
    '/guide/': [
      {
        text: '入门',
        items: [
          { text: '介绍', link: '/guide/introduction' },
          { text: '快速开始', link: '/guide/quick-start' }
        ]
      }
    ]
  }
}

## API 参考

### 配置选项
- title: 站点标题
- description: 站点描述
- themeConfig: 主题配置
- locales: 语言配置
- markdown: Markdown 配置

### 主题配置
- navbar: 导航栏配置
- sidebar: 侧边栏配置
- footer: 页脚配置
- socialLinks: 社交链接

## 使用示例

### MDX 组件
import { Button } from './components/Button';

# 我的页面

<Button onClick={() => alert('你好')}>
  点击我
</Button>

### 自定义布局
export default function Layout({ children }) {
  return (
    <div className="custom-layout">
      {children}
    </div>
  );
}

## 最佳实践

1. **组织内容**: 使用清晰的文件夹结构
2. **使用 MDX**: 利用交互组件
3. **优化构建**: 启用代码分割
4. **SEO**: 添加元数据和描述
5. **性能**: 优化图片和资产

## 故障排除

### 构建错误
Q: 为什么我的构建失败?
A: 检查配置文件语法和导入路径

### 路由问题
Q: 路由未按预期工作?
A: 验证文件结构和命名约定

### 样式问题
Q: 自定义样式未应用?
A: 确保正确导入 CSS 并使用正确的选择器

## 部署

### Vercel
vercel deploy

### Netlify
netlify deploy --prod

### GitHub Pages
npm run build
npm run deploy:github

## 资源

- 文档: https://rspress.dev
- GitHub: https://github.com/web-infra-dev/rspress
- Discord: https://discord.gg/rspress
- Twitter: @rspress_dev

## 版本

当前版本: 1.0.0
Node.js: >= 16.0.0
npm: >= 8.0.0

## 许可证

MIT License - 详见 LICENSE 文件

## 标签

rspress, documentation, static-site-generator, react, vite, mdx,
typescript, ssg, ssr, markdown, docs, website, developer-tools

下一步

最佳实践

保持 llms.txt 更新与主文档同步
包含实际的可运行代码示例
使用清晰的分层结构
为所有主要功能添加代码片段

注意事项

定期验证格式正确性
避免过长的部分
不要包含敏感信息
保持内容简洁相关

资源

llms.txt 格式 ​

什么是 llms.txt? ​

概述 ​

为什么使用 llms.txt? ​

基本结构 ​

文件格式 ​

必需部分 ​

创建 llms.txt ​

手动创建 ​

自动生成 ​

与 Rspress 集成 ​

最佳实践 ​

内容组织 ​

关键词和标签 ​

元数据 ​

高级功能 ​

多语言支持 ​

版本化 ​

链接文档 ​

索引策略 ​

内容优先级 ​

搜索优化 ​

代码文档 ​

自动化 ​

GitHub Actions ​

预构建钩子 ​

验证和测试 ​

验证脚本 ​

质量检查 ​

故障排除 ​

常见问题 ​

调试提示 ​

实际示例 ​

完整的 llms.txt 模板 ​

下一步 ​

llms.txt 格式

什么是 llms.txt?

概述

为什么使用 llms.txt?

基本结构

文件格式

必需部分

创建 llms.txt

手动创建

自动生成

与 Rspress 集成

最佳实践

内容组织

关键词和标签

元数据

高级功能

多语言支持

版本化

链接文档

索引策略

内容优先级

搜索优化

代码文档

自动化

GitHub Actions

预构建钩子

验证和测试

验证脚本

质量检查

故障排除

常见问题

调试提示

实际示例

完整的 llms.txt 模板

下一步