介绍

Rspress 是一个基于 Rsbuild 的静态站点生成器，使用 React 渲染。它内置开箱即用的文档主题，帮助你快速上线站点。你还可以通过自定义主题或官方插件，满足博客、产品主页或组件库文档等多种场景。

为什么选择 Rspress

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

构建性能。保证足够快的启动速度，带来良好的开发体验。
MDX 支持。通过 MDX，我们可以方便地复用文档片段，以及在文档中渲染自定义的 React 组件。
文档站基础能力。包括国际化、多版本支持、全文搜索、组件库文档等。
可扩展性。内置插件系统，支持通过插件 API 来扩展功能。

这几项正是现代静态站点的核心需求，下面将逐一说明 Rspress 如何满足它们。

构建性能

随着项目变大，启动缓慢会直接拖累开发体验。Rspress 通过在两个关键环节使用 Rust 前端工具链 来保证“秒启”和快速构建：

打包工具。Rspress 采用团队自研的 Rspack，利用 Rust、多线程并行和增量编译，相比传统 JS bundler 可带来 5～10 倍的性能提升。
Markdown 编译器。Rspress 内置的 Rust 版编译器（@rspress/mdx-rs）针对 MDX 做了定制，相比社区的 JS 版本有近 20 倍的性能提升：

同时，Rspress 还提供主题预打包、样式预生成等优化，配合 Rust 工具链，让开发与产物构建都保持高速稳定。

MDX 支持

为了保持内容开发的灵活性，Rspress 选择了 MDX。文档可以作为组件复用片段，也能随时引入自定义 React 组件，极大释放文档的表达空间。

文档站基础能力

Rspress 也为文档站的基础能力做好了默认支持：

自动生成导航、侧边栏与大纲。
生产环境直接生成 HTML 的静态站点。
多语言国际化。
开箱即用的全文搜索。
多版本文档管理。
主题可定制。
自带组件 Demo 预览与 Playground。

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

扩展机制

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

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

功能特性

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

自动生成布局

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

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

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

导航栏和侧边栏有两种配置方式，可按习惯选择：

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

_meta.json

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

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

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

推荐默认使用 声明式配置，配置更简洁，目录与侧边栏结构一一对应，增删项时无需往返 rspress.config.ts。编程式配置 适用于需要动态生成的场景。例如，官方 TypeDoc 插件会将 TypeDoc 的 JSON 输出直接转换为 nav 与 sidebar。

MDX 支持

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

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

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

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

SSG

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

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

你也可以通过配置自定义生成的 HTML，详见「静态站点生成」文档。

国际化（i18n）

国际化在一个文档类型的站点中是一个很常见的需求，而 Rspress 将国际化的能力封装得足够简单易用，在 Rspress 中我们将国际化抽象为如下的需求：

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

Rspress 已经为你支持了这些需求场景，你可以根据 I18n 教程来一步步为你的站点实现国际化。

多版本文档

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

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

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

// 目录结构
docs
├── v1
│   ├── README.md
│   └── guide
│       └── README.md
└── v2
    ├── 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';

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

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

插件机制

插件机制是 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 默认使用 mdx-rs 来提供更好的构建性能，详见构建性能。
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

#构建性能

#MDX 支持

#文档站基础能力

#扩展机制

#功能特性

#自动生成布局

#MDX 支持

#SSG

#国际化（i18n）

#多版本文档

#全文搜索

#自定义主题

#插件机制

#组件文档

#Demo 预览

#Demo 实时 playground

#内置流畅的转场动画

#与其它 SSG 框架的区别

#与 Docusaurus 的区别

#与 Nextra 的区别

#与 VitePress 的区别

#尝试 Rspress

介绍

为什么选择 Rspress

构建性能

MDX 支持

文档站基础能力

扩展机制

功能特性

自动生成布局

MDX 支持

SSG

国际化（i18n）

多版本文档

全文搜索

自定义主题

插件机制

组件文档

Demo 预览

Demo 实时 playground

内置流畅的转场动画

与其它 SSG 框架的区别

与 Docusaurus 的区别

与 Nextra 的区别

与 VitePress 的区别

尝试 Rspress