自定义页面

Rspress 提供了多种方式能让你自定义页面的内容，包括：

  • 添加自定义全局组件；
  • 添加自定义全局样式；
  • 自定义页面布局结构。

自定义全局组件

某些场景下，你可能需要在页面中添加一些自定义的全局组件，框架提供了一个配置项 globalUIComponents 来实现这个功能。

使用方法

在 rspress.config.ts 中添加以下配置：

rspress.config.ts

  1. import { defineConfig } from 'rspress/config';
  2. import path from 'path';
  4. export default defineConfig({
  5.   globalUIComponents: [path.join(__dirname, 'components', 'MyComponent.tsx')],
  6. });

globalUIComponents 的每一项可以是一个字符串，代表组件的文件路径；也可以是一个数组，第一项为组件的文件路径，第二项为组件的 props 对象，比如：

rspress.config.ts

  1. import { defineConfig } from 'rspress/config';
  3. export default defineConfig({
  4.   globalUIComponents: [
  5.     [
  6.       path.join(__dirname, 'components', 'MyComponent.tsx'),
  7.       {
  8.         foo: 'bar',
  9.       },
  10.     ],
  11.   ],
  12. });

当你注册了全局组件之后，框架会自动将这些 React 组件在主题中进行渲染，而不用你手动引入。

通过全局组件，你可以完成诸多自定义的功能，比如:

compUi.tsx

  1. import React from 'react';
  3. // 需要默认导出一个组件
  4. // 通过 props 来拿到配置中传入的 props 数据
  5. export default function PluginUI(props?: { foo: string }) {
  6.   return <div>This is a global layout component</div>;
  7. }

这样，在主题页面中会渲染组件的内容，比如添加回到顶部按钮。

同时，你也可以通过全局组件来注册全局副作用。比如：

compSideEffect.tsx

  1. import { useEffect } from 'react';
  2. import { useLocation } from 'rspress/runtime';
  4. // 需要默认导出一个组件
  5. export default function PluginSideEffect() {
  6.   const { pathname } = useLocation();
  7.   useEffect(() => {
  8.     // 组件初次渲染时执行
  9.   }, []);
  11.   useEffect(() => {
  12.     // 路由变化时执行
  13.   }, [pathname]);
  14.   return null;
  15. }

这样，在主题页面中会执行组件的副作用。比如以下的一些需要副作用的场景:

  • 针对某些页面路由进行重定向操作。
  • 对页面的 img 标签进行事件监听，实现图片放大功能。
  • 路由变化时，上报不同页面的 PV 数据。
  • ……

自定义样式

某些场景下，你可能需要在主题 UI 的基础上添加一些全局样式，框架提供了一个配置项 globalStyles 来实现这个功能。

使用方法

在 rspress.config.ts 中添加以下配置：

rspress.config.ts

  1. import { defineConfig } from 'rspress/config';
  2. import path from 'path';
  4. export default defineConfig({
  5.   globalStyles: path.join(__dirname, 'styles/index.css'),
  6. });

然后可以添加以下代码：

  1. /* styles/index.css */
  2. :root {
  3.   --rp-c-brand: #f00;
  4. }

这样框架会自动搜集所有的全局样式并合并到最终的样式文件中。

下面列举一些常用的全局样式：

  1. /* styles/index.css */
  3. :root {
  4.   /* 修改主题色 */
  5.   --rp-c-brand: #f00;
  6.   --rp-c-brand-dark: #ffa500;
  7.   --rp-c-brand-darker: #c26c1d;
  8.   --rp-c-brand-light: #f2a65a;
  9.   --rp-c-brand-lighter: #f2a65a;
  10.   /* 修改左侧侧边栏宽度 */
  11.   --rp-sidebar-width: 280px;
  12.   /* 修改右侧大纲栏宽度 */
  13.   --rp-aside-width: 256px;
  14.   /* 修改代码块标题背景 */
  15.   --rp-code-title-bg: rgba(250, 192, 61, 0.15);
  16.   /* 修改代码块内容背景 */
  17.   --rp-code-block-bg: rgba(214, 188, 70, 0.05);
  18. }

如果想了解更多内部的全局样式，可以查看 vars.css

Tailwind CSS

要在 Rspress 中使用 Tailwind CSS，你可以按照以下步骤操作：

  1. 安装 Tailwind CSS：

npm

yarn

pnpm

bun

  1. npm install tailwindcss -D
  1. 创建一个包含 tailwindcss 插件的 postcss.config.js 文件：

postcss.config.js

  1. module.exports = {
  2.   plugins: {
  3.     tailwindcss: {},
  4.   },
  5. };
  1. 创建一个 tailwind.config.js 文件，并确保 content 包含了所有使用 Tailwind CSS 的文件：

tailwind.config.js

  1. module.exports = {
  2.   content: ['./src/**/*.tsx', './docs/**/*.mdx'],
  3.   theme: {
  4.     extend: {},
  5.   },
  6.   plugins: [],
  7. };
  1. 在你的 CSS 样式文件中添加 Tailwind 指令，参考 自定义样式：

styles/index.css

  1. @import 'tailwindcss/base';
  2. @import 'tailwindcss/components';
  3. @import 'tailwindcss/utilities';

请参考官方 Tailwind CSS 文档 了解最新用法。

自定义布局结构

Rspress 提供了 pageType 配置来让你自定义页面的布局结构。

使用 pageType

Rspress 的约定式路由支持了两种路由，一种是文档路由，即用 md(x) 文件编写的页面，另一种是组件路由，即 .jsx/.tsx 文件编写的页面。

对于前者，你可以在 frontmatter 中添加 pageType 字段来指定页面的布局结构，比如：

foo.mdx

  1. ---
  2. pageType: custom
  3. ---

对于后者，你可以添加如下的导出来指定 pageType：

foo.tsx

  1. // 导出 frontmatter 对象，其含义与 md(x) 文件中的 frontmatter 一致
  2. export const frontmatter = {
  3.   // 声明布局类型
  4.   pageType: 'custom',
  5. };

pageType 可以配置为如下的值：

  • home: 首页，包含顶部导航栏和首页的布局内容。
  • doc: 文档页，包含顶部导航栏、左边侧边栏、正文内容和右侧的大纲栏。
  • custom: 自定义页面，包含顶部导航栏和自定义的内容。
  • blank: 也属于自定义页面，但是不包含顶部导航栏。
  • 404: 404 页面。

使用细粒度开关

除了 pageType 页面布局级别的配置之外，Rspress 还提供了更细粒度的开关，你可以在 frontmatter 配置其它的字段，这些字段及其含义如下：

  • navbar：是否展示顶部导航栏，当你想要隐藏顶部导航栏时，可以配置为 false；
  • sidebar：是否展示侧边栏，当你想要隐藏侧边栏时，可以配置为 false；
  • outline：是否展示大纲栏，当你想要隐藏大纲栏时，可以配置为 false；
  • footer：是否展示页脚，当你想要隐藏页脚时，可以配置为 false；
  • globalComponents: 是否展示全局组件，当你想要隐藏全局组件时，可以配置为 false。

示例：

foo.mdx

  1. ---
  2. navbar: false
  3. sidebar: false
  4. outline: false
  5. footer: false
  6. globalUIComponents: false
  7. ---

使用 URL 参数开关

除此之外，你还可以使用 URL 参数在运行时控制页面的布局结构，比如：

  1. # 隐藏导航栏和右侧大纲栏
  2. http://YOUR_DOMAIN/foo?navbar=0&outline=0

通过 URL 参数，你可以在不修改源码的情况下，快速地调整页面的布局结构，这些参数具体包括：

  • navbar：是否展示导航栏，当你想要隐藏顶部导航栏时，可以配置为 0；
  • sidebar：是否展示侧边栏，当你想要隐藏侧边栏时，可以配置为 0；
  • outline：是否展示大纲栏，当你想要隐藏大纲栏时，可以配置为 0；
  • footer：是否展示页脚，当你想要隐藏页脚时，可以配置为 0；
  • globalUIComponents：是否展示全局组件，当你想要隐藏全局组件时，可以配置为 0。

自定义标签

自定义 head 标签

在 rspress.config.ts 中，你可以为所有页面设置 HTML 的 metadata（即 head 标签）。我们在 基础配置 - head 中详细解释了这一点。

生成 metadata 标签

在 frontmatter 中，你还可以自定义页面的 metadata 标签以进行 SEO 优化。

例如，如果你想在 <head> 标签中添加 <meta name="description" content="This is description">，你可以这样使用 frontmatter：

example.mdx

  1. ---
  2. title: This is title
  3. description: This is description
  4. ---

更多关于如何自定义 open graph 图像（og:image） 和 open graph 标题（og:title） 的详细信息可以在 frontmatter 配置 中查看。