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

相关推荐
Smile_Gently2 小时前
前端:最简单封装nmp插件(组件)过程。
前端·javascript·vue.js·elementui·vue
luckycoke8 小时前
小程序立体轮播
前端·css·小程序
一 乐8 小时前
高校体育场管理系统系统|体育场管理系统小程序设计与实现(源码+数据库+文档)
前端·javascript·数据库·spring boot·高校体育馆系统
懒羊羊我小弟8 小时前
常用Webpack Loader汇总介绍
前端·webpack·node.js
祈澈菇凉9 小时前
ES6模块的异步加载是如何实现的?
前端·javascript·es6
我爱学习_zwj9 小时前
4.从零开始学会Vue--{{组件通信}}
前端·javascript·vue.js·笔记·前端框架
顾比魁9 小时前
XSS盲打:当攻击者“盲狙”管理员
前端·网络安全·xss
黑客老李9 小时前
新手小白如何挖掘cnvd通用漏洞之存储xss漏洞(利用xss钓鱼)
java·运维·服务器·前端·xss
晚风予星9 小时前
简记|LogicFlow自定义BPMN元素节点
前端
Json____10 小时前
使用html css js 开发一个 教育机构前端静态网站模板
前端·css·html·js·前端学习·企业站·教育机构网站