DOCSEARCHbyAlgolia
Submit Docs

Rspress Documentation

website·Indexed 34 days ago

https://v1.rspress.dev/

A high-performance documentation site generator built with React and MDX. Features include Static Site Generation (SSG), internationalization (I18n), automatic layout generation, and a flexible extension mechanism. The documentation covers configuration for build, theme, and front matter, as well as official plugins like @rspress/plugin-playground, @rspress/plugin-api-docgen, and @rspress/plugin-typedoc.

Tokens
31.1K
Snippets
226
Records
246
Agent score
50%

What's inside Rspress

  1. Overview of Rspress features and architecture

    Rspress is a static site generator based on Rsbuild and rendered with React. It is optimized for high-performance documentation sites and offers the following core capabilities:

    • Build Performance: Uses a Rust-based toolchain (Rspack for bundling and @rspress/mdx-rs for Markdown compilation) to achieve significantly faster startup and build times compared to traditional JS-based tools.
    • MDX Support: Allows the use of React components directly within Markdown files for componentized content and fragment reuse.
    • Documentation Essentials: Built-in support for Static Site Generation (SSG), Internationalization (I18n), multi-version document management, and full-text search.
    • Developer Experience: Automatic layout generation for navigation bars, sidebars, and article outlines, as well as built-in demo previews and playgrounds for component libraries.

  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 content is compiled.
    • Custom Routing: Add new custom pages and routes (e.g., a /blog page) beyond the default 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 specifically before or after the build process.
    • Global UI Components: Inject global React components into the runtime page for features like 'Back to Top' buttons or global side-effect logic.

  3. Create an Overview page in Rspress

    An Overview page is a built-in preview page that automatically generates a structured summary of a directory's contents. To enable this feature, add overview: true to the frontmatter of a markdown file. You can optionally specify a title in the frontmatter; if provided, you do not need to include an H1 title within the markdown body.
    ---
overview: true
title: API Overview
---

This is an Overview page of our website.

  4. Use @rspress/plugin-container-syntax to parse Markdown containers

    The @rspress/plugin-container-syntax is a built-in Rspress plugin that converts container syntax in Markdown or MDX files into JSX syntax and applies corresponding styles. It supports common container patterns such as :::tip, :::warning, and the GitHub-style > [!NOTE] syntax.
    :::tip
This is a tip container
:::

:::warning
This is a warning container
:::

> [!NOTE]
This is a note container

  6. Use built-in Rspress theme components

    Rspress provides a set of built-in components for documentation pages. To simplify imports, the rspress/theme package is aliased as @theme within Rspress, allowing you to import components directly using @theme.

  7. Generate navigation and sidebars using _meta.json

    Rspress allows automatic generation of the navbar and sidebar using _meta.json files located within the documentation directory. This approach keeps the main rspress.config.ts file concise.

    Critical Constraint: Automated navigation only works if the nav and sidebar configurations are omitted from the rspress.config.ts file.

  8. Configure the overview page filters

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

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

  9. Generate sub-preview pages for directories

    To create a nested Overview page for a specific sub-directory (e.g., a theme directory), use one of the following two methods:

    1. Parent Directory File: 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. Internal Index File: 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.
    // theme/_meta.json
[
  {
    "type": "file",
    "name": "index",
    "label": "Overview"
  }
]

  10. Understand Rspress file-system routing mapping

    Rspress uses file system routing where the file path of a page is mapped directly to its routing path. The system automatically scans the root directory and all subdirectories to generate these routes.
    File Path          -> Route Path
index.md           -> /
/foo.md            -> /foo
/foo/bar.md        -> /foo/bar
/zoo/index.md      -> /zoo/

  11. Rspress SSG and Deployment

    Rspress is a Static Site Generation (SSG) framework. During the production build process, it generates static HTML files for every page in the output directory. These files can be deployed to any static hosting service such as GitHub Pages, Netlify, or Vercel.

  12. Create API overview pages with Overview

    The Overview component is used to create structured API reference pages with grouped items and optional headers.
    import { Overview } from 'rspress/theme';

interface GroupItem {
  text?: string;
  link?: string;
  headers?: Header[];
}

interface Group {
  name: string;
  items: GroupItem[];
}

interface OverviewProps {
  content?: React.ReactNode;
  groups?: Group[];
  defaultGroupTitle?: string;
  overviewHeaders?: number[];
}