垦荒学园

简体中文

English

简体中文

English

切换主题

快速开始 ​

本章将带你从零开始，创建第一个 Rspress 项目，并了解项目的基本结构和配置。

环境准备 ​

在开始之前，请确保你的系统已安装以下工具：

Node.js ​

Rspress 需要 Node.js 版本 >= 16.0.0。

bash
# 检查 Node.js 版本
node -v

# 如果版本过低，请访问 https://nodejs.org/ 下载最新版本

包管理器 ​

可以使用 npm、yarn、pnpm 或 bun 中的任意一个：

bash
# npm (Node.js 自带)
npm -v

# yarn
npm install -g yarn

# pnpm (推荐，更快更省空间)
npm install -g pnpm

# bun (新一代包管理器)
npm install -g bun

创建新项目 ​

使用脚手架创建 ​

Rspress 提供了官方脚手架工具，可以快速创建项目：

bash
# 使用 npm
npm create rspress@latest

# 使用 yarn
yarn create rspress

# 使用 pnpm
pnpm create rspress

# 使用 bun
bun create rspress

交互式配置 ​

运行上述命令后，会进入交互式配置：

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

选择 Documentation Site 开始。

项目初始化 ​

脚手架会自动：

  1. 创建项目目录
  2. 安装必要依赖
  3. 生成基础配置文件
  4. 创建示例文档
bash
✔ 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

项目结构 ​

创建完成后，项目结构如下：

my-rspress-site/
├── docs/                   # 文档源文件目录
│   ├── index.md           # 首页
│   ├── guide/             # 指南目录
│   │   └── index.md
│   └── api/               # API 目录
│       └── index.md
├── public/                 # 静态资源目录
│   └── favicon.ico
├── rspress.config.ts      # Rspress 配置文件
├── package.json           # 项目配置
├── tsconfig.json          # TypeScript 配置
└── .gitignore            # Git 忽略文件

核心文件说明 ​

rspress.config.ts ​

这是 Rspress 的主配置文件：

typescript
import { defineConfig } from 'rspress/config';

export default defineConfig({
  // 站点根路径
  root: 'docs',

  // 站点标题
  title: 'My Rspress Site',

  // 站点描述
  description: 'A documentation site powered by Rspress',

  // 站点图标
  icon: '/favicon.ico',

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

  // 主题配置
  themeConfig: {
    // 社交链接
    socialLinks: [
      {
        icon: 'github',
        mode: 'link',
        content: 'https://github.com/web-infra-dev/rspress',
      },
    ],
  },
});

package.json ​

包含项目依赖和脚本命令：

json
{
  "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"
  }
}

启动开发服务器 ​

进入项目目录 ​

bash
cd my-rspress-site

启动开发模式 ​

bash
# 使用 npm
npm run dev

# 使用 yarn
yarn dev

# 使用 pnpm
pnpm dev

# 使用 bun
bun dev

访问站点 ​

开发服务器启动后，会显示：

bash
  RSPRESS v1.0.0

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

在浏览器中打开 http://localhost:5173，你将看到你的第一个 Rspress 站点！

编写第一个文档 ​

创建新页面 ​

在 docs 目录下创建新的 Markdown 文件：

bash
# 创建一个新的指南页面
touch docs/guide/getting-started.md

编写内容 ​

在 getting-started.md 中添加内容：

markdown
# 开始使用

欢迎使用 Rspress！

## 第一步

这是你的第一个文档页面。

## 第二步

你可以使用标准的 Markdown 语法。

### 代码示例

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

### 提示框

::: tip
这是一个提示框
:::

::: warning
这是一个警告框
:::

::: danger
这是一个危险框
:::

查看效果 ​

保存文件后，开发服务器会自动重新加载，你可以立即在浏览器中看到新页面。访问：

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

配置导航栏 ​

编辑 rspress.config.ts，添加导航配置：

typescript
export default defineConfig({
  // ... 其他配置

  themeConfig: {
    nav: [
      {
        text: '首页',
        link: '/',
      },
      {
        text: '指南',
        link: '/guide/',
      },
      {
        text: 'API',
        link: '/api/',
      },
      {
        text: '关于',
        items: [
          {
            text: '团队介绍',
            link: '/about/team',
          },
          {
            text: '更新日志',
            link: '/about/changelog',
          },
        ],
      },
    ],
  },
});

配置侧边栏 ​

为每个目录配置侧边栏：

typescript
export default defineConfig({
  // ... 其他配置

  themeConfig: {
    sidebar: {
      '/guide/': [
        {
          text: '开始',
          items: [
            {
              text: '介绍',
              link: '/guide/',
            },
            {
              text: '快速开始',
              link: '/guide/getting-started',
            },
          ],
        },
        {
          text: '进阶',
          items: [
            {
              text: '配置',
              link: '/guide/config',
            },
            {
              text: '主题',
              link: '/guide/theme',
            },
          ],
        },
      ],
      '/api/': [
        {
          text: 'API 参考',
          items: [
            {
              text: 'CLI',
              link: '/api/cli',
            },
            {
              text: '配置项',
              link: '/api/config',
            },
          ],
        },
      ],
    },
  },
});

构建生产版本 ​

构建命令 ​

开发完成后，使用构建命令生成生产版本：

bash
# 使用 npm
npm run build

# 使用 yarn
yarn build

# 使用 pnpm
pnpm build

# 使用 bun
bun run build

构建输出 ​

构建完成后，静态文件会生成在 doc_build 目录：

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

本地预览 ​

构建完成后，可以本地预览生产版本：

bash
# 使用 npm
npm run preview

# 使用 yarn
yarn preview

# 使用 pnpm
pnpm preview

# 使用 bun
bun run preview

常用命令总结 ​

bash
# 开发模式（热更新）
npm run dev

# 生产构建
npm run build

# 预览生产版本
npm run preview

# 清除缓存
rm -rf node_modules/.rspress

下一步 ​

恭喜！你已经成功创建了第一个 Rspress 项目。接下来，你可以：

  1. 学习 约定式路由，了解文件如何映射到 URL
  2. 探索 导航栏与侧边栏，深入了解导航配置
  3. 尝试 MDX 及 React 组件，让文档更加动态

💡 开发技巧

  • 使用 pnpm 可以节省磁盘空间并加快安装速度
  • 开发时保持 npm run dev 运行，享受热更新带来的流畅体验
  • 遇到奇怪的问题时，尝试清除缓存：rm -rf node_modules/.rspress

📝 注意事项

  • 确保 Node.js 版本 >= 16.0.0
  • 首次安装依赖可能需要几分钟
  • 开发服务器默认端口是 5173，如果被占用会自动选择其他端口