DOCSEARCHbyAlgolia
Submit Docs

Rspress Documentation

website·Indexed 34 days ago

https://v1.rspress.rs/

Documentation for Rspress, a static site generator featuring MDX support, a default theme with multi-versioning, and a variety of official plugins such as @rspress/plugin-typedoc, @rspress/plugin-shiki, and @rspress/plugin-api-docgen. This version 1.0 documentation covers configuration, client APIs, build commands, and deployment guides.

Tokens
30.9K
Snippets
217
Records
243
Agent score
56%

What's inside Rspress

  1. Overview of Rspress static site generator

    Rspress is a high-performance static site generator (SSG) based on Rsbuild and rendered with React. It is specifically designed for documentation sites but can be customized for blogs or product homepages. Key technical advantages include the use of a Rust-based frontend toolchain (Rspack) for bundling and a custom Rust-based Markdown compiler (@rspress/mdx-rs), which significantly reduces startup and build times compared to traditional JavaScript-based tools.

  2. Overview of Rspress Plugin System capabilities

    The Rspress plugin system allows developers to extend the framework's functionality across the Node side (build time) and the Browser Runtime. Key extension points include:

    • Markdown/MDX Compilation: Integrate remark or rehype plugins to modify how Markdown/MDX is processed.
    • Custom Routing: Add new routes (e.g., a /blog page) beyond the framework's conventional routing.
    • Build Tool Configuration: Customize the underlying Rsbuild configuration or add Rspack/Rsbuild plugins.
    • Page Metadata: Extend the logic used to calculate page metadata (like title and description), which can then be accessed via the usePageData hook.
    • Build Lifecycle Hooks: Execute custom logic before or after the build process (e.g., cleaning up event listeners).
    • Global UI Components: Inject global React components into the runtime page for features like 'Back to Top' buttons or global side-effect logic.

  3. Understand Rspress Static Site Generation (SSG)

    Rspress automatically performs Static Site Generation (SSG) during production builds. It pre-renders components into HTML strings and writes them to HTML files in the output directory (e.g., doc_build). This results in faster First Contentful Paint (FCP) and improved SEO as search engine spiders can crawl complete HTML content. In development environments, Rspress uses traditional SPA rendering instead of pre-rendering.

  4. Compare Rspress and VitePress technical architecture

    Rspress and VitePress differ in their core frameworks and build toolchains:

    • Rendering Framework: Rspress uses React, whereas VitePress uses Vue.
    • Content Development: Rspress uses MDX for content. VitePress uses Markdown with support for Vue components, resulting in different underlying compilation toolchains.
    • Build Performance: While both offer fast development starts, Rspress provides faster production build speeds because VitePress relies on Rollup for bundling, which is subject to the performance constraints of JavaScript-based toolchains.

  5. Rspress Internationalization (I18n) capabilities

    Rspress provides built-in support for internationalization, covering I18n data source definition, site configuration for different languages, directory organization for language versions, and the use of I18n data within custom components.

  7. Generate sub-preview pages for directories

    To create a nested overview page for a specific sub-directory (e.g., a theme directory), you can use one of two methods:

    1. Create a markdown file in the parent directory with the same name as the sub-directory (e.g., theme.md) and set overview: true in its frontmatter.
    2. Create an index.md file inside the sub-directory, set overview: true in its frontmatter, and ensure the sub-directory's _meta.json includes that index file.
    # Method 1: Parent directory file
├── docs
│ ├── api
│ │ ├── index.md
│ │ ├── theme.md  <-- (overview: true)
│ │ ├── theme
│ │ │ ├── component.mdx
│ │ └── ...

# Method 2: Internal index file
├── docs
│ ├── api
│ │ ├── theme
│ │ │ ├── index.md <-- (overview: true)
│ │ │ ├── component.mdx
│ │ └── ...

  8. Rspress Static Site Generation (SSG) overview

    Rspress is an SSG framework that automatically generates static HTML files for every page during the production build process. The resulting HTML is placed in the default output directory and can be deployed to any static hosting service like GitHub Pages, Netlify, or Vercel.

  9. Create an Overview page in Rspress

    Rspress provides a built-in preview page (Overview page) that automatically generates a content structure based on the _meta.json configuration and the H1/H2 headers of the linked articles. To enable this, you must set overview: true in the markdown file's frontmatter. You can optionally set a title in the frontmatter to override the default 'Overview' title, removing the need for an H1 header in the markdown body.
    ---
overview: true
title: API Overview
---

This is an Overview page of our website.

  10. Configure Overview page structure via _meta.json

    The Overview page automatically aggregates content based on the _meta.json files in the directory structure. It creates groups based on directories and lists articles within those groups. To control which header levels are displayed in the overview, use the overviewHeaders configuration in _meta.json or the file's frontmatter (defaults to [2]).
    // api/_meta.json
[
  {
    "type": "file",
    "name": "index",
    "label": "API Overview"
  },
  {
    "type": "dir",
    "name": "theme",
    "label": "Theme"
  }
]

    // api/theme/_meta.json ["component", "utils"]

  11. Use @rspress/plugin-container-syntax to render container blocks

    The @rspress/plugin-container-syntax plugin is a built-in Rspress plugin that parses container syntax in Markdown and MDX files and compiles them into JSX syntax. It supports common container patterns such as :::tip, :::warning, and > [!NOTE], while automatically applying the necessary styles to these blocks.

  12. Configure the overview page filters

    The overview configuration allows you to customize the text used in the filter component of the overview page.
    import { defineConfig } from 'rspress/config';

export default defineConfig({
  themeConfig: {
    overview: {
      filterNameText: 'Filter',
      filterPlaceholderText: 'Enter keyword',
      filterNoResultText: 'No matching API found',
    },
  },
});