五分钟用 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 installpnpm 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.jsonguide/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!

相关推荐
吕彬-前端15 分钟前
使用vite+react+ts+Ant Design开发后台管理项目(五)
前端·javascript·react.js
学前端的小朱18 分钟前
Redux的简介及其在React中的应用
前端·javascript·react.js·redux·store
guai_guai_guai27 分钟前
uniapp
前端·javascript·vue.js·uni-app
bysking1 小时前
【前端-组件】定义行分组的表格表单实现-bysking
前端·react.js
王哲晓2 小时前
第三十章 章节练习商品列表组件封装
前端·javascript·vue.js
fg_4112 小时前
无网络安装ionic和运行
前端·npm
理想不理想v2 小时前
‌Vue 3相比Vue 2的主要改进‌?
前端·javascript·vue.js·面试
酷酷的阿云2 小时前
不用ECharts!从0到1徒手撸一个Vue3柱状图
前端·javascript·vue.js
微信:137971205872 小时前
web端手机录音
前端
齐 飞2 小时前
MongoDB笔记01-概念与安装
前端·数据库·笔记·后端·mongodb