Introduction to Rspress

What is Rspress?

Rspress is a modern static site generator developed by ByteDance's Web Infra team, specifically designed for technical documentation websites. Built on Rust, it combines the powerful features of React and MDX to provide developers with a fast, flexible, and easy-to-use documentation solution.

Why Choose Rspress?

1. Ultimate Performance

Rspress's core build engine is written in Rust, offering several times the performance improvement compared to traditional JavaScript toolchains:

Fast Build - Build times for large documentation projects reduced from minutes to seconds
Instant Hot Reload - See changes almost instantly when editing docs during development
Optimized Output - Automatic code splitting and lazy loading for optimal loading performance

2. Developer Experience First

Rspress prioritizes developer experience, providing rich features:

Conventional Routing - File system-based routing with no manual configuration needed
MDX Support - Seamlessly use React components in Markdown
TypeScript Support - Complete type definitions for better development experience
Rich Plugins - Flexible plugin system for easy functionality extension

3. Feature Complete

As a professional documentation tool, Rspress provides all essential features:

Full-text Search - Built-in high-performance search based on FlexSearch
Internationalization - Comprehensive multi-language support
Theme Customization - Flexible theme system with deep customization
Code Highlighting - Shiki-based code highlighting with multiple themes
Responsive Design - Perfect adaptation for desktop, tablet, and mobile devices

Core Features

Rust-based Build Engine

Rspress uses a Rust-written build toolchain, offering significant performance advantages over JavaScript tools:

typescript

// Traditional build tools might take 2-3 minutes
// Rspress only needs 10-20 seconds

// Hot reload response time
// Traditional tools: 1-2 seconds
// Rspress: 100-200 milliseconds

MDX - Markdown + JSX

MDX allows you to use React components in Markdown, making documentation more dynamic and interactive:

mdx

# My Documentation

This is regular Markdown content.

<CustomComponent prop="value">
  You can use React components in Markdown!
</CustomComponent>

## More Content

Continue using Markdown syntax...

Conventional Routing

Rspress uses file system-based routing, where file structure equals route structure:

docs/
├── index.md           -> /
├── guide/
│   ├── index.md      -> /guide
│   ├── start.md      -> /guide/start
│   └── config.md     -> /guide/config
└── api/
    └── cli.md        -> /api/cli

Automatically generate navigation bars and sidebars based on directory structure and file frontmatter, reducing manual configuration:

yaml

---
title: Page Title
sidebar_position: 1
---

Technical Architecture

Tech Stack

Rspress's tech stack includes:

Build Engine: Rust (via Rspack)
Frontend Framework: React 18
Routing: React Router
Content Processing: MDX
Code Highlighting: Shiki
Search Engine: FlexSearch
Styling Solution: CSS Modules

Workflow

mermaid

graph LR
    A[Markdown/MDX Files] --> B[Rspack Compilation]
    B --> C[React Components]
    C --> D[Static HTML]
    D --> E[Production Deployment]
    B -.-> F[Dev Server]
    F -.-> G[Hot Reload]

Comparison with Other Tools

Rspress vs VitePress

Feature	Rspress	VitePress
Build Engine	Rust (Rspack)	JavaScript (Vite)
Build Speed	Extremely Fast	Fast
Frontend Framework	React	Vue
MDX Support	✅ Native	❌ Plugin Required
Component Ecosystem	React Ecosystem	Vue Ecosystem
TypeScript	✅ Full Support	✅ Full Support

Rspress vs Docusaurus

Feature	Rspress	Docusaurus
Build Speed	Extremely Fast	Medium
Configuration Complexity	Low	Medium
Conventional Routing	✅	❌
Auto Navigation	✅	Partial
Learning Curve	Gentle	Medium

Use Cases

Rspress is particularly suitable for:

1. Technical Documentation Sites

API documentation
Product user manuals
Developer guides
Tech blogs

2. Open Source Project Documentation

GitHub project docs
Framework/library official docs
Tool usage guides

3. Enterprise Internal Knowledge Bases

Team collaboration docs
Technical specifications
Best practices sharing

4. Tutorial and Course Websites

Online tutorials
Learning paths
Training materials

Quick Try

Want to quickly try Rspress? Just a few commands:

bash

# Create new project
npm create rspress@latest

# Enter project directory
cd my-rspress-site

# Install dependencies
npm install

# Start dev server
npm run dev

Open your browser to http://localhost:5173, and you'll see a running Rspress site!

Learning Resources

Official Resources

Community Resources

Next Steps

Now that you understand the basic concepts and features of Rspress, let's move on to the Quick Start chapter to create your first Rspress project!

💡 Tip

Rspress is a young but rapidly evolving project with a very active community. If you encounter issues, you can seek help in GitHub Issues or the Discord community.

📚 Further Reading

Rspack Official Documentation - Learn about Rspress's build engine
React Official Documentation - Deep dive into React
MDX Official Documentation - Master MDX syntax

Introduction to Rspress ​

What is Rspress? ​

Why Choose Rspress? ​

1. Ultimate Performance ​

2. Developer Experience First ​

3. Feature Complete ​

Core Features ​

Rust-based Build Engine ​

MDX - Markdown + JSX ​

Conventional Routing ​

Auto-generated Navigation ​

Technical Architecture ​

Tech Stack ​

Workflow ​

Comparison with Other Tools ​

Rspress vs VitePress ​

Rspress vs Docusaurus ​

Use Cases ​

1. Technical Documentation Sites ​

2. Open Source Project Documentation ​

3. Enterprise Internal Knowledge Bases ​

4. Tutorial and Course Websites ​

Quick Try ​

Learning Resources ​

Official Resources ​

Community Resources ​

Next Steps ​