主题配置

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

rspress.config.ts

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

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

nav

类型：Array
默认值： []

网站的导航栏。 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',
          },
        ],
      },
    ],
  },
});

类型：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',
          ],
        },
      ],
    },
  },
});

类型：Object
默认值： {}

主页的页脚。

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>',
    },
  },
});

socialLinks

类型：Array
默认值： []

你可以通过如下的配置添加相关链接，比如 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

类型：string
默认值： Next Page

下一页的文本。比如:

rspress.config.ts

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

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

locales

类型：Array<LocaleConfig>
默认值： undefined

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

export interface LocaleConfig {
  /**
   * 通用站点信息，优先级高于 `locales` 中的配置
   */
  // 语言名称
  lang?: string;
  // HTML 标题，优先于 `themeConfig.title`
  title?: string;
  // HTML 描述，优先于 `themeConfig.description`
  description?: string;
  // 对应语言的显示文本
  label: string;
}

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

darkMode

类型：boolean
默认值： 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;
}

默认值： 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',
    },
  },
});

enableContentAnimation

类型：boolean
默认值： false

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

转场动画暂时不能配置。

rspress.config.ts

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

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

enableAppearanceAnimation

类型：boolean
默认值： false

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

切换动画暂时不能配置。

rspress.config.ts

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

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

search

类型：boolean
默认值： true

是否显示搜索框。比如：

rspress.config.ts

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

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

enableScrollToTop

类型：boolean
默认值： false

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

rspress.config.ts

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

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

localeRedirect

类型：'auto' | 'never' | 'only-default-lang'
默认值： 'auto'

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

rspress.config.ts

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

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

fallbackHeadingTitle

类型：boolean
默认值： true

是否在文档不书写 H1 时将 frontmatter.title 作为后备内容。比如:

rspress.config.ts

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

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

---
title: 文档标题
---

## 正文内容

#主题配置

#nav

#sidebar

#footer

#socialLinks

#nextPageText

#locales

#darkMode

#editLink

#enableContentAnimation

#enableAppearanceAnimation

#search

#enableScrollToTop

#localeRedirect

#fallbackHeadingTitle

#主题配置

#nav

#sidebar

#footer

#socialLinks

#nextPageText

#locales

#darkMode

#editLink

#enableContentAnimation

#enableAppearanceAnimation

#search

#enableScrollToTop

#localeRedirect

#fallbackHeadingTitle

主题配置

nav

sidebar

footer

socialLinks

nextPageText

locales

darkMode

editLink

enableContentAnimation

enableAppearanceAnimation

search

enableScrollToTop

localeRedirect

fallbackHeadingTitle

主题配置

nav

sidebar

footer

socialLinks

nextPageText

locales

darkMode

editLink

enableContentAnimation

enableAppearanceAnimation

search

enableScrollToTop

localeRedirect

fallbackHeadingTitle