大家好,我是三元。
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 详细介绍
- _meta.json 详细配置
- 接入国际化
- 多版本文档管理
- MDX 语法学习
- 使用静态资源
- Rspress 插件机制
- 如果你有搭建组件库文档的需求,可以使用 preview 插件 来实现组件预览。
如果觉得不错,欢迎大家给 Rspress 仓库 点个 star,也非常欢迎大家给 Rspress 贡献,respect!