介绍

Rspress 是一个基于 Rsbuild 的静态站点生成器，使用 React 进行渲染，内置了一套默认的文档主题。你可以通过 Rspress 快速搭建文档站点，也可以自定义主题来满足个性化的静态站需求，如博客站、产品主页等。此外，你还可以接入官方提供的插件来便捷地搭建组件库文档。

为什么选择 Rspress

Rspress 主要围绕以下几个核心特性进行设计：

构建性能。保证足够快的启动速度，带来良好的开发体验。
AI 友好。技术文档不仅服务于人类读者，也可以通过 SSG-MD 被 AI 更好地理解和使用。
MDX 支持。通过 MDX，我们可以方便地复用文档片段，以及在文档中渲染自定义的 React 组件。
文档站基础能力。包括国际化、多版本支持、全文搜索、组件库文档等。
可扩展性。内置插件系统，支持通过插件 API 来扩展功能。

这些也代表了静态站点开发的一些核心需求。接下来将会根据这几个方面分别进行介绍。

构建性能

随着项目规模不断扩大，团队成员常常受困于冗长的项目启动时间，开发体验因此受到影响，而且项目开发时间越长，这种体验的劣化就越明显。

我们不禁开始思考，是否能跳出目前社区工具链的限制，突破现有 SSG 框架的性能瓶颈，实现绝大多数场景的项目秒启效果？

接着，我们在这个方向上持续地探索，最终在 Rspress 上实现了这样的效果。

在 Rspress V2 中，我们通过多种优化手段实现了显著的性能提升：

LazyCompilation。lazyCompilation 会在 dev 模式下按需编译。只有当你访问某个页面时，该页面才会被编译，大幅提升了开发启动速度，甚至实现毫秒级的冷启动。
持久化缓存。对于 build 生产构建中，默认开启了持久化缓存，在热启动中复用上次编译的结果，提升 30%-60% 的构建速度。
Rspack Bundler。Rspress 使用了团队内部自研的 Rspack，Rspack 是一个基于 Rust 的 Bundler，内置多种性能优化手段，比如多线程并行编译、增量编译等等，相比社区传统的打包工具，有 5 ～ 10 倍的性能提升。

与此同时，Rspress 内部也应用了其它诸多构建优化手段。这些优化手段，配合强大的 Rust 工具链，将 SSG 框架的编译性能推向了一个崭新的高度。

AI 友好

随着大语言模型的普及，技术文档不仅服务于人类读者，也需要被 AI 更好地理解和使用。

Rspress V2 引入了 SSG-MD 能力，它将页面渲染为 Markdown 文件而非 HTML 文件，并生成符合 llms.txt 规范的索引文件。

rspress.config.ts

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

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

启用后，构建产物中会包含 llms.txt（按导航和侧边栏顺序展示各页面标题与描述的索引文件）、llms-full.txt（包含所有页面 Markdown 内容的完整文件）以及各路由对应的 .md 文件。

正如 SSG 可以生成静态 HTML 文件提高 SEO，SSG-MD 也可以相对提升 GEO（Generative Engine Optimization）和给大模型的静态信息质量。

详细用法请参考 SSG-MD 文档。

MDX 支持

为了保证内容开发的灵活性，Rspress 选择支持 MDX 这种内容格式。

因为 MDX 的背后实际代表了一种组件化的内容组织方式，一方面文档即组件，那么我们可以在不同文档间复用文档片段，另一方面在文档中可以引入任何自定义 React 组件，大大释放了文档开发的想象力。

文档站基础能力

当然，Rspress 在文档站基础能力的打磨上也做了相当多的工作，支持了如下的功能特性：

自动生成布局，包括导航栏、左侧侧边栏等等；
静态站点生成，项目构建后直出 HTML；
国际化，支持多语言文档；
全文搜索，提供开箱即用的搜索功能；
多版本文档管理；
自定义文档主题；
自动生成组件 Demo 预览及 Playground；

在后文，我们将会对这些功能特性进行详细的介绍。

扩展机制

Rspress 内部设计了多种扩展机制，保证足够强的定制能力，包括：

支持自定义全局组件、全局样式、页面布局结构，详情请参考自定义页面。
支持构建能力扩展，包括 Rspack 配置、增加 MDX 编译插件等等，详情请参考构建能力扩展。
支持自定义主题，详情请参考自定义主题。
内置插件机制，支持自定义插件，详情请参考插件机制。

功能特性

接下来我们来介绍 Rspress 的主要功能特性。

一整套全新主题

Rspress V2 带来了全新设计的主题，在视觉效果和阅读体验上都有显著提升，同时提供了极高的可定制性。

BEM 命名规范

所有内置组件现已采用 BEM 命名规范。这一改变使开发者能够通过标准 CSS 选择器灵活调整样式，避免与 Tailwind CSS 等工具产生冲突，大大降低了样式定制的门槛。

/* 轻松覆盖组件样式 */
.rp-nav__title {
  height: 32px;
}
.rp-nav-menu__item--active {
  color: purple;
}

丰富的 CSS 变量

全新主题暴露了更多的 CSS 变量，覆盖主题色、代码块、首页等组件的样式。你可以在 CSS 变量页面交互式地预览和调整这些变量。

`rspress eject` 命令

当 CSS 变量无法满足定制需求时，你可以使用全新的 rspress eject 命令将内置组件的源代码复制到项目的主题目录中，实现完全自定义。

# 将 Nav 组件导出到 theme 目录
npx rspress eject Nav

自动生成布局

对于一个文档站的搭建而言，除了显示正文内容之外，我们一般还需要以下的几个布局模块：

导航栏，用于提供全局性的导航入口；
侧边栏，用于展示当前导航下的文章目录；
文章大纲栏，用于展示当前页面的大纲结构。

对于文档大纲，Rspress 会自动提取文档中的各级标题，生成大纲信息，并默认展示在文章页右侧，你无需其它操作。

而对于导航栏和侧边栏，我们提供了两种配置方式，你可以选择其中一种进行配置：

声明式配置。通过在目录中声明 _meta.json 来配置对应的数据，比如：

_meta.json

["introduction", "install", "start"]

配置详情你可以阅读「自动化导航栏/侧边栏」文档。

编程式配置。通过在 Rspress 配置中指定 nav 和 sidebar 配置项来实现。

我们推荐在一般情况下使用声明式配置，这样有诸多的好处：

配置文件更加简洁和清晰。
文件目录结构和侧边栏目录结构的对应关系更加直观。
增加或者删减侧边栏目录时，直接在当前目录中操作，而不用前往 rspress.config.ts 配置文件中定位到相应的位置然后添加/删减配置，从而减少了开发上下文切换的成本。

而编程式配置则在某些需要动态生成配置的场景中非常有用，比如 Rspress 官方的 TypeDoc 插件会根据 TypeDoc 提供的一份 json 数据自动转换为 nav 和 sidebar 的配置。

MDX 支持

MDX 是一种功能强大的内容开发方式。你不仅仅可以像往常一样编写 Markdown 文件，而且可以在 Markdown 的内容中使用 React 组件：

除此之外，Rspress 还支持了一些特定的语法，如：

自定义容器语法。
FrontMatter 元数据定义。
代码行高亮语法。

详情可以查看「使用 MDX」文档。

集成 Shiki 用于代码块高亮

Rspress V2 默认使用 Shiki 进行代码高亮。相比运行时高亮方案，Shiki 在编译时完成高亮处理，基于 TextMate 语法实现与 VS Code 一致的准确语法高亮，不增加运行时开销和包体积。

可以通过 CSS 变量自定义代码块的配色方案，在 CSS 变量页面可以交互式地切换和预览不同的 Shiki 主题。同时 Shiki 也允许使用自定义的 transformer 进行扩展来丰富写作，如 twoslash。

SSG

Rspress 是一个标准的 SSG 框架，在生产环境的构建中，它会自动帮你生成静态站点，即生成各个页面的 HTML 内容，在构建完成之后，HTML 会出现在默认的产物目录中。

随后，你可以将这个产物目录的内容部署到任何静态站点托管服务上，比如 GitHub Pages、Netlify、Vercel 等等。

同时，我们也提供了配置让你能够很方便地自定义 SSG 生成的 HTML 内容，详情可以参考「静态站点生成」文档。

国际化（i18n）

国际化是文档站点的常见需求，Rspress 将国际化能力封装得简单易用，我们将其抽象为如下需求：

如何定义 I18n 数据源？
如何进行不同语言下的站点配置？
如何组织不同语言版本的文档目录？
如何自定义组件中使用 I18n 数据源？

Rspress V2 主题内置了中文、英文、日文、韩文等多种语言的翻译文本，未来会支持更多语言，系统会自动根据语言配置和使用进行 "Tree Shaking"，仅打包你需要的文本。你也可以通过 i18nSource 配置项轻松扩展或覆盖翻译内容。

你可以根据 I18n 教程来一步步为你的站点实现国际化。

多版本文档

在某些场景中，我们需要进行多版本文档管理，而 Rspress 已经内置了多版本文档的支持，一方面你可以通过简单的配置来开启这个能力，另一方面你只需要按照往常的写法来组织目录即可，不引入非必要的目录和概念，将心智负担降到最低：

// 配置文件
import { defineConfig } from '@rspress/core';

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

// 目录结构

docs

README.md

guide

README.md

guide

README.md

全文搜索

Rspress 中提供开箱即用的全文搜索能力，你无需任何配置即可接入，底层基于开源的 FlexSearch 引擎实现，效果如下：

自定义主题

Rspress 支持两种自定义主题的方式：

基于默认主题扩展。在默认主题的各个组件中，提供了许多插槽让你能添加自定义的布局内容，比如

// theme/index.tsx
import Theme from '@rspress/core/theme';
import { NoSSR } from '@rspress/core/runtime';

const Layout = () => <Theme.Layout beforeNavTitle={<p>Custom Block</p>} />;

export default {
  ...Theme,
  Layout,
};

export * from '@rspress/core/theme-original';

完全自定义主题。如果你想从头开发一套自定义主题，可以重新自定义 Layout 的内容，并借助 Rspress 提供的各个 Runtime API （如 usePageData）来获取编译时数据、路由等信息。

关于自定义主题的详情，你可以参考「自定义主题」文档。

插件机制

插件机制是 Rspress 至关重要的部分，它可以让你在搭建站点的过程中，方便地扩展 Rspress 的功能。详情可以查看插件介绍文档。

组件文档

Demo 预览

Rspress 提供了 preview 插件，可以自动为你生成组件预览。当你注册 preview 插件后，在 mdx 文件中声明如下的代码块：

import React from 'react';
import { Tag, Space } from '@arco-design/web-react';
import '@arco-design/web-react/dist/css/arco.css';
const COLORS = [
  'red',
  'orangered',
  'orange',
  'gold',
  'lime',
  'green',
  'cyan',
  'blue',
  'arcoblue',
  'purple',
  'pinkpurple',
  'magenta',
  'gray',
];

export default () => {
  return (
    <Space>
      {COLORS.map((color, i) => (
        <Tag key={i} color={color}>
          {color}
        </Tag>
      ))}
    </Space>
  );
};

那么你可以看到如下的预览效果：

当然，插件同时也支持移动端预览模式，你可以通过插件配置开启，预览效果如下：

Demo 实时 playground

对于组件文档，如果能提供组件的实时编辑的能力，将能大大提高文档的交互体验。

为了实现这个功能，你只需要注册官方的 playground 插件，然后在 .mdx 文件中声明你的代码块。（这里以上面的代码块为例）

接着，你将会在文档中看到下面的 playground 效果：

内置流畅的转场动画

View Transition API 是现代浏览器原生提供的一组 API，用于实现页面跳转过程中的过渡效果。在 Rspress 中我们也跟进了这个特性，基于 View Transition 实现了文档的过渡动画，而未使用任何第三方 SPA 的动画方案。在未来，我们也会探索出更多的动画效果，进一步提升体验。

export default defineConfig({
  themeConfig: {
    // 开启 View Transition 过渡
    enableContentAnimation: true,
    enableAppearanceAnimation: true,
  },
});

与其它 SSG 框架的区别

与 Docusaurus 的区别

Docusaurus 是 Meta 开源的一款 SSG 框架，它和 Rspress 一样使用 React 作为渲染框架，且支持 MDX，但 Rspress 与 Docusaurus 的区别主要在于：

Rspress 通过 lazyCompilation 和持久化缓存提供更好的构建性能，实现毫秒级的冷启动，详见构建性能。
Rspress 的配置更简单，上手成本更低。Rspress 的配置更加简单，不引入过多的概念，尽可能降低心智负担，比如提供开箱即用的搜索功能、符合直觉的多版本文档管理方式等等。
Rspress 架构上对 Bundler 提供了更上层的抽象。对于 webpack、Rspack 这类底层的 Bundler，其配置项繁琐且不易上手。Docusaurus 选择直接暴露底层 Bundler 的配置项，而 Rspress 则对 Bundler 进行了更上层的抽象，提供了更加简单易用的配置项，比如你可以通过 builderConfig.html.tags 轻松添加 <head> 中的标签，而不用通过 Bundler 来注册 html-webpack-plugin 相关插件。

与 Nextra 的区别

Nextra 是 Vercel 开源的一款 SSG 框架，它也和 Rspress 一样使用 React 作为渲染框架，且支持 MDX。Rspress 与 Nextra 的区别主要在于：

Rspress 的构建性能更好。这一点可参考「与 Docusaurus 的区别」。
Rspress 整体更加轻量。Nextra 需要依赖 Next.js，其 SSG 流程也是基于 Next.js 的，因此 SSG 产物中并非纯粹的 HTML 文件，而是额外包含了一些 Next.js 的运行时代码，一方面导致了 Nextra 的产物体积更大，另一方面需要在部署时以应用的方式部署(使用 next start 命令)，而不能以纯静态站点的方式部署。但 Rspress 没有和任何应用框架绑定，因此产物更加轻量，可以很方便地以纯静态站点的方式部署。

与 VitePress 的区别

VitePress 是一款基于 Vite 静态站点生成器，它的特点是使用 Vue 作为渲染框架，且性能非常优秀。Rspress 与 VitePress 的区别主要在于：

Rspress 使用 React 作为渲染框架，而 VitePress 使用 Vue 作为渲染框架。
Rspress 使用 MDX 作为内容开发方式，而 VitePress 使用 Markdown 作为内容开发方式，并在 Markdown 中支持 Vue 组件，这同时也导致了底层编译工具链实现上的差异。
构建性能上，在开发阶段，Rspress 和 VitePress 都能很快地启动一个项目，而在生产环境下，VitePress 需要基于 Rollup 打包项目，因此会面临其他基于 JavaScript 的工具链类似的性能问题，此时 Rspress 会有更快的构建速度。

尝试 Rspress

进入快速开始了解如何使用 Rspress 快速搭建一个文档站点。

#介绍

#为什么选择 Rspress

#构建性能

#AI 友好

#MDX 支持

#文档站基础能力

#扩展机制

#功能特性

#一整套全新主题

#BEM 命名规范

#丰富的 CSS 变量

#rspress eject 命令

#自动生成布局

#MDX 支持

#集成 Shiki 用于代码块高亮

#SSG

#国际化（i18n）

#多版本文档

#全文搜索

#自定义主题

#插件机制

#组件文档

#Demo 预览

#Demo 实时 playground

#内置流畅的转场动画

#与其它 SSG 框架的区别

#与 Docusaurus 的区别

#与 Nextra 的区别

#与 VitePress 的区别

#尝试 Rspress

介绍

为什么选择 Rspress

构建性能

AI 友好

MDX 支持

文档站基础能力

扩展机制

功能特性

一整套全新主题

BEM 命名规范

丰富的 CSS 变量

`rspress eject` 命令

自动生成布局

MDX 支持

集成 Shiki 用于代码块高亮

SSG

国际化（i18n）

多版本文档

全文搜索

自定义主题

插件机制

组件文档

Demo 预览

Demo 实时 playground

内置流畅的转场动画

与其它 SSG 框架的区别

与 Docusaurus 的区别

与 Nextra 的区别

与 VitePress 的区别

尝试 Rspress