#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 看的"文档目录"

产物结构示例：

doc_build
├── llms.txt
├── llms-full.txt
├── guide
│   └── start
│       └── introduction.md
└── ...

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 格式，即使使用 SSG 阶段产生后的 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
```

#功能介绍

• 将每个站点页面渲染为 .md 文件，便于向量化或提供给大模型，/guide/start/introduction.html 将 .html 后缀替换为 .md 即可访问。
• 生成 llms.txt，按导航、侧边栏顺序展示各页面标题与描述。
• 生成 llms-full.txt，包含每个页面的 Markdown 内容，方便批量导入。
• 支持多语言站点，会为非默认语言输出对应的 {lang}/llms.txt 与 {lang}/llms-full.txt。

#产物示例

doc_build
├── llms.txt
├── llms-full.txt
├── guide
│   └── start
│       └── introduction.md
└── ...

实际文件落在构建目录（如 guide/start/introduction.md），llms-full.txt 中的 url 会携带站点前缀，例如 /guide/start/introduction.md。

llms-full.txt 示例片段：

---
url: /guide/start/introduction.md
---

# 介绍

...

#启用方式

在 rspress.config.ts 中开启 llms 即可在构建阶段产出上述文件：

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

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

执行 rspress build 后，可在输出目录（默认 doc_build）中看到 llms.txt、llms-full.txt 以及各路由对应的 .md 文件。

#自定义 MDX 拆分（可选）

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

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

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

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