#llms.txt （SSG-MD） experimental

想快速上手？跳转到快速开始。

#什么是 SSG-MD？

Rspress 提供实验性的 Static Site Generation to Markdown (SSG-MD) 能力，这是一个全新的功能。与它的名字一样 SSG-MD，与 静态站点生成（SSG） 过程类似，但不同之处在于它将你的页面渲染为 Markdown 文件，而非 HTML 文件，并生成 llms.txt 及 llms-full.txt 相关文件，便于大模型理解和使用你的技术文档。

为了便于理解 SSG-MD 概念，下面是一个 SSG 与 SSG-MD 的类比表：

#什么是 llms.txt？

llms.txt 是一种新兴的标准化文件格式，放置于网站根目录，帮助大语言模型更好地理解和使用网站内容。

由于 LLM 的上下文窗口有限，无法处理整个网站的 HTML 内容，而将复杂的 HTML（包含导航、广告、JavaScript）转换为纯文本既困难又不精确。llms.txt 使用 Markdown 格式提供网站的结构化索引，包含页面 URL 及其内容描述，让 AI 能够快速定位和理解关键信息。

简单来说：

• sitemap.xml → 给搜索引擎看的"网站地图"
• llms.txt → 给 AI 看的"文档目录"

产物结构示例：

llms.txt 内容示例：

# Rspress

> Rspress is a static site generator based on Rspack.

## Docs

- [Introduction](/guide/start/introduction.md): Introduction to Rspress
- [Quick Start](/guide/start/quick-start.md): Quick Start

#为什么需要 SSG-MD？

在基于 React 动态渲染的前端框架中，往往存在静态信息难以提取的问题。这在 MDX 中同样存在，.mdx 文件既包含 Markdown 内容，也支持嵌入 React 组件，增强文档的交互能力。对于 Rspress 而言，Rspress 允许用户通过 MDX 片段、React 组件、Hooks 以及 TSX 路由等动态特性来增强文档表现力。但这些动态内容在转换为 Markdown 文本时会面临以下问题：

• 直接将 MDX 输入给 AI 会包含大量代码语法噪音，并丢失 React 组件内容

• 将 HTML 转为 Markdown 往往效果不佳，信息质量难以保证

静态站点生成（SSG） 可以生成静态的 HTML 文件供爬虫爬取，提升 SEO。SSG-MD 也是为了解决类似的问题，提升 GEO 和面向大模型的静态信息质量。相比将 HTML 转化为 Markdown，React 在渲染期间的虚拟 DOM 拥有更好的信息源。

#怎么实现 SSG-MD？

1. Rspress 内部实现了类似 react-dom 中 renderToString 的 renderToMarkdownString 方法，将 React 组件渲染为 Markdown 字符串：

import { renderToMarkdownString } from 'react-render-to-markdown';

// HTML 元素会被转换为对应的 Markdown 语法
renderToMarkdownString(
  <div>
    <strong>foo</strong>
    <span>bar</span>
  </div>,
);
// 输出: '**foo**bar'

// 支持 React 组件和 Hooks
const Article = () => {
  return (
    <>
      <h1>Hello World</h1>
      <p>This is a paragraph.</p>
    </>
  );
};
renderToMarkdownString(<Article />);
// 输出: '# Hello World\n\nThis is a paragraph.\n'

理论上这一 API 适用于任何使用 React 构建的网站，如果你对它感兴趣，请参考 react-render-to-markdown。

2. 提供 import.meta.env.SSG_MD 环境变量，方便用户在 React 组件中区分 SSG-MD 渲染和浏览器渲染，从而实现更灵活的内容定制：

export function Tab({ label }: { label: string }) {
  if (import.meta.env.SSG_MD) {
    return <>{`** Here is a Tab named ${label}**`}</>;
  }
  return <div>{label}</div>;
}

3. Rspress 内部组件对于 SSG-MD 做了适配，确保在 SSG-MD 阶段渲染出合理的 Markdown 内容。例如：

<PackageManagerTabs command="create rspress@latest" />

将被渲染为：

```sh [npm]
npm create rspress@latest
```

```sh [yarn]
yarn create rspress
```

```sh [pnpm]
pnpm create rspress@latest
```

```sh [bun]
bun create rspress@latest
```

```sh [deno]
deno init --npm rspress@latest
```

#快速开始

在 rspress.config.ts 中开启 llms 即可：

import { defineConfig } from '@rspress/core';

export default defineConfig({
  llms: true,
});

执行 rspress build 后，输出目录（默认 doc_build）会额外生成以下文件：

访问时将 .html 后缀替换为 .md 即可，如 /guide/start/introduction.md。多语言站点会为非默认语言输出 {lang}/llms.txt 与 {lang}/llms-full.txt。

#配置选项

#UI 展示

当启用 llms: true 时，会自动在所有 H1 标题下方显示 LlmsCopyButton 和 LlmsViewOptions 组件，方便用户复制 Markdown 内容或在 ChatGPT、Claude 等 AI 工具中打开。

可通过 themeConfig.llmsUI 自定义或禁用：

import { defineConfig } from '@rspress/core';

export default defineConfig({
  llms: true,
  themeConfig: {
    // 禁用 LLMS UI
    llmsUI: false,
    // 或自定义选项：
    // llmsUI: {
    //   viewOptions: ['markdownLink', 'chatgpt', 'claude'],
    // },
  },
});

更多信息请参阅 themeConfig.llmsUI。

#自定义 MDX 拆分

当文档中包含自定义组件时，可通过 remarkSplitMdxOptions 控制哪些组件在转换为 Markdown 时保留或转成纯文本：

import { defineConfig } from '@rspress/core';

export default defineConfig({
  llms: {
    remarkSplitMdxOptions: {
      excludes: [[['Demo'], '@project/components']],
    },
  },
});

• excludes：匹配的组件会被转成纯文本，优先级最高。
• includes：若设置，仅允许匹配的组件保留，其余会转成纯文本。
• 同时配置时会先应用 excludes，再按 includes 进行过滤。