主题配置

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

rspress.config.ts

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

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

nav

类型：Array
默认值： []

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

interface NavItem {
  // 导航栏文本
  text: string;
  // 导航栏链接
  link: '/';
  // 是否为下载链接
  download?: boolean;
  // 导航栏链接的激活规则
  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;
}

type SidebarItem = {
  // 侧边栏文本
  text: string;
  // 侧边栏链接
  link: string;
  // 图标配置(可选)，填入 svg 标签内容或者图片 URL
  tag?: 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: [
            {
              text: 'Customization',
              link: '/guide/advanced/customization',
            },
            {
              text: 'Markdown',
              link: '/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>',
    },
  },
});

lastUpdated

类型：boolean | { author?: boolean | ((info: { name: string; email: string; filePath: string }) => string) }
默认值： false

是否展示每个文档页面的最后更新时间。Rspress 会从文件最新一次 Git 提交中读取该时间。

rspress.config.ts

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

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

在 CI 中部署时，请确保可以访问完整的 Git 历史。例如在 GitHub Actions 中为 actions/checkout 配置 fetch-depth: 0。

设置 author 可以同时展示最后一次提交的作者，也可以传入函数来自定义展示的作者文本。

rspress.config.ts

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

export default defineConfig({
  themeConfig: {
    lastUpdated: {
      author: ({ name, email }) => `${name} <${email}>`,
    },
  },
});

socialLinks

类型：Array
默认值： []

你可以通过如下的配置添加相关链接，比如 github 链接、x 链接等。相关链接支持五种模式：link text img dom github-stars，相关例子如下：

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">',
      },
      {
        icon: 'github',
        mode: 'github-stars',
        content: 'https://github.com/web-infra-dev/rspress',
      },
    ],
  },
});

当link模式时，点击 icon 即可跳转链接。
当text模式时，鼠标移到 icon 上会显示弹框，弹框内容是输入的文本。
当img模式时，鼠标移到 icon 上会显示弹框，弹框内容是指定的图片，需要注意的是，图片需要放在public目录下。
当dom模式时，可以直接在 content 字段中传入需要自定义html。使用''进行包裹。
当github-stars模式时，content 应为 GitHub 仓库 URL。组件会通过 GitHub REST API 拉取仓库的 star 数并显示在 icon 旁边，结果会缓存在 localStorage 中 1 小时以避免触发 API 频率限制。请求失败时（离线、被限流或私有仓库）会自动回退为普通链接。

相关链接支持以下几种图片，通过 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

类型：

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
默认值： true

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

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: 文档标题
---

## 正文内容

llmsUI

类型：

type LlmsUI =
  | boolean
  | {
      viewOptions?: Array<
        | 'markdownLink'
        | 'chatgpt'
        | 'claude'
        | { title: string; icon?: React.ReactNode; onClick?: () => void }
        | { title: string; href: string; icon?: React.ReactNode }
      >;
      placement?: 'title' | 'outline';
    };

默认值：false（当配置 llms: true 时自动设置为 true）

LLMS UI 组件配置。启用后，会自动在所有 H1 标题下方（默认）或右侧大纲面板中添加 LlmsCopyButton 和 LlmsViewOptions 组件。

这在使用 llms 功能生成 llms.txt 文件时非常有用，允许用户轻松复制或在 AI 工具中打开 markdown 内容。

Warning

ssg-md 仅在构建过程中生效，因此在 dev 模式下复制 Markdown 内容无法正常工作。请使用 rspress build 构建后，通过 rspress preview 进行调试。详见 dev 和 build 下的区别。

示例：

rspress.config.ts

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

export default defineConfig({
  llms: true, // 这将自动启用 llmsUI
  themeConfig: {
    // 当 llms: true 时，llmsUI 会自动设置为 true
    // 你也可以显式配置：
    llmsUI: true,
    // 或者使用自定义选项：
    // llmsUI: {
    //   viewOptions: ['markdownLink', 'chatgpt', 'claude'],
    //   placement: 'outline',
    // },
  },
});

viewOptions

类型：Array<'markdownLink' | 'chatgpt' | 'claude' | CustomOption>
默认值：['markdownLink', 'chatgpt', 'claude']

LlmsViewOptions 下拉菜单的选项。内置选项包括：

'markdownLink': 复制 markdown 文件链接
'chatgpt': 在 ChatGPT 中打开
'claude': 在 Claude 中打开

你也可以提供自定义选项，包含 title、href 或 onClick，以及可选的 icon。

placement

类型：'title' | 'outline'
默认值：'title'

控制 LLMS UI 组件的显示位置。

'title'：在 H1 标题下方以按钮形式显示（默认行为）
'outline'：在右侧大纲面板中以独立行形式显示

rspress.config.ts

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

export default defineConfig({
  llms: true,
  themeConfig: {
    llmsUI: {
      placement: 'outline',
    },
  },
});

#主题配置

#nav

#sidebar

#footer

#lastUpdated

#socialLinks

#nextPageText

#locales

#darkMode

#editLink

#enableContentAnimation

#enableAppearanceAnimation

#search

#enableScrollToTop

#localeRedirect

#fallbackHeadingTitle

#llmsUI

#viewOptions

#placement

主题配置

nav

sidebar

footer

lastUpdated

socialLinks

nextPageText

locales

darkMode

editLink

enableContentAnimation

enableAppearanceAnimation

search

enableScrollToTop

localeRedirect

fallbackHeadingTitle

llmsUI

viewOptions

placement