This div is used to preload the font
指南
插件
API
指南
插件
API
简体中文

基础配置

root

  • Type: string
  • Default: docs

指定文档根目录。比如：

rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  root: 'docs',
});

该配置同时支持相对路径和绝对路径，相对路径相对于当前工作目录。

当然，除了通过配置文件来指定文档根目录，你也可以通过命令行参数来指定，比如：

rspress dev docs
rspress build docs

base

  • Type: string
  • Default: /

部署基础路径。比如，如果你计划将你的站点部署到 https://foo.github.io/bar/，那么你应该将 base 设置为 "/bar/"：

rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  base: '/bar/',
});

title

  • Type: string
  • Default: "Rspress"

站点标题。这个参数将被用作 HTML 页面的标题。例如：

rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  title: '我的站点',
});

description

  • Type: string
  • Default: ""

站点描述。这将用作 HTML 页面的描述。例如：

rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  description: '我的站点描述',
});

icon

  • Type: string
  • Default: ""

站点图标。这个路径将用作 HTML 页面的图标路径。例如：

rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  icon: '/favicon.ico',
});

框架会在 public 目录中找到你的图标，当然你也可以设置成一个 CDN 地址。

logo

  • Type: string | { dark: string; light: string }
  • Default: ""

站点 logo。这个路径将用作导航栏左上角的 logo 路径。例如：

rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  logo: '/logo.png',
});

框架会在 public 目录中找到你的图标，当然你也可以设置成一个 CDN 地址。

当然你可以针对浅色/暗黑模式设置不同的 logo：

rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  logo: {
    dark: '/logo-dark.png',
    light: '/logo-light.png',
  },
});

logoText

  • Type: string
  • Default: ""

站点 logo 文字。这个文字将用作导航栏左上角的 logo 文字。例如：

rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  logoText: 'rspress',
});

outDir

  • Type: string
  • Default: doc_build

自定义构建站点的输出目录。比如:

rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  outDir: 'doc_build',
});

locales

  • Type: Locale[]
export interface Locale {
  lang: string;
  label: string;
  title?: string;
  description?: string;
}

站点的多语言配置。比如：

rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  locales: [
    {
      lang: 'en-US',
      label: 'English',
      title: 'Doc Tools',
      description: 'Doc Tools',
    },
    {
      lang: 'zh-CN',
      label: '简体中文',
      title: '文档框架',
      description: '文档框架',
    },
  ],
});

mediumZoom

  • Type: boolean | { selector?: string }
  • Default: true

是否开启图片放大功能。默认开启，你可以通过设置 mediumZoom 为 false 来关闭。

底层使用的是 medium-zoom 库来实现的。

使用示例：

rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  // 关闭图片放大功能
  mediumZoom: false,
  // 配置 CSS 选择器，自定义要放大的图片，默认为 '.rspress-doc img'
  mediumZoom: {
    selector: '.rspress-doc img',
  },
});

search

  • Type: { searchHooks: string; versioned: boolean; }

searchHooks

你可以通过 searchHooks 参数来增加搜索运行时钩子逻辑，比如：

rspress.config.ts
import { defineConfig } from 'rspress/config';
import path from 'path';

export default defineConfig({
  search: {
    searchHooks: path.join(__dirname, 'searchHooks.ts'),
  },
});

关于具体的钩子逻辑，你可以阅读 自定义搜索功能。

versioned

如果你配置了 multiVersion，可以使用 versioned 参数为文档的每个版本创建单独的搜索索引。开启该选项后，搜索将仅会查询当前所选版本对应的索引。

rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  search: {
    versioned: true,
  },
});

globalUIComponents

  • Type: (string | object)[]
  • Default: []

你可以通过 globalUIComponents 参数来增加全局 UI 组件，比如：

rspress.config.ts
import { defineConfig } from 'rspress/config';
import path from 'path';

export default defineConfig({
  globalUIComponents: [path.join(__dirname, 'components', 'MyComponent.tsx')],
});

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

rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  globalUIComponents: [
    [
      path.join(__dirname, 'components', 'MyComponent.tsx'),
      {
        foo: 'bar',
      },
    ],
  ],
});

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

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

compUi.tsx
import React from 'react';

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

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

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

compSideEffect.tsx
import { useEffect } from 'react';
import { useLocation } from 'rspress/runtime';

// 需要默认导出一个组件
export default function PluginSideEffect() {
  const { pathname } = useLocation();
  useEffect(() => {
    // 组件初次渲染时执行
  }, []);

  useEffect(() => {
    // 路由变化时执行
  }, [pathname]);
  return null;
}

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

  • 针对某些页面路由进行重定向操作。

  • 对页面的 img 标签进行事件监听，实现图片放大功能。

  • 路由变化时，上报不同页面的 PV 数据。

  • ......

multiVersion

  • Type: { default: string; versions: string[] }

你可以通过 multiVersion 参数来增加多版本文档支持，比如：

rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  multiVersion: {
    default: 'v1',
    versions: ['v1', 'v2'],
  },
});

其中，default 为默认版本，versions 为所有版本列表。

route

  • Type: Object

自定义路由配置。

route.include

  • Type: string[]
  • Default: []

在路由中添加一些额外的文件。默认情况下，只有文档根目录中的文件才会包含在路由中。如果你想在路由中添加一些额外的文件，你可以使用这个选项。例如：

rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  route: {
    include: ['other-dir/**/*.{md,mdx}'],
  },
});

注意：数组中的字符串支持 glob 模式，填写的 glob 表达式应基于文档的 root 目录，并带上对应的 extensions 后缀。

NOTE

我们更加推荐在自定义 Rspress 插件中使用 addPages hook 来在路由中添加一些额外的文件，这样可以更灵活且更合理地指定页面路由和文件路径/内容。

route.exclude

  • Type: string[]
  • Default: []

从路由中排除一些文件。例如：

rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  route: {
    exclude: ['custom.tsx', 'component/**/*'],
  },
});

注意：数组中的字符串支持 glob 模式，填写的 glob 表达式应基于文档的 root 目录。

route.extensions

  • Type: string[]
  • Default: []

将包含在路由中的文件的扩展名。默认情况下，Rspress 会在路由中包含所有 `'js'、'jsx'、'ts'、'tsx'、'md'、'mdx' 文件。如果你想自定义扩展名，你可以使用这个选项。例如：

rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  route: {
    extensions: ['.jsx', '.md', '.mdx'],
  },
});

route.cleanUrls

  • Type: boolean
  • Default: false

开启后可以生成无 .html 后缀的链接，URL 可以更加简洁。

rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  route: {
    cleanUrls: true,
  },
});

ssg

  • Type: boolean
  • Default: true

是否开启静态站点生成。默认开启，你可以通过设置 ssg 为 false 来关闭。

rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  ssg: false,
});