#llms.txt (SSG-MD) experimental

Want to get started quickly? Jump to Quick Start.

#What is SSG-MD?

Rspress provides the experimental Static Site Generation to Markdown (SSG-MD) feature. Similar to Static Site Generation (SSG), SSG-MD renders pages as Markdown files instead of HTML files and generates llms.txt and llms-full.txt, making technical documentation easier for large language models to understand and use.

The following table compares SSG and SSG-MD:

#What is llms.txt?

llms.txt is an emerging standard file format placed in a website's root directory to help large language models better understand and use website content.

Because LLMs have limited context windows, they usually cannot process an entire website's HTML content. Converting complex HTML with navigation, ads, and JavaScript to plain text is also difficult and imprecise. llms.txt solves this by providing a structured Markdown index that includes page URLs and content descriptions, helping AI tools quickly locate and understand key information.

In simple terms:

• sitemap.xml → "Site map" for search engines
• llms.txt → "Documentation index" for AI

Output structure example:

llms.txt content example:

# 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

#Why SSG-MD?

In React-based frontend frameworks, extracting static information from dynamically rendered content is often difficult. MDX has the same challenge: .mdx files contain Markdown content but can also embed React components, making docs more interactive. Rspress lets users enhance docs with MDX fragments, React components, Hooks, and TSX routes, but this dynamic content creates problems when converted to Markdown:

• Feeding raw MDX to AI introduces code syntax noise and loses rendered React component content.

• Converting HTML to Markdown often produces poor results, making information quality hard to guarantee.

Static Site Generation (SSG) generates static HTML for crawlers and improves SEO. SSG-MD addresses a similar problem for AI tools: it improves GEO and the quality of static information for large language models. Compared with HTML-to-Markdown conversion, rendering from React's virtual DOM gives SSG-MD a richer information source.

#How does SSG-MD work?

1. Rspress internally implements a renderToMarkdownString method similar to renderToString in react-dom, which renders React components to Markdown strings:

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

// HTML elements are converted to the corresponding Markdown syntax
renderToMarkdownString(
  <div>
    <strong>foo</strong>
    <span>bar</span>
  </div>,
);
// Output: '**foo**bar'

// React components and Hooks are supported
const Article = () => {
  return (
    <>
      <h1>Hello World</h1>
      <p>This is a paragraph.</p>
    </>
  );
};
renderToMarkdownString(<Article />);
// Output: '# Hello World\n\nThis is a paragraph.\n'

In principle, this API works for any site built with React; see react-render-to-markdown if you're interested.

2. Rspress uses a custom remark plugin remarkSplitMdx to preprocess MDX files before rendering. This plugin splits the MDX AST, separating pure Markdown content from JSX components: Markdown text is serialized as string literals, while JSX components and MDX expressions (e.g., {variable}) are preserved as React elements. This ensures that Markdown content passes through as-is without being processed by React rendering, while dynamic components are rendered by renderToMarkdownString.

For example, the following MDX:

# Hello

Some **bold** text.

<PackageManagerTabs command="install rspress" />

{window.title}

It is transformed into a component like this:

function _createMdxContent() {
  return (
    <>
      {'# Hello\n\nSome **bold** text.\n'}
      <PackageManagerTabs command="install rspress" />
      {window.title}
    </>
  );
}

3. Rspress provides the import.meta.env.SSG_MD environment variable so React components can distinguish SSG-MD rendering from browser rendering and customize their output:

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

4. Rspress's internal component library is adapted for SSG-MD, so components render meaningful Markdown during the SSG-MD phase. For example:

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

It is rendered as:

```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
```

#Quick start

Enable llms in rspress.config.ts:

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

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

After running rspress build, the output directory (default doc_build) will additionally contain the following files:

Access pages by replacing the .html suffix with .md, e.g., /guide/start/introduction.md. Multilingual sites will output {lang}/llms.txt and {lang}/llms-full.txt for non-default languages.

{
  "dependencies": {
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "react-render-to-markdown": "^18.3.1"
  }
}

#Configuration

#UI display

When llms: true is enabled, LlmsCopyButton and LlmsViewOptions components are automatically displayed below all H1 headers, allowing users to copy Markdown content or open it in AI tools like ChatGPT or Claude. You can also display them in the outline panel instead by setting placement: 'outline'.

Customize or disable via themeConfig.llmsUI:

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

export default defineConfig({
  llms: true,
  themeConfig: {
    // Disable LLMS UI
    llmsUI: false,
    // Or customize options:
    // llmsUI: {
    //   viewOptions: ['markdownLink', 'chatgpt', 'claude'],
    //   placement: 'outline', // Display in outline panel instead of below H1
    // },
  },
});

For more information, see themeConfig.llmsUI.

#Custom MDX splitting

When documents contain custom components, use remarkSplitMdxOptions to control which components to keep or convert to plain text when converting to Markdown:

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

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

• excludes: Matched components are converted to plain text and have the highest priority.
• includes: If set, only matched components are retained; all others are converted to plain text.
• When both are configured, excludes is applied first, then the result is filtered by includes.