主题配置

主题配置位于 doc 配置中的 themeConfig 下。例如：

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    // ...
  },
});

nav

Type: Array
Default: []

网站的导航栏。 nav 配置是 NavItem 的数组，具有以下类型：

interface NavItem {
  // 导航栏文本
  text: string;
  // 导航栏链接
  link: '/';
  // 导航栏链接的激活规则
  activeMatch: '^/$|^/';
  // 图标配置(可选)，填入 svg 标签内容或者图片 URL
  tag?: string;
}

activeMatch 用于匹配当前路由，当路由匹配 activeMatch 规则时，nav 项会高亮显示。默认情况下，activeMatch 是 nav 项的 link。

比如:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    nav: [
      {
        text: 'Home',
        link: '/',
      },
      {
        text: 'Guide',
        link: '/guide/',
      },
    ],
  },
});

当然 nav 数组中也可以配置多级菜单，类型如下:

interface NavGroup {
  // 导航栏文本
  text: string;
  // 子菜单
  items: NavItem[];
  // 图标配置(可选)，填入 svg 标签内容或者图片 URL
  tag?: string;
}

例如下面的配置:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    nav: [
      {
        text: 'Home',
        link: '/',
      },
      {
        text: 'Guide',
        items: [
          {
            text: 'Getting Started',
            link: '/guide/getting-started',
          },
          {
            text: 'Advanced',
            link: '/guide/advanced',
          },
        ],
      },
    ],
  },
});

Type: Object

网站的侧边栏。配置为一个对象，类型如下：

// key 为 SidebarGroup 的路径
// value 为 SidebarGroup 的数组
type Sidebar = Record<string, SidebarGroup[]>;

interface SidebarGroup {
  text: string;
  link?: string;
  items: SidebarItem[];
  // 是否可折叠
  collapsible?: boolean;
  // 是否默认折叠
  collapsed?: boolean;
  // 图标配置(可选)，填入 svg 标签内容或者图片 URL
  tag?: string;
}

// 可填入一个对象，也可以填入一个字符串
// 填入字符串时，内部会转换成一个对象，字符串会被当做 link，text 值会自动取对应文档的标题
type SidebarItem =
  | {
      // 侧边栏文本
      text: string;
      // 侧边栏链接
      link: string;
      // 图标配置(可选)，填入 svg 标签内容或者图片 URL
      tag?: string;
    }
  | string;

比如:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    sidebar: {
      '/guide/': [
        {
          text: 'Getting Started',
          items: [
            // 填入一个对象
            {
              text: 'Introduction',
              link: '/guide/getting-started/introduction',
            },
            {
              text: 'Installation',
              link: '/guide/getting-started/installation',
            },
          ],
        },
        {
          text: 'Advanced',
          items: [
            // 直接填入链接字符串
            '/guide/advanced/customization',
            '/guide/advanced/markdown',
          ],
        },
      ],
    },
  },
});

Type: Object
Default: {}

主页的页脚。

footer 配置是 Footer 的一个对象，它具有以下类型：

export interface Footer {
  message?: string;
}

message 是一个可以包含 HTML 内容的字符串。这个字符串将使用 dangerouslySetInnerHTML 插入到页脚中，因此你可以传入 HTML 模板标签来设计你的页脚。

比如：

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    footer: {
      message:
        '<p>这是一个包含<a href="https://example.com">链接</a>的<strong>页脚</strong></p>',
    },
  },
});

outline

Type: boolean
Default: true

是否显示右侧大纲。

比如:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    outline: false,
  },
});

outlineTitle

Type: string
Default: 'ON THIS PAGE'

在右侧边栏中配置大纲的标题。

比如:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    outlineTitle: 'Outline',
  },
});

lastUpdated

Type: boolean
Default: false

是否显示最后更新时间，默认情况下不显示。

Info

你必须提交 markdown 文件才能看到最后更新时间。

比如:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    lastUpdated: true,
  },
});

lastUpdatedText

Type: string
Default: Last Updated

最后更新时间的文本。

比如:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    lastUpdatedText: 'Last Updated',
  },
});

prevPageText

Type: string
Default: Previous Page

上一页的文本。比如:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    prevPageText: 'Previous Page',
  },
});

searchPlaceholderText

Type: string
Default: Search

搜索框的占位符文本。比如:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    searchPlaceholderText: 'Search',
  },
});

searchNoResultsText

Type: string
Default: No results for

没有搜索结果时的显示文本。比如:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    searchNoResultsText: 'No results for',
  },
});

searchSuggestedQueryText

Type: string
Default: Please try again with a different keyword

没有搜索结果时的建议查询提示文本。比如:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    searchSuggestedQueryText: 'Please search again',
  },
});

overview

Type: Object

预览页/组件的配置项。配置为一个对象，类型如下：

interface FilterConfig {
  filterNameText?: string;
  filterPlaceholderText?: string;
  filterNoResultText?: string;
}

For example:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    overview: {
      filterNameText: 'Filter',
      filterPlaceholderText: 'Enter keyword',
      filterNoResultText: 'No matching API found',
    },
  },
});

socialLinks

Type: Array
Default: []

你可以通过如下的配置添加相关链接，比如 github 链接、x 链接等。相关链接支持四种模式：链接模式link 文本模式text 图片模式img 自定义模式dom，相关例子如下：

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    socialLinks: [
      {
        icon: 'github',
        mode: 'link',
        content: 'https://github.com/sanyuan0704/island.js',
      },
      {
        icon: 'wechat',
        mode: 'text',
        content: '微信号 foo',
      },
      {
        icon: 'qq',
        mode: 'img',
        content: '/qrcode.png',
      },
      {
        icon: 'github',
        mode: 'dom',
        content:
          '<img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/rjhwzy/ljhwZthlaukjlkulzlp/rspress/rspress-navbar-logo-0904.png" alt="logo" id="logo" class="mr-4 rspress-logo dark:hidden">',
      },
    ],
  },
});

当link模式时，点击 icon 即可跳转链接。
当text模式时，鼠标移到 icon 上会显示弹框，弹框内容是输入的文本。
当img模式时，鼠标移到 icon 上会显示弹框，弹框内容是指定的图片，需要注意的是，图片需要放在public目录下。
当dom模式时，可以直接在 content 字段中传入需要自定义html。使用''进行包裹。

相关链接支持以下几种图片，通过 icon 属性来选择：

export type SocialLinkIcon =
  | 'lark'
  | 'discord'
  | 'facebook'
  | 'github'
  | 'instagram'
  | 'linkedin'
  | 'slack'
  | 'x'
  | 'youtube'
  | 'wechat'
  | 'qq'
  | 'juejin'
  | 'zhihu'
  | 'bilibili'
  | 'weibo'
  | 'gitlab'
  | 'X'
  | 'bluesky'
  | 'npm'
  | { svg: string };

如果需要自定义 icon，可以通过传入一个带有 svg 属性 的对象，svg 的值为自定义图标内容即可，比如：

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    socialLinks: [
      {
        icon: {
          svg: '<svg>foo</svg>',
        },
        mode: 'link',
        content: 'https://github.com/',
      },
    ],
  },
});

nextPageText

Type: string
Default: Next Page

下一页的文本。比如:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    nextPageText: 'Next Page',
  },
});

locales

Type: Array<LocaleConfig>
Default: undefined

国际化配置。此配置为一个数组，数组中的每一项都是一个 LocaleConfig 对象，它具有以下类型：

export interface LocaleConfig {
  /**
   * 通用站点信息，优先级高于 `locales` 中的配置
   */
  // 语言名称
  lang?: string;
  // HTML 标题，优先于 `themeConfig.title`
  title?: string;
  // HTML 描述，优先于 `themeConfig.description`
  description?: string;
  // 对应语言的显示文本
  label: string;
  /**
   * 主题相关信息
   */
  // 右侧大纲标题
  outlineTitle?: string;
  // 最后更新时间文本
  lastUpdatedText?: string;
  // 是否显示最后更新时间
  lastUpdated?: boolean;
  // 上一页文本
  prevPageText?: string;
  // 下一页文本
  nextPageText?: string;
  // 搜索框占位符文本
  searchPlaceholderText?: string;
  // 没有搜索结果时的显示文本
  searchNoResultsText?: string;
  // 没有搜索结果时的建议查询提示文本
  searchSuggestedQueryText?: string;
  // 配置编辑链接
  editLink?: EditLink;
}

LocaleConfig 中包含许多与主题配置中相同的配置项，但它的优先级会更高。

darkMode

Type: boolean
Default: true

是否出现暗黑模式/白天模式切换按钮。比如：

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    darkMode: true,
  },
});

同时，你也可以通过在 HTML 中注入如下的全局变量来指定默认的主题模式：

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  builderConfig: {
    html: {
      tags: [
        {
          tag: 'script',
          // 通过 window.RSPRESS_THEME 变量来指定默认的主题模式，可选值为 'dark' 和 'light'
          children: "window.RSPRESS_THEME = 'dark';",
        },
      ],
    },
  },
});

editLink

Type:

interface EditLink {
  /**
   * 自定义编辑链接的 URL
   */
  docRepoBaseUrl: string;

  /**
   * 自定义编辑链接的文本
   *
   * @default 'Edit this page'
   */
  text?: string;
}

Default: undefined

用于配置编辑链接，以在 GitHub 或 GitLab 等 Git 管理服务上编辑页面。

比如：

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    editLink: {
      docRepoBaseUrl:
        'https://github.com/web-infra-dev/rspress/tree/main/website/docs',
      text: '📝 在 GitHub 上编辑此页',
    },
  },
});

enableContentAnimation

Type: boolean
Default: false

在页面切换的时候是否显示转场动画，使用 View Transition API 实现。例如：

转场动画暂时不能配置。

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    enableContentAnimation: true,
  },
});

enableAppearanceAnimation

Type: boolean
Default: false

在浅色和深色主题之间切换时是否有动画效果，使用 View Transition API 实现。例如：

切换动画暂时不能配置。

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    enableAppearanceAnimation: true,
  },
});

search

Type: boolean
Default: true

是否显示搜索框。比如：

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    search: false,
  },
});

sourceCodeText

Type: string
Default: Source

源代码按钮的文本。比如：

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    sourceCodeText: 'Source',
  },
});

enableScrollToTop

Type: boolean
Default: false

启用文档上的滚动到顶部按钮. 比如:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    enableScrollToTop: true,
  },
});

localeRedirect

Type: 'auto' | 'never' | 'only-default-lang'
Default: 'auto'

是否在访问网站时重定向到最接近 window.navigator.language 的语言，默认为 auto 表示首次访问时将重定向，never 表示不重定向，only-default-lang 表示仅在访问默认语言时重定向。比如:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    localeRedirect: 'never',
  },
});

fallbackHeadingTitle

Type: boolean
Default: true

是否在文档标题未提供时将 frontmatter.title 作为后备内容。比如:

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    fallbackHeadingTitle: false,
  },
});

#主题配置

#nav

#sidebar

#footer

#outline

#outlineTitle

#lastUpdated

#lastUpdatedText

#prevPageText

#searchPlaceholderText

#searchNoResultsText

#searchSuggestedQueryText

#overview

#socialLinks

#nextPageText

#locales

#darkMode

#editLink

#enableContentAnimation

#enableAppearanceAnimation

#search

#sourceCodeText

#enableScrollToTop

#localeRedirect

#fallbackHeadingTitle

主题配置

nav

sidebar

footer

outline

outlineTitle

lastUpdated

lastUpdatedText

prevPageText

searchPlaceholderText

searchNoResultsText

searchSuggestedQueryText

overview

socialLinks

nextPageText

locales

darkMode

editLink

enableContentAnimation

enableAppearanceAnimation

search

sourceCodeText

enableScrollToTop

localeRedirect

fallbackHeadingTitle