主题配置
主题配置位于 doc
配置中的 themeConfig
下。例如:
rspress.config.ts
import { defineConfig } from 'rspress/config';
export default defineConfig({
themeConfig: {
// ...
},
});
nav
网站的导航栏。 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',
},
],
},
],
},
});
网站的侧边栏。配置为一个对象,类型如下:
// 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',
],
},
],
},
},
});
主页的页脚。
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',
},
});
socialLinks
你可以通过如下的配置添加相关链接,比如 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;
}
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,
},
});
search
- 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',
},
});