Quick Start

This chapter will guide you from scratch to create your first Rspress project and understand the basic structure and configuration.

Prerequisites

Before starting, ensure your system has the following tools installed:

Node.js

Rspress requires Node.js version >= 16.0.0.

# Check Node.js version
node -v

# If version is too low, visit https://nodejs.org/ to download the latest version

Package Manager

You can use any of npm, yarn, pnpm, or bun:

# npm (comes with Node.js)
npm -v

# yarn
npm install -g yarn

# pnpm (recommended, faster and saves space)
npm install -g pnpm

# bun (next-generation package manager)
npm install -g bun

Create a New Project

Using the Scaffold

Rspress provides an official scaffold tool for quick project creation:

# Using npm
npm create rspress@latest

# Using yarn
yarn create rspress

# Using pnpm
pnpm create rspress

# Using bun
bun create rspress

Interactive Configuration

After running the command, you'll enter interactive configuration:

? Project name: my-rspress-site
? Select a template:
  > Documentation Site
    Blog Site
    Component Library Docs

Select Documentation Site to begin.

Project Initialization

The scaffold will automatically:

1. Create project directory
2. Install necessary dependencies
3. Generate basic configuration files
4. Create example documentation

✔ Project name: my-rspress-site
✔ Select a template: Documentation Site
✔ Initialize git repository? Yes

Creating project at ./my-rspress-site...

✔ Project created successfully!

Next steps:
  cd my-rspress-site
  npm run dev

Project Structure

After creation, the project structure looks like this:

my-rspress-site/
├── docs/                   # Documentation source files
│   ├── index.md           # Homepage
│   ├── guide/             # Guide directory
│   │   └── index.md
│   └── api/               # API directory
│       └── index.md
├── public/                 # Static assets directory
│   └── favicon.ico
├── rspress.config.ts      # Rspress configuration
├── package.json           # Project configuration
├── tsconfig.json          # TypeScript configuration
└── .gitignore            # Git ignore file

Core Files

rspress.config.ts

This is the main Rspress configuration file:

import { defineConfig } from 'rspress/config';

export default defineConfig({
  // Site root path
  root: 'docs',

  // Site title
  title: 'My Rspress Site',

  // Site description
  description: 'A documentation site powered by Rspress',

  // Site icon
  icon: '/favicon.ico',

  // Website logo
  logo: {
    light: '/logo-light.png',
    dark: '/logo-dark.png',
  },

  // Theme configuration
  themeConfig: {
    // Social links
    socialLinks: [
      {
        icon: 'github',
        mode: 'link',
        content: 'https://github.com/web-infra-dev/rspress',
      },
    ],
  },
});

package.json

Contains project dependencies and script commands:

{
  "name": "my-rspress-site",
  "version": "1.0.0",
  "scripts": {
    "dev": "rspress dev",
    "build": "rspress build",
    "preview": "rspress preview"
  },
  "dependencies": {
    "rspress": "^1.0.0"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "typescript": "^5.0.0"
  }
}

Start Development Server

Enter Project Directory

cd my-rspress-site

Start Development Mode

# Using npm
npm run dev

# Using yarn
yarn dev

# Using pnpm
pnpm dev

# Using bun
bun dev

Access the Site

After the development server starts, you'll see:

  RSPRESS v1.0.0

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h to show help

Open http://localhost:5173 in your browser to see your first Rspress site!

Write Your First Document

Create a New Page

Create a new Markdown file in the docs directory:

# Create a new guide page
touch docs/guide/getting-started.md

Write Content

Add content to getting-started.md:

# Getting Started

Welcome to Rspress!

## Step 1

This is your first documentation page.

## Step 2

You can use standard Markdown syntax.

### Code Example

\`\`\`javascript
function hello() {
  console.log('Hello Rspress!');
}
\`\`\`

### Callout Boxes

::: tip
This is a tip box
:::

::: warning
This is a warning box
:::

::: danger
This is a danger box
:::

View Results

After saving the file, the development server will automatically reload, and you can immediately see the new page in your browser. Visit:

http://localhost:5173/guide/getting-started

Configure Navigation

Edit rspress.config.ts to add navigation configuration:

export default defineConfig({
  // ... other config

  themeConfig: {
    nav: [
      {
        text: 'Home',
        link: '/',
      },
      {
        text: 'Guide',
        link: '/guide/',
      },
      {
        text: 'API',
        link: '/api/',
      },
      {
        text: 'About',
        items: [
          {
            text: 'Team',
            link: '/about/team',
          },
          {
            text: 'Changelog',
            link: '/about/changelog',
          },
        ],
      },
    ],
  },
});

Configure Sidebar

Configure sidebar for each directory:

export default defineConfig({
  // ... other config

  themeConfig: {
    sidebar: {
      '/guide/': [
        {
          text: 'Getting Started',
          items: [
            {
              text: 'Introduction',
              link: '/guide/',
            },
            {
              text: 'Quick Start',
              link: '/guide/getting-started',
            },
          ],
        },
        {
          text: 'Advanced',
          items: [
            {
              text: 'Configuration',
              link: '/guide/config',
            },
            {
              text: 'Theme',
              link: '/guide/theme',
            },
          ],
        },
      ],
      '/api/': [
        {
          text: 'API Reference',
          items: [
            {
              text: 'CLI',
              link: '/api/cli',
            },
            {
              text: 'Config Options',
              link: '/api/config',
            },
          ],
        },
      ],
    },
  },
});

Build for Production

Build Command

After development, use the build command to generate production version:

# Using npm
npm run build

# Using yarn
yarn build

# Using pnpm
pnpm build

# Using bun
bun run build

Build Output

After building, static files will be generated in the doc_build directory:

my-rspress-site/
└── doc_build/
    ├── index.html
    ├── guide/
    │   └── getting-started.html
    ├── assets/
    │   ├── css/
    │   └── js/
    └── ...

Preview Locally

After building, you can preview the production version locally:

# Using npm
npm run preview

# Using yarn
yarn preview

# Using pnpm
pnpm preview

# Using bun
bun run preview

Common Commands Summary

# Development mode (hot reload)
npm run dev

# Production build
npm run build

# Preview production version
npm run preview

# Clear cache
rm -rf node_modules/.rspress

Next Steps

Congratulations! You've successfully created your first Rspress project. Next, you can:

1. Learn Conventional Routing to understand how files map to URLs
2. Explore Navigation & Sidebar for deeper navigation configuration
3. Try MDX & React Components to make docs more dynamic

---

💡 Development Tips

• Use pnpm to save disk space and speed up installation
• Keep npm run dev running during development to enjoy smooth hot reload
• When encountering strange issues, try clearing cache: rm -rf node_modules/.rspress

📝 Notes

• Ensure Node.js version >= 16.0.0
• First-time dependency installation may take a few minutes
• Development server default port is 5173, will automatically choose another if occupied