主题配置

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

rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  themeConfig: {
    // ...
  },
});
  • 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/config';

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/config';

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/config';

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;
}

比如:

rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  themeConfig: {
    footer: {
      message: 'This is a footer',
    },
  },
});

outlineTitle

  • Type: string
  • Default: 'ON THIS PAGE'

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

比如:

rspress.config.ts
import { defineConfig } from 'rspress/config';

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

lastUpdated

  • Type: boolean
  • Default: false

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

比如:

rspress.config.ts
import { defineConfig } from 'rspress/config';

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

lastUpdatedText

  • Type: string
  • Default: Last Updated

最后更新时间的文本。

比如:

rspress.config.ts
import { defineConfig } from 'rspress/config';

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

prevPageText

  • Type: string
  • Default: Previous Page

上一页的文本。比如:

rspress.config.ts
import { defineConfig } from 'rspress/config';

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

searchPlaceholderText

  • Type: string
  • Default: Search Docs

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

rspress.config.ts
import { defineConfig } from 'rspress/config';

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

searchNoResultsText

  • Type: string
  • Default: No results for

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

rspress.config.ts
import { defineConfig } from 'rspress/config';

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/config';

export default defineConfig({
  themeConfig: {
    searchSuggestedQueryText: 'Please search again',
  },
});
  • Type: Array
  • Default: []

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

rspress.config.ts
import { defineConfig } from 'rspress/config';

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'
  | 'twitter'
  | 'youtube'
  | 'wechat'
  | 'qq'
  | 'juejin'
  | 'zhihu'
  | 'bilibili'
  | 'weibo'
  | 'gitlab'
  | 'X'
  | { svg: string };

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

import { defineConfig } from 'rspress/config';

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/config';

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;
  // 是否显示右侧大纲
  outline?: boolean;
  // 最后更新时间文本
  lastUpdatedText?: string;
  // 是否显示最后更新时间
  lastUpdated?: boolean;
  // 上一页文本
  prevPageText?: string;
  // 下一页文本
  nextPageText?: string;
  // 搜索框占位符文本
  searchPlaceholderText?: string;
  // 没有搜索结果时的显示文本
  searchNoResultsText?: string;
  // 没有搜索结果时的建议查询提示文本
  searchSuggestedQueryText?: string;
}

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

darkMode

  • Type: boolean
  • Default: true

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

rspress.config.ts
import { defineConfig } from 'rspress/config';

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

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

rspress.config.ts
import { defineConfig } from 'rspress/config';

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

hideNavbar

  • Type: "always" | "auto" | "never"
  • Default: never

控制隐藏导航栏行为。默认情况下,导航栏总是显示。你可以设置为 auto 来实现页面向下滚动时导航栏自动隐藏,或者设置为 always 来总是隐藏导航栏

。比如:

rspress.config.ts
import { defineConfig } from 'rspress/config';

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

enableContentAnimation

  • Type: boolean
  • Default: false

在页面切换的时候是否显示转场动画,例如:

转场动画暂时不能配置。

rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  themeConfig: {
    enableContentAnimation: true,
  },
});
  • Type: boolean
  • Default: true

是否显示搜索框。比如:

rspress.config.ts
import { defineConfig } from 'rspress/config';

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

sourceCodeText

  • Type: string
  • Default: Source

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

rspress.config.ts
import { defineConfig } from 'rspress/config';

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

enableScrollToTop

  • Type: boolean
  • Default: false

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

rspress.config.ts
import { defineConfig } from 'rspress/config';

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

localeRedirect

  • Type: 'auto' | 'never'
  • Default: 'auto'

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

rspress.config.ts
import { defineConfig } from 'rspress/config';

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