A modern library reading room with documentation on a laptop screen

Rspress: Docs at the Speed of Rust

The Orange Cat
The Orange Cat

If you have ever waited for a documentation site to rebuild while staring at a terminal spinner, you already understand the problem Rspress solves. Built on top of Rspack, the Rust-based bundler from ByteDance's web-infra team, rspress delivers a documentation-focused static site generator that compiles pages so fast you might think it skipped a step. It uses React for rendering and MDX for content authoring, which means you get the full power of components inside your Markdown files without sacrificing build performance.

Whether you are documenting an open-source library, building internal engineering docs, or maintaining a knowledge base that spans multiple versions and languages, Rspress gives you a serious toolkit with minimal configuration overhead.

Why Your Docs Deserve a Rust Engine

The headline feature of Rspress is raw speed. Because it sits on top of Rspack (itself built in Rust), compilation times are 5 to 10 times faster than webpack-based alternatives like Docusaurus. But it does not stop at the bundler. Rspress also supports lazy compilation in development mode, meaning pages are only compiled when you actually visit them. Warm builds benefit from persistent caching, shaving another 30 to 60 percent off rebuild times.

Beyond performance, Rspress packs a thoughtful feature set:

  • Full MDX support for embedding React components directly in Markdown
  • Built-in full-text search powered by FlexSearch, with no external service required
  • Internationalization with built-in translations for Chinese, English, Japanese, and Korean
  • Multi-version documentation through simple configuration
  • Plugin system for extending functionality
  • Theme customization with CSS variables and a BEM naming convention
  • AI-native features in v2, including llms.txt specification compliance

Getting Off the Ground

Installation is straightforward. You can scaffold a new project or add Rspress to an existing one.

npm create rspress@latest

Or set things up manually:

npm install rspress -D

yarn add rspress -D

Once installed, add these scripts to your package.json:

{
  "scripts": {
    "dev": "rspress dev",
    "build": "rspress build",
    "preview": "rspress preview"
  }
}

Create a docs directory with an index.md file and you are ready to go. Rspress requires Node.js 20.19 or higher, and also supports Deno and Bun.

Your First Documentation Page

Writing MDX Content

The real power of Rspress shows up when you start mixing Markdown with React components. Create a file at docs/guide/getting-started.mdx:

# Getting Started

Welcome to the project. Here is a live counter to prove this is not just static text.

import { useState } from 'react';

export const Counter = () => {
  const [count, setCount] = useState(0);
  return (
    <button onClick={() => setCount(count + 1)}>
      Clicked {count} times
    </button>
  );
};

<Counter />

## Installation

Run the following command to install the package:

\`\`\`bash
npm install my-awesome-lib
\`\`\`

MDX lets you define and use React components inline. This is particularly useful for interactive API playgrounds, configuration demos, or anything that benefits from live state.

Configuring the Site

Create an rspress.config.ts file at your project root:

import { defineConfig } from 'rspress/config';

export default defineConfig({
  root: 'docs',
  title: 'My Project Docs',
  description: 'Documentation for my awesome project',
  themeConfig: {
    socialLinks: [
      {
        icon: 'github',
        mode: 'link',
        content: 'https://github.com/my-org/my-project',
      },
    ],
  },
});

This minimal configuration gives you a fully functional documentation site with a sidebar, navigation, and social links. Rspress infers the sidebar structure from your file system by default, so organizing your docs directory is all the navigation setup you need for most projects.

Syntax Highlighting and Code Blocks

Rspress uses Shiki for syntax highlighting, which means you get accurate, IDE-quality coloring for dozens of languages. You can enable line numbers, code wrapping, and copy buttons per block:

```tsx title="app.tsx" {3-5}
import { createApp } from './framework';

const app = createApp({
  name: 'docs-site',
  version: '1.0.0',
});

app.start();
```

The {3-5} syntax highlights specific lines, and the title meta string adds a filename label to the block.

Leveling Up Your Docs

Multi-Version Documentation

When your library ships breaking changes across major versions, you need docs that match each release. Rspress handles this through configuration:

import { defineConfig } from 'rspress/config';

export default defineConfig({
  root: 'docs',
  multiVersion: {
    default: 'v2',
    versions: ['v1', 'v2'],
  },
});

Version-specific content lives in subdirectories, and Rspress generates a version switcher in the UI automatically. The built-in search is version-aware too, so users only see results relevant to the version they are browsing.

Built-in Search Without External Services

Unlike Docusaurus, which typically relies on Algolia DocSearch, Rspress ships with FlexSearch-powered full-text search out of the box. The search index is generated at build time and bundled with your site:

import { defineConfig } from 'rspress/config';

export default defineConfig({
  root: 'docs',
  search: {
    versioned: true,
  },
});

No API keys, no external service dependencies, no waiting for a crawler to index your content. Search just works the moment your site deploys.

Internationalization

Adding multiple languages requires minimal effort. Rspress supports i18n through directory-based locale separation:

import { defineConfig } from 'rspress/config';

export default defineConfig({
  root: 'docs',
  locales: [
    {
      lang: 'en',
      label: 'English',
    },
    {
      lang: 'zh',
      label: 'Chinese',
    },
  ],
});

Place your translated content under docs/en/ and docs/zh/ directories, and Rspress handles the language switcher and routing. Built-in UI strings are already translated for Chinese, English, Japanese, and Korean, and unused language strings are tree-shaken from the final bundle.

AI-Native Documentation with llms.txt

Version 2 introduced a feature that sets Rspress apart from every other documentation generator: SSG-MD rendering and llms.txt compliance. This generates Markdown versions of your pages alongside the HTML output, plus an index file that follows the llms.txt specification. AI assistants and language models can consume your documentation directly without scraping or parsing HTML.

import { defineConfig } from 'rspress/config';

export default defineConfig({
  root: 'docs',
  ssg: {
    markdown: true,
  },
});

This is a forward-looking feature that acknowledges how developers increasingly discover and consume documentation through AI tools.

Where Rspress Fits

Rspress occupies a specific niche in the documentation tooling landscape. If you are a React developer who wants MDX support, built-in search, and the fastest possible build times, it is hard to beat. VitePress is faster than most but is Vue-only. Docusaurus is feature-rich but slower and heavier. Nextra is React-based but tied to Next.js.

The trade-offs are real: Rspress has a smaller community, fewer third-party plugins, and less production mileage than the established players. But the Rstack ecosystem is growing fast, backed by ByteDance's engineering resources and an active open-source community.

Wrapping Up

rspress delivers a documentation experience that feels like it was designed by people who got tired of waiting for their docs to build. Rust-powered compilation, React rendering, MDX authoring, built-in search, i18n, multi-version support, and now AI-native features in v2 make it one of the most complete and performant documentation generators available. If your current docs pipeline has you watching progress bars, Rspress might just make that a thing of the past.