五分钟用 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!

相关推荐
kyriewen32 分钟前
编辑弹窗点了取消,列表里的数据怎么还是变了?
前端·javascript·人工智能
Karl_fang1 小时前
🥳 再也不用拿起手机抄验证码!我做了一个 Android → Mac 的「验证码接力」工具
前端·macos·ai编程
谭光志2 小时前
如何让 AI 高效工作
前端·后端·ai编程
FRing033 小时前
vue2干货总结11(短信验证、登录功能、统一处理错误(响应拦截器)、将token信息存入vuex、vuex持久化处理)
开发语言·前端·javascript·vue.js·vue2
泯泷3 小时前
改一个字,整段都红了?——中文内容差异对比的算法与协议设计
前端·javascript·typescript
再吃一根胡萝卜3 小时前
DSH plugin 开发示例:五种插件形态完整代码整理
前端
Yk酱228403 小时前
A2UI随笔-demo-01
前端
云起SAAS3 小时前
本地生活同城多商户商城系统源码源码 合伙人分红加区域代理加排队返现
前端·javascript·后端
奶油话梅糖4 小时前
3 天 1,705 Star:DeepSeek 开源官方聊天前端——零后端纯静态,浏览器直连 API
前端·开源
Linye4 小时前
HTML 流程图连线交叉看不清?聊聊画布避障折线与跳弧实现
前端·人工智能