> For AI agents: the complete documentation index is available at https://rspress.rs/zh/llms.txt, the full documentation bundle is available at https://rspress.rs/zh/llms-full.txt.

# 主题配置

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

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

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

## nav

- **类型**：`Array`
- **默认值**： `[]`

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

```ts
interface NavItem {
  // 导航栏文本
  text: string;
  // 导航栏链接
  link: '/';
  // 是否为下载链接
  download?: boolean;
  // 导航栏链接的激活规则
  activeMatch: '^/$|^/';
  // 显示在导航栏文本之前的图标
  icon?: string;
  // 显示在导航栏文本之后的标签
  tag?: string;
}
```

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

使用本地图标时，应将图片放在 `public` 目录中，并通过 `/icon.png` 这样的绝对路径引用。此外还支持内联 SVG 字符串、emoji、外链和 data URL。

比如:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

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

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

```ts
interface NavGroup {
  // 导航栏文本
  text: string;
  // 子菜单
  items: NavItem[];
  // 显示在导航栏文本之前的图标
  icon?: string;
  // 显示在导航栏文本之后的标签
  tag?: string;
}
```

例如下面的配置:

```ts title="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',
          },
        ],
      },
    ],
  },
});
```

## sidebar

- **类型**：`Object`

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

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

interface SidebarGroup {
  text: string;
  link?: string;
  items: SidebarItem[];
  // 是否可折叠
  collapsible?: boolean;
  // 是否默认折叠
  collapsed?: boolean;
  // 显示在侧边栏文本之前的图标
  icon?: string;
  // 显示在侧边栏文本之后的标签
  tag?: string;
}

type SidebarItem = {
  // 侧边栏文本
  text: string;
  // 侧边栏链接
  link: string;
  // 显示在侧边栏文本之前的图标
  icon?: string;
  // 显示在侧边栏文本之后的标签
  tag?: string;
};
```

比如:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    sidebar: {
      '/guide/': [
        {
          text: 'Getting Started',
          icon: '/icon.png',
          items: [
            {
              text: 'Introduction',
              link: '/guide/getting-started/introduction',
              icon: '<svg>...</svg>',
              tag: 'new',
            },
            {
              text: 'Installation',
              link: '/guide/getting-started/installation',
            },
          ],
        },
        {
          text: 'Advanced',
          items: [
            {
              text: 'Customization',
              link: '/guide/advanced/customization',
            },
            {
              text: 'Markdown',
              link: '/guide/advanced/markdown',
            },
          ],
        },
      ],
    },
  },
});
```

## footer

- **类型**：`Object`
- **默认值**： `{}`

主页的页脚。

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

```ts
export interface Footer {
  message?: string;
}
```

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

比如：

```ts title="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 提交中读取该时间。

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

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

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

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

```ts title="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`，相关例子如下：

```ts title="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 属性来选择：

```ts
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 的值为自定义图标内容即可，比如：

```js
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`

下一页的文本。比如:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

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

## locales

- **类型**：`Array<LocaleConfig>`
- **默认值**： `undefined`

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

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

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

## darkMode

- **类型**：`boolean | 'dark' | 'light' | 'auto' | 'force-light' | 'force-dark' | 'force-auto'`
- **默认值**： `true`

暗黑模式启用时，Rspress 会在 `<html>` 元素上添加 `dark` class。你可以使用 `html.dark` 选择器来自定义暗黑模式样式：

```css
html.dark .custom-content {
  color: white;
}
```

配置暗黑模式/白天模式的行为：

- `true`：行为和 `'auto'` 一致。
- `false`：行为和 `'force-light'` 一致。
- `'light'`：显示切换按钮，当用户没有保存过偏好时默认使用浅色模式。
- `'dark'`：显示切换按钮，当用户没有保存过偏好时默认使用暗黑模式。
- `'auto'`：显示切换按钮，当用户没有保存过偏好时默认跟随系统偏好。
- `'force-light'`：始终使用浅色模式，并隐藏切换按钮。
- `'force-dark'`：始终使用暗黑模式，并隐藏切换按钮。
- `'force-auto'`：始终跟随系统偏好，并隐藏切换按钮。

比如，始终使用暗黑模式，并隐藏切换按钮：

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  themeConfig: {
    darkMode: 'force-dark',
  },
});
```

## editLink

- **类型**：

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

- **默认值**： `undefined`

用于配置编辑链接，以在 GitHub 或 GitLab 等 Git 管理服务上编辑页面。该链接会同时显示在文档底部和右侧大纲面板中。

比如：

```ts title="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](https://developer.mozilla.org/docs/Web/API/View_Transitions_API) 实现。例如：

> 转场动画暂时不能配置。

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

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

## enableAppearanceAnimation

- **类型**：`boolean`
- **默认值**： `false`

在浅色和深色主题之间切换时是否有动画效果，使用 [View Transition API](https://developer.mozilla.org/docs/Web/API/View_Transitions_API) 实现。例如：

> 切换动画暂时不能配置。

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

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

## search

- **类型**：`boolean`
- **默认值**： `true`

是否显示搜索框。比如：

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

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

## enableScrollToTop

- **类型**：`boolean`
- **默认值**： `true`

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

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

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

## ~~localeRedirect~~

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

控制如何根据 `window.navigator.language` 将首次访问的用户重定向到最匹配的已配置语言。

:::warning 配置已迁移

该选项已迁移至 [`route.localeRedirect`](https://rspress.rs/zh/api/config/config-basic.md#routelocaleredirect)。`themeConfig.localeRedirect` 仍会继续生效以保持向后兼容，但已废弃。请将该选项迁移至 `route`；同时配置两者时，`route.localeRedirect` 优先生效。

:::

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

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

## fallbackHeadingTitle

- **类型**：`boolean`
- **默认值**： `true`

是否在文档不书写 H1 时将 [`frontmatter.title`](https://rspress.rs/zh/api/config/config-frontmatter.md#title) 作为后备内容。比如:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

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

```mdx
---
title: 文档标题
---

## 正文内容
```

## llmsUI

- **类型**：

```ts
type LlmsUI =
  | boolean
  | {
      injectLlmsHint?: boolean;
      viewOptions?: false | Array<'markdownLink' | 'chatgpt' | 'claude'>;
      placement?: 'title' | 'outline';
    };
```

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

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

这在使用 [llms](https://rspress.rs/zh/guide/basic/ssg-md.md) 功能生成 llms.txt 文件时非常有用，允许用户轻松复制或在 AI 工具中打开 markdown 内容。

:::warning
ssg-md 仅在构建过程中生效，因此在 `dev` 模式下复制 Markdown 内容无法正常工作。请使用 `rspress build` 构建后，通过 `rspress preview` 进行调试。详见 [dev 和 build 下的区别](https://rspress.rs/zh/guide/basic/ssg.md#dev-%E5%92%8C-build-%E4%B8%8B%E7%9A%84%E5%8C%BA%E5%88%AB)。
:::

示例：

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  llms: true,
  themeConfig: {
    llmsUI: {
      injectLlmsHint: true,
      viewOptions: ['markdownLink', 'chatgpt', 'claude'],
      placement: 'outline',
    },
  },
});
```

### injectLlmsHint


[新增于 v2.0.18](https://github.com/web-infra-dev/rspress/releases/tag/v2.0.18)

- **类型**：`boolean`
- **默认值**：`true`

此选项用于控制是否在生成的页面中注入面向 LLM 的 directive hint。同一个 `LlmsHint` 组件有两种输出形态：

- 在 SSG HTML 输出中，它会在页面顶部附近渲染一个 visually hidden 的纯文本 DOM 元素。它不会使用 `display: none`、`hidden` 属性、`aria-hidden` 或嵌套链接，这样 agent 在进行 HTML 到 Markdown 转换时可以将该 directive 保留为文本。
- 在 SSG-MD Markdown 输出中，它会在 Markdown 页面顶部附近渲染为 blockquote 字符串。

假设 [`siteOrigin`](https://rspress.rs/zh/api/config/config-basic.md#siteorigin) 是 `https://example.com`，会在 `/guide/` 页面中注入以下 HTML directive：


```html
<div class="rp-llms-hint" style="position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);clip-path:inset(50%);white-space:nowrap;border:0">For AI agents: the complete documentation index is available at https://example.com/llms.txt, the full documentation bundle is available at https://example.com/llms-full.txt, and this page is available as Markdown at https://example.com/guide/index.md.</div>
```

同一页面的 SSG-MD Markdown 输出会以以下内容开头：

```md
> For AI agents: the complete documentation index is available at https://example.com/llms.txt, the full documentation bundle is available at https://example.com/llms-full.txt.
```

其中的 URL 会自动包含配置的 `siteOrigin`、[`base`](https://rspress.rs/zh/api/config/config-basic.md#base)、语言和版本前缀。未配置 `siteOrigin` 时，则保留带 `base` 前缀的路径。

将 `injectLlmsHint` 设置为 `false`，可以禁用这一行为：

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  llms: true,
  themeConfig: {
    llmsUI: {
      injectLlmsHint: false,
    },
  },
});
```

### viewOptions

- **类型**：`false | Array<'markdownLink' | 'chatgpt' | 'claude'>`
- **默认值**：`['markdownLink', 'chatgpt', 'claude']`

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

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

将 `viewOptions` 设置为 `false` 或 `[]` 可以隐藏 view options UI。

### placement

- **类型**：`'title' | 'outline'`
- **默认值**：`'title'`

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

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

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

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