docs: upgrade llms.txt and ssg-md (#2927)

SoonIter · web-flow · commit c03d863a6b0e · 2025-12-25T11:54:08.000+08:00
diff --git a/packages/core/src/theme/layout/Layout/index.tsx b/packages/core/src/theme/layout/Layout/index.tsx
@@ -3,7 +3,7 @@ import {
   Content,
   useFrontmatter,
   useLocaleSiteData,
-  usePageData,
+  usePage,
   useSite,
 } from '@rspress/core/runtime';
 import type { HomeLayoutProps } from '@theme';
@@ -139,7 +139,7 @@ export function Layout(props: LayoutProps) {
     beforeFeatures,
     afterFeatures,
   };
-  const { page } = usePageData();
+  const { page } = usePage();
   const { site } = useSite();
   const { frontmatter } = useFrontmatter();
   const {
diff --git a/website/docs/en/guide/basic/ssg-md.mdx b/website/docs/en/guide/basic/ssg-md.mdx
@@ -4,4 +4,166 @@ tag: experimental
 
 # llms.txt (SSG-MD)
 
-{/* TODO */}
+Rspress provides experimental SSG-MD capability, which is a brand new feature. As its name suggests SSG-MD, the only difference from [Static Site Generation (SSG)](./ssg) is that it renders your pages as Markdown files instead of HTML files, and generates [`llms.txt`](https://llmstxt.org/) and llms-full.txt related files, making it easier for large language models to understand and use your technical documentation.
+
+## Why SSG-MD?
+
+In frontend frameworks based on React dynamic rendering, there is often a problem of difficulty in extracting static information. This also exists in MDX, where `.mdx` files contain both Markdown content and support embedding React components, enhancing the interactivity of documents. For Rspress, Rspress allows users to use [MDX fragments](../use-mdx/components.mdx), custom components, React Hooks, tsx files as routes, etc. to enhance the expressiveness of document content. However, these dynamic contents are difficult to convert to Markdown format, and even if the html generated during the SSG phase is converted to markdown, the results are often unsatisfactory.
+
+[Static Site Generation (SSG)](./ssg) can generate static HTML files for crawlers to crawl, improving [SEO](https://en.wikipedia.org/wiki/Search_engine_optimization). SSG-MD also solves similar problems, improving [GEO](https://en.wikipedia.org/wiki/Generative_engine_optimization) and the quality of static information for large language models. Compared to converting html to markdown, React's virtual DOM during rendering has a better source of information.
+
+## How to implement SSG-MD?
+
+1. Rspress internally implements a `renderToMarkdownString` method similar to `renderToString` in `react-dom`.
+
+```tsx
+import { expect, describe, it } from '@rstest/core';
+import { renderToMarkdownString } from './react-render-to-markdown';
+import { useState } from 'react';
+
+describe('renderToMarkdownString', () => {
+  it('renders text', () => {
+    expect(
+      renderToMarkdownString(
+        <div>
+          <strong>foo</strong>
+          <span>bar</span>
+        </div>,
+      ),
+    ).toBe('**foo**bar');
+  });
+  it('renders header and paragraph', () => {
+    const Comp1 = () => {
+      const [count, setCount] = useState(1);
+      return <h1>Header {count}</h1>;
+    };
+    const Comp2 = () => {
+      return (
+        <>
+          <Comp1 />
+          <p>Paragraph</p>
+        </>
+      );
+    };
+    expect(renderToMarkdownString(<Comp2 />)).toBe('# Header 1\n\nParagraph\n');
+  });
+});
+```
+
+2. Provides `process.env.__SSR_MD__` environment variable, making it easy for users to distinguish between SSG-MD rendering and browser rendering in MDX components, thus achieving more flexible content customization. For example:
+
+```tsx
+export function Tab({ label }: { label: string }) {
+  if (process.env.__SSR_MD__) {
+    return <>{`** Here is a Tab named ${label}**`}</>;
+  }
+  return <div>{label}</div>;
+}
+```
+
+3. Rspress internal component library has been adapted for SSG-MD to ensure reasonable Markdown content is rendered during the SSG-MD phase. For example:
+
+```tsx
+<PackageManagerTabs command="create rspress@latest" />
+```
+
+Will be rendered as:
+
+````md
+```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
+```
+````
+
+We believe that with the introduction of this feature, all websites built with React in the future can use SSG-MD to achieve better GEO.
+
+## Features
+
+- Renders each site page as a `.md` file, convenient for vectorization or providing to large language models. `/guide/start/introduction.html` can be accessed by replacing the `.html` suffix with `.md`.
+- Generates [`llms.txt`](https://llmstxt.org/), displaying the title and description of each page in navigation and sidebar order.
+- Generates `llms-full.txt`, containing the Markdown content of each page, convenient for batch import.
+- Supports multilingual sites, outputting corresponding `{lang}/llms.txt` and `{lang}/llms-full.txt` for non-default languages.
+
+## Output example
+
+```txt
+doc_build
+├── llms.txt
+├── llms-full.txt
+├── guide
+│   └── start
+│       └── introduction.md
+└── ...
+```
+
+The actual files are placed in the build directory (such as `guide/start/introduction.md`), and the `url` in `llms-full.txt` will carry the site prefix, such as `/guide/start/introduction.md`.
+
+`llms-full.txt` example snippet:
+
+```md
+---
+url: /guide/start/introduction.md
+---
+
+# Introduction
+
+...
+```
+
+## How to enable
+
+Enable `llms` in `rspress.config.ts` to generate the above files during the build phase:
+
+```ts title="rspress.config.ts"
+import { defineConfig } from '@rspress/core';
+
+export default defineConfig({
+  llms: true,
+});
+```
+
+After executing `rspress build`, you can see `llms.txt`, `llms-full.txt` and the `.md` files corresponding to each route in the output directory (default `doc_build`).
+
+:::warning
+
+`llms` is an experimental capability, mainly used to generate Markdown data that is easy for large language models or retrieval systems to use. It will be continuously optimized in future versions and may have stability or compatibility issues.
+
+If your project does not support SSG, such as using `ssg: false`, please use [@rspress/plugin-llms](/plugin/official-plugins/llms).
+
+:::
+
+## Custom MDX splitting (Optional)
+
+When documents contain custom components, you can control which components to keep or convert to plain text when converting to Markdown through `remarkSplitMdxOptions`:
+
+```ts title="rspress.config.ts"
+import { defineConfig } from '@rspress/core';
+
+export default defineConfig({
+  llms: {
+    remarkSplitMdxOptions: {
+      excludes: [[['Demo'], '@project/components']],
+    },
+  },
+});
+```
+
+- `excludes`: Matched components will be converted to plain text, with the highest priority.
+- `includes`: If set, only matched components are allowed to be retained, and the rest will be converted to plain text.
+- When configured simultaneously, `excludes` will be applied first, then filtered by `includes`.
diff --git a/website/docs/en/plugin/official-plugins/llms.mdx b/website/docs/en/plugin/official-plugins/llms.mdx
@@ -8,6 +8,12 @@ import { SourceCode } from '@rspress/core/theme';
 
 Generate [llms.txt](https://llmstxt.org/) related files for your Rspress site, allowing large language models to better understand your documentation site.
 
+:::warning
+
+`@rspress/plugin-llms` is only intended as an alternative solution for scenarios where `ssg: false` is used. It is recommended to prioritize using the [SSG-MD](/guide/basic/ssg-md) feature.
+
+:::
+
 ## Installation
 
 import { PackageManagerTabs } from '@theme';
diff --git a/website/docs/zh/guide/basic/ssg-md.mdx b/website/docs/zh/guide/basic/ssg-md.mdx
@@ -4,12 +4,99 @@ tag: experimental
 
 # llms.txt （SSG-MD）
 
-Rspress 提供实验性的 SSG-MD 能力，在 [静态站点生成（SSG）](./ssg) 时额外输出便于大模型理解的 Markdown 资源。
+Rspress 提供实验性的 SSG-MD 能力，这是一个全新的功能。与它的名字一样 SSG-MD，与 [静态站点生成（SSG）](./ssg) 唯一的不同在于它将你的页面渲染为 Markdown 文件，而非 HTML 文件，并生成 [`llms.txt`](https://llmstxt.org/) 及 llms-full.txt 相关文件，便于大模型理解和使用你的技术文档。
+
+## 为什么需要 SSG-MD？
+
+在基于 React 动态渲染的前端框架中， 往往存在静态信息难以提取的问题。这在 MDX 中同样存在，`.mdx` 文件既包含 Markdown 内容，也支持嵌入 React 组件，增强文档的交互能力。对于 Rspress 而言，Rspress 允许用户使用 [MDX 片段](../use-mdx/components.mdx)、自定义组件、React Hooks、用 tsx 文件作为路由等等来增强文档内容的表现力。然而，这些动态内容很难被转化为 Markdown 格式，即使使用 SSG 阶段产生后的 html 转为 markdown，结果也往往不尽如人意。
+
+[静态站点生成（SSG）](./ssg) 可以生成静态的 HTML 文件提供给爬虫爬取，提高 [SEO](https://en.wikipedia.org/wiki/Search_engine_optimization)，SSG-MD 也为了解决类似的问题，提升 [GEO](https://en.wikipedia.org/wiki/Generative_engine_optimization) 和给大模型的静态信息质量，相比与将 html 转化为 markdown，React 在渲染期间的虚拟 DOM 拥有更好的信息源。
+
+## 怎么实现 SSG-MD？
+
+1. Rspress 内部实现了类似 `react-dom` 中 `renderToString` 相同的 `renderToMarkdownString` 方法。
+
+```tsx
+import { expect, describe, it } from '@rstest/core';
+import { renderToMarkdownString } from './react-render-to-markdown';
+import { useState } from 'react';
+
+describe('renderToMarkdownString', () => {
+  it('renders text', () => {
+    expect(
+      renderToMarkdownString(
+        <div>
+          <strong>foo</strong>
+          <span>bar</span>
+        </div>,
+      ),
+    ).toBe('**foo**bar');
+  });
+  it('renders header and paragraph', () => {
+    const Comp1 = () => {
+      const [count, setCount] = useState(1);
+      return <h1>Header {count}</h1>;
+    };
+    const Comp2 = () => {
+      return (
+        <>
+          <Comp1 />
+          <p>Paragraph</p>
+        </>
+      );
+    };
+    expect(renderToMarkdownString(<Comp2 />)).toBe('# Header 1\n\nParagraph\n');
+  });
+});
+```
+
+2. 提供 `process.env.__SSR_MD__` 环境变量，方便用户在 React 组件中区分 SSG-MD 渲染和浏览器渲染，从而实现更灵活的内容定制。例如：
+
+```tsx
+export function Tab({ label }: { label: string }) {
+  if (process.env.__SSR_MD__) {
+    return <>{`** Here is a Tab named ${label}**`}</>;
+  }
+  return <div>{label}</div>;
+}
+```
+
+3. Rspress 内部组件对于 SSG-MD 做了适配，确保在 SSG-MD 阶段渲染出合理的 Markdown 内容。例如：
+
+```tsx
+<PackageManagerTabs command="create rspress@latest" />
+```
+
+将被渲染为：
+
+````md
+```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
+```
+````
+
+相信随着这一功能的推出，未来所有使用 React 构建的网站都可以运用 SSG-MD 获得更好的 GEO。
 
 ## 功能介绍
 
-- 将站点页面渲染为 `.md` 文件，便于向量化或提供给大模型。
-- 生成 `llms.txt`，按导航、侧边栏顺序罗列各页面标题与描述。
+- 将每个站点页面渲染为 `.md` 文件，便于向量化或提供给大模型，`/guide/start/introduction.html` 将 `.html` 后缀替换为 `.md` 即可访问。
+- 生成 [`llms.txt`](https://llmstxt.org/)，按导航、侧边栏顺序展示各页面标题与描述。
 - 生成 `llms-full.txt`，包含每个页面的 Markdown 内容，方便批量导入。
 - 支持多语言站点，会为非默认语言输出对应的 `{lang}/llms.txt` 与 `{lang}/llms-full.txt`。
 
@@ -53,6 +140,14 @@ export default defineConfig({
 
 执行 `rspress build` 后，可在输出目录（默认 `doc_build`）中看到 `llms.txt`、`llms-full.txt` 以及各路由对应的 `.md` 文件。
 
+:::warning
+
+`llms` 为实验能力，主要用于生成便于大模型或检索系统使用的 Markdown 数据。会在未来版本中持续优化，可能存在不稳定或兼容性问题。
+
+如果你的项目不支持 SSG，例如使用 `ssg: false`，请使用 [@rspress/plugin-llms](/plugin/official-plugins/llms)。
+
+:::
+
 ## 自定义 MDX 拆分（可选）
 
 当文档中包含自定义组件时，可以通过 `remarkSplitMdxOptions` 控制哪些组件在转换为 Markdown 时保留或转成纯文本：
@@ -72,7 +167,3 @@ export default defineConfig({
 - `excludes`：匹配的组件会被转成纯文本，优先级最高。
 - `includes`：若设置，仅允许匹配的组件保留，其余会转成纯文本。
 - 同时配置时会先应用 `excludes`，再按 `includes` 进行过滤。
-
-:::warning
-`llms` 为实验能力，主要用于生成便于大模型或检索系统使用的 Markdown 数据。
-:::
diff --git a/website/docs/zh/plugin/official-plugins/llms.mdx b/website/docs/zh/plugin/official-plugins/llms.mdx
@@ -8,6 +8,12 @@ import { SourceCode } from '@rspress/core/theme';
 
 为 Rspress 站点生成 [llms.txt](https://llmstxt.org/) 相关文件，使大模型可以更好地理解你的文档站。
 
+:::warning
+
+`@rspress/plugin-llms` 仅作为 `ssg: false` 场景下的替代方案使用，建议优先使用 [SSG-MD](/guide/basic/ssg-md) 功能。
+
+:::
+
 ## 安装
 
 import { PackageManagerTabs } from '@theme';
