简体中文

基础配置

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: '文档框架',
    },
  ],
});

head

Type: string | [string, Record<string, string>] | (route) => string | [string, Record<string, string>] | undefined
也可以通过 frontmatter 针对每个页面设置

页面 HTML 的 <head> 标签中呈现的附加元素。

rspress.config.ts

import { defineConfig } from 'rspress/config';

export default defineConfig({
  // ... 其他用户配置
  head: [
    '<meta name="author" content="John Doe">',
    // 或者
    ['meta', { name: 'author', content: 'John Doe' }],
    // [htmlTag, { attrName: attrValue, attrName2: attrValue2 }]
    // 或者
    (route) => {
      if (route.routePath.startsWith('/jane/')) return "<meta name='author' content='Jane Doe'>";
      if (route.routePath.startsWith('/john/')) return ['meta', { name: 'author', content: 'John Doe' }];
      \\ or even skip returning anything
      return undefined;
    }
  ]
});

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 | { strict?: boolean }
Default: true

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

rspress.config.ts

import { defineConfig } from 'rspress/config';

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

当 SSG 失败时，默认会 fallback 到 CSR。你可以通过设置 ssg 为 { strict: true } 来严格要求 SSG 必须成功，否则抛出错误。

rspress.config.ts

export default {
  ssg: {
    strict: true,
  },
};

replaceRules

Type: { search: string | RegExp; replace: string; }[]
Default: []

你可以通过 replaceRules 来对整个站点设置文本替换规则，规则会作用于包括 _meta.json 文件、frontmatter 配置以及文档内容和标题等所有内容。

rspress.config.ts

export default {
  replaceRules: [
    {
      search: /foo/g,
      replace: 'bar',
    },
  ],
};

基础配置#

root#

base#

title#

description#

icon#

logo#

logoText#

outDir#

locales#

head#

mediumZoom#

search#

searchHooks#

versioned#

globalUIComponents#

multiVersion#

route#

route.include#

route.exclude#

route.extensions#

route.cleanUrls#

ssg#

replaceRules#

基础配置

root

base

title

description

icon

logo

logoText

outDir

locales

head

mediumZoom

search

searchHooks

versioned

globalUIComponents

multiVersion

route

route.include

route.exclude

route.extensions

route.cleanUrls

ssg

replaceRules