五分钟用 Rspress 从零到一搭建和部署一个文档站点

大家好，我是三元。

Rspress 简介

Rspress 是一款基于 Rspack 和 React 的静态站点生成器，主打以下的几个优势:

高性能。基于 Rust 语言工具链和大量的优化策略，项目构建性能明显领先于 React 的其它文档框架(详情见下图)，实现了项目秒启。
支持 MDX。这意味着你可以在 markdown 中渲染 React 组件，十分灵活，大大释放了文档开发的想象力。
简单易用。提供了很多开箱即用的功能，国际化、全文搜索、组件 playground 等等能力，尤其是无需任何配置就可以开启搜索功能，省心省力。
高度可扩展。内置了一套完整的插件机制，支持自定义插件，同时支持自定义主题。

如果你想了解 Rspress 与 VitePress 的区别，可以移步官方的对比文档 rspress.dev/zh/guide/st...

接下来我们就来基于 Rspress 来快速搭建一个文档站点吧。

一键创建项目

通过下面的命令，你可以一键初始化项目：

bash 复制代码

# 使用 npm
npm create rspress@latest
# 使用 yarn
yarn create rspress@latest
# 使用 pnpm
pnpm create rspress@latest

然后根据交互填写基本的信息即可(这里使用的是 pnpm 包管理器)：

根据提示，我们执行 pnpm install 和 pnpm dev，然后你可以在本地访问项目。

增加导航栏和侧边栏

对于一个文档站点而言，导航栏和侧边栏是非常关键的布局模块。在 Rspress 中，你可以通过 _meta.json 配置文件轻松地完成配置，目前 docs 目录如下：

ts 复制代码

.
├── _meta.json // 配置导航栏
├── guide
│   ├── _meta.json // 配置侧边栏
│   ├── basic
│   │   ├── _meta.json // 配置侧边栏
│   │   └── start.mdx
│   └── index.md
├── hello.md
├── index.md
└── ...

其中，docs 目录下的 _meta.json 为导航栏的配置，你可以根据默认的配置项追加更多的导航栏菜单，比较简单：

ts 复制代码

[
  {
    "text": "Guide",
    "link": "/guide/",
    "activeMatch": "/guide/"
  },
  {
    "text": "Hello World",
    "link": "/hello/",
    "activeMatch": "/hello/"
  },
  {
    "text": "API",
    "link": "https://rspress.dev/api/index.html"
  }
]

至于侧边栏，你需要新建 guide/basic/_meta.json 和 guide/basic/start.mdx 文件，内容分别如下：

json 复制代码

// guide/basic/_meta.json
// 按顺序声明当前目录下的文章，这里指的是 `start.mdx`，可忽略后缀名
["start"]

md 复制代码

# 快速开始

这是 guide/basic/start.mdx 的内容

同时，我们需要在 guide/_meta.json 添加如下的配置：

ts 复制代码

[
  {
    "type": "dir",
    "name": "basic",
    "label": "基础指南"
  }
]

这里我们注册了 guide 目录下的 basic 子目录的内容。因此你可以看到 _meta.json 里面可以声明两种类型的数据：文件和目录，具体的声明方式已经在上面的例子中展示。

保存文件后访问项目，你可以发现侧边栏已经生成出来了：

你也可以根据上面的声明方式继续扩展，将你的侧边栏做的更加丰富。

通过 GitHub Pages 部署

接下来你可以新建一个 GitHub 仓库（以这里名为 rspress-demo 的仓库为例）。值得注意的是，当你通过 GitHub Pages 访问的时候，路径会带上仓库名的前缀，如https://xxx.github.io/rspress-demo。在这种情况下，你需要在 rspress.config.ts 配置文件中添加base属性，保证线上正常访问：

diff 复制代码

import { defineConfig } from "rspress/config";

export default defineConfig({
+  base: "/rspress-demo",
});

在仓库的 Setting 界面选择 Pages，然后在 source 栏选择 GitHub Actions:

现在你可以将代码推送到 main 分支上，这样会自动触发 GitHub Actions 流水线：

当流水线运行完成，你就可以通过域名访问线上的站点了：

至此，Rspress 项目的部署工作流就搭建完成了，之后当你往 main 分支推送代码后会进行站点的自动部署。

示例仓库链接：github.com/sanyuan0704...

后续指南

经过以上的步骤，我们部署了一个初步的文档站点，接下来，你可以根据如下的指南探索更多 Rspress 的功能：

如果觉得不错，欢迎大家给 Rspress 仓库点个 star，也非常欢迎大家给 Rspress 贡献，respect！