从0到1搭建react组件库-文档篇一个优秀的文档是一个开源库中很重要的一环，这一篇使用了rspress配置组件库文档，

前言

历史文章链接：

环境配置

rspress作为一个基于rsbuild的静态站点生成器，它的构建性能非常好，并且支持MDX（可以在MDX中引用react组件渲染），并且包含所有的文档站基础功能（国际化、多版本支持、全文搜索等），并且内置插件系统，可以根据需求拓展功能。（如果文章中有错误内容，欢迎大家交流指正。）

rspress项目配置

进入apps/website/目录下，运行npm init -y.
然后在devDependencies字段中添加rspress以及typescript相关依赖，并且修改包的名称。

// apps/website/package.json
{
  "name": "@mini-ui/website",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
  },
  "devDependencies": {
    "rspress": "1.30.0",
    "typescript": "5.6.2",
    "ts-node": "10.9.2"
  }
}

命令行进入apps/website目录下的中运行pnpm i，下载安装rspress及typescript相关的依赖。
在apps/website目录下新建一个ts.config.json文件，用来配置typescript的基本内容（ts继承于根目录tsconfig, 然后根据官网信息加入ts的额外配置即可）。

//apps/website/tsconfig.json
{
  "extends": ["../../tsconfig.json"],
  "include": ["docs", "theme", "rspress.config.ts"],
  "mdx": {
    "checkMdx": true
  }
}

在apps/website目录下新建一个rspress.config.ts，然后按照官网配置即可，具体配置信息见rspress基础配置。

// /apps/website/rspress.config.ts
import { defineConfig } from "rspress/config";

export default defineConfig({
  root: "docs",
  title: "mini-ui",
})

apps/website目录下的package.json中追加启动命令，如下。

// apps/website/package.json
{
  "name": "@mini-ui/website",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "dev": "rspress dev",
    "build": "rspress build",
    "preview": "rspress preview"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "rspress": "1.30.0",
    "typescript": "5.6.2",
    "ts-node": "10.9.2"
  }
}

至此，rspress的基本配置已经完成。接下来就是去了解rspress的约定式路由的相关概念，然后如何通过_meta.json创建文档的nav导航栏、sidebar侧边栏主体展示的文档内容了。

rspress基础概念

约定式路由

约定式路由的概念其实很常见，也可以将其称之为文件路由，框架会去读取约定的文件夹下的文件的文件路径，然后通过文件路径解析出路由配置，这样的做法可以让整个项目的路由非常直观，不用打开路由配置文件查找路由信息。

官方例子如下：

docs
├── foo
│   └── bar.md
└── foo.md

具体映射规则如下：

文件路径	路由路径
`index.md`	`/`
`/foo.md`	`/foo`
`/foo/bar.md`	`/foo/bar`
`/zoo/index.md`	`/zoo/`

自动化导航栏/侧边栏

Rspress中，有两种实现导航栏和侧边栏的声明。

在配置文件中通过ThemeConfig字段中声明nav和siderbar来实现导航栏和侧边栏的内容。
通过在目录下创建_meta.json来自动化生成导航栏和侧边栏。

在这里我们选择第二种方式，即通过_meta.json描述文件，来声明导航栏和侧边栏的信息。其中_meta.json在项目中声明的位置不同，也代表着不同的级别。

在文档根目录(/apps/website/docs下，或者配置文件中root字段的目录下)的_meta.json将会被解析成为导航栏。
在根目录中的子目录中，生成的则是侧边栏级别。

开发

配置首页面

这里配置比较简陋，仅包含标题、子标题、还有两个按钮内容。

// apps/website/index.md
---
pageType: home

hero:
  name: mini-ui
  actions:
    - theme: brand
      text: 快速开始
      link: /guide/basic/
    - theme: alt
      text: Github
      link: https://github.com/frontendley/mini-ui
---

配置导航栏

导航栏就是顶部的主要内容。（这里的title是在rspress.config.ts中配置），主要是配置了一个Guide按钮，以及右侧的github地址。

注意导航栏的配置是在根目录中。

// apps/website/docs/_meta.json
[
  {
    "text": "Guide",  // 显示的文本
    "link": "/guides/start",   // 跳转的链接
    "activeMatch": "^/guides/", // 路由匹配正则，若匹配会高亮
    "position": "left"   // 位置 左边还是右边
  },
  {
    "text": "Github",
    "link": "https://github.com/frontendley/mini-ui",
    "activeMatch": "",
    "position": "right"
  }
]

配置侧边栏

侧边栏的内容，在根目录的子目录下进行配置。

// /apps/website/docs/guide/_meta.json
[
  {
    "type": "dir",     // 文件/目录/链接， 若为目录，则有子菜单，若为文件，则点击即可跳转。
    "name": "basic",   // 文件名/目录名
    "label": "基础指南" // 展示在页面中的内容。
  },
  {
    "type": "dir",
    "name": "components",
    "label": "组件"
  }
]

配置侧边栏中的嵌套路由

快速开始

创建basic目录，然后在basic目录下创建_meta.json以及index.mdx，分别用来配置子菜单，以及点击子菜单后显示的内容。

_meta.json

// apps/website/docs/guide/basic/_meta.json
[
  {
    "type": "file",
    "label": "快速开始",
    "name": "index"
  }
]

index.mdx

// apps/website/docs/guide/basic/index.mdx
# 快速开始
## 通过本教程快速开始使用mini-ui

组件/按钮组件配置

创建components目录，以后的组件主要展示在这个目录下。先创建一个button.mdx文件，然后在_meta.json中声明这个菜单项。

button.mdx

// apps/website/docs/components/button.mdx
# 按钮组件

_meta.json

// apps/website/docs/components/_meta.json
[  {    "type": "file",    "label": "按钮",    "name": "button"  }]

Demo项目配置

参照开发方案篇中的对mini-ui的react下载配置，以及如何在测试项目中声明下载组件库的内容。配置下react以及ts，和mini-ui的依赖即可。

button组件Demo

在demo目录中新增一个button文件夹，然后新建一个basic-button.tsx文件，用来调用@mini-ui中的button组件，然后在文档中引用展示。

// /apps/demo/button/basic-button.tsx
import {Button} from "@mini-ui/ui";

export default function App () {
  return (
    <Button></Button>
  )
}

在apps/website/docs/guide/button.mdx中，增加内容, 引用demo下的basic-button进行展示。

# 按钮组件

<code src="../../../../demo/button/basic-button.tsx" />

5. 刷新页面后，发现不能展示引用的button组件，是因为rspress需要预览插件，才能在页面中渲染组件内容。安装@rspress/plugin-preview插件，注意要和rspress版本一致。

// apps/website/package.json
{
  "name": "@mini-ui/website",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "dev": "rspress dev",
    "build": "rspress build",
    "preview": "rspress preview"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "rspress": "1.30.0",
    "typescript": "5.6.2",
    "ts-node": "10.9.2",
    "@rspress/plugin-preview": "1.30.0" // 预览插件
  }
}

接着在website/rspress.config.ts中，配置插件内容。

import { defineConfig } from "rspress/config";
import { pluginPreview } from "@rspress/plugin-preview";

export default defineConfig({
  root: "docs",
  title: "mini-ui",
  plugins: [pluginPreview()],
})

刷新页面。

项目地址

未完待续

后续会开始样式的整体内容设计。（参照arco-desgin的思路。）