Rspress is a static site generator based on Rspack, rendered with the React framework. It comes with a default documentation theme, and you can quickly build a documentation site with Rspress. You can also customize the theme to meet your personalized static site needs, such as blog sites, product homepages, etc. Of course, you can also integrate the corresponding plugins provided by the official to easily build component library documentation.
Rspress is mainly built in the following directions:
These also represent some core requirements for SSG site development. The following will introduce these aspects separately.
As the project becomes larger and larger, team members often worry about the lengthy project startup time, which negatively affects the development experience. The longer the project development time, the more obvious this deterioration of experience.
We couldn't help but start thinking, can we break the limitations of the current community tool chain, break through the performance bottleneck of the existing SSG framework, and achieve the effect of instant startup for most project scenarios?
Then, we continued to explore in this direction and finally achieved this effect on Rspress. Taking the content of Rspress's official website documentation as an example, the performance comparison between Rspress, Docusaurus, and Nextra is as follows:
If there is only one most core optimization method, it is undoubtedly the Rust Frontend Toolchain
. We mainly use the Rust toolchain in two performance-sensitive parts:
Markdown Compilation
, we also Rust this process to further speed up and customize Rspress's Markdown compiler (ie @rspress/mdx-rs
). This compiler is nearly 20 times more efficient than the JS version of the compiler in the community:At the same time, Rspress internally also applies many other build optimization methods, such as pre-bundle of theme
, etc. These additional optimization methods, combined with the powerful Rust front-end toolchain, push the compilation performance of the SSG framework to a new height.
In order to ensure the flexibility of content development, Rspress chooses to support the MDX content format.
Because MDX actually represents a componentized content organization method behind it. On the one hand, documents are components, so we can reuse document fragments between different documents. On the other hand, any custom React components can be introduced in the document, greatly releasing the imagination of document development.
Of course, Rspress has also done a lot of work on the polishing of the basic capabilities of the documentation site, supporting the following functional features:
In the following text, we will introduce these functional features in detail.
Rspress internally designed various extension mechanisms to ensure sufficient customization capabilities, including:
Next, let's introduce the main functional features of Rspress.
For the construction of a documentation site, in addition to displaying the main content, we generally need the following layout modules:
For the document outline, Rspress will automatically extract the various titles in the document, generate outline information, and display it on the right side of the article page by default, without any other operations.
For the navigation bar and sidebar, we provide two config methods, you can choose one of them:
_meta.json
in the directory, such as:You can read the Auto Nav/Sidebar for config details.
We recommend using declarative config
under normal scenes, which has many benefits:
file directory structure
and the sidebar directory structure
is more intuitive.rspress.config.ts
config file to locate the corresponding position and then add/delete the config, thereby reducing the cost of switching development context.The programming config
is very useful in some scenarios where dynamic config generation is needed. For example, the official Rspress TypeDoc plugin will automatically convert a json data provided by TypeDoc into nav
and sidebar
configs.
MDX is a powerful content development format. You can not only write Markdown files as usual, but also use React components in the content of Markdown:
In addition, Rspress also supports some specific syntax, such as:
Details can be found in the Use MDX Document.
Rspress is a SSG framework. In the build process in the production environment, it will automatically help you generate static sites, that is, generate HTML content for each page. After the build process is completed, HTML will appear in the default output directory.
Then, you can deploy the contents of this product directory to any static site hosting service, such as Github Pages, Netlify, Vercel, etc.
At the same time, we also provide config to easily customize the HTML content generated by SSG. For details, please refer to the Static Site Generation Document.
Internationalization is a common requirement in a document-type site, and Rspress encapsulates the ability of internationalization to be simple and easy to use. In the framework, we abstract internationalization into the following requirements:
The framework has already supported these demand scenarios for you. You can follow the I18n Tutorial to step by step to implement internationalization for your site.
In some scenarios, we need to manage multi-version documents, and Rspress has built-in support for multi-version documents. On the one hand, you can enable this capability through simple config. On the other hand, you only need to organize the directory as usual, without introducing unnecessary directories and concepts, minimizing the mental burden:
Rspress provides out-of-the-box full-text search capabilities, which you can access without any config. It is based on the open-source FlexSearch engine, with the following effect:
Rspress supports two ways to customize themes:
usePageData
) to obtain compile-time data, routing information, etc.For details about custom themes, you can refer to the Custom Theme Documentation.
The plugin system is a crucial part of Rspress, which can help you conveniently extend the framework's functionality during site construction. Details can be found in the Plugin Introduction Documentation.
Rspress provides a preview plugin, which can automatically generate component previews for you. After you register the preview plugin, declare the following code block in the mdx file:
Then you can see the following preview effect:
Of course, the plugin also supports mobile preview mode, which you can enable through plugin config:
For component documentation, if real-time editing capabilities can be provided for components, it will greatly enhance the interactive experience of the documentation.
To achieve this feature, you only need to register the official playground plugin, and then declare your code block in the .mdx file. (Take the above code block as an example)
Next, you will see the following playground effect in the documentation:
View Transition API is a set of APIs natively provided by modern browsers for implementing transition effects during page jumps. In Rspress, we also followed up on this feature, implemented document transition animations based on View Transition, and did not use any third-party SPA animation schemes. In the future, we will explore more animation effects to further enhance the experience.
Docusaurus is an open-source SSG framework by Meta. Like Rspress, it uses React as the rendering framework and supports MDX. However, the main differences between Rspress and Docusaurus are:
Rspress has better build performance. Based on the Rust front-end toolchain, Rspress's project startup/build speed is 5 ~ 10 times faster than Docusaurus. For details, refer to Build Performance.
Rspress has simpler config and lower learning curve. Rspress's config is simpler, does not introduce too many concepts, and reduces cognitive load as much as possible. For example, it provides out-of-the-box search functionality, intuitive multi-version document management, etc.
Rspress provides a higher level of abstraction for Bundler in its architecture. For low-level Bundlers like webpack and Rspack, their config items are complex and not easy to get started with. Docusaurus chooses to directly expose the config items of the underlying Bundler, while Rspress provides a higher level of abstraction for Bundler, offering simpler and more user-friendly config items. For instance, you can easily add tags in <head>
through builderConfig.html.tags
, without having to register related plugins via Bundler like html-webpack-plugin
.
Nextra is an open-source SSG framework by Vercel. Like Rspress, it also uses React as the rendering framework and supports MDX. The main differences between Rspress and Nextra are:
next start
command) rather than being deployed as a pure static site. But Rspress is not bound to any application framework, so its output is lighter and can be conveniently deployed as a pure static site.VitePress is a static site generator based on Vite. It is characterized by using Vue as the rendering framework and has excellent performance. The main differences between Rspress and VitePress are:
Go to Quick Start to learn how to use Rspress to quickly build a documentation site.