主题配置
概述
主题配置用于定制主题的各项功能，以控制主题的行为， 您可以在 .vuepress/config.ts 或者 .vuepress/plume.config.ts 中进行配置。
当字段说明包含以下声明时，表示该字段不支持在 .vuepress/plume.config.ts 中进行配置：
该字段不支持在 主题配置文件 plume.config.js 中进行配置。
无以上声明的字段，你可以在 .vuepress/config.ts 或者 .vuepress/plume.config.ts 的任意一个文件中 进行配置，一般情况下建议在 .vuepress/plume.config.ts 中进行配置。
已经在一个配置文件中进行配置的字段，尽量不要在另一个配置文件中重复配置
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
// 主题配置
})
})import { defineThemeConfig } from 'vuepress-theme-plume'
export default defineThemeConfig({
// 主题配置
})基础配置
configFile
类型：
string默认值：
''详情：
自定义主题配置文件的路径。
查看 主题配置文件
plume.config.js了解更多。该字段不支持在 主题配置文件
plume.config.js中进行配置。
plugins
类型：
PlumeThemePluginOptions默认值：
{}详情：
对主题内部使用的插件进行自定义配置。
主题使用的插件默认已进行了配置，大多数情况下您不需要进行修改，如果需要使用到细致的定制化，请查阅 此文档
该字段不支持在 主题配置文件
plume.config.js中进行配置。
markdown 1.0.0-rc.136 +
类型：
MarkdownOptions默认值：
{}详情：
Markdown 功能配置， 参考 此文档
该字段不支持在 主题配置文件
plume.config.js中进行配置。
codeHighlighter 1.0.0-rc.136 +
类型：
false | ShikiPluginOptions默认值：
{}详情：
代码高亮配置， 参考 此文档
该字段不支持在 主题配置文件
plume.config.js中进行配置。
search 1.0.0-rc.136 +
类型：
false | SearchOptions默认值：
{ provider: 'local' }详情：
搜索配置， 参考 此文档
该字段不支持在 主题配置文件
plume.config.js中进行配置。
comment 1.0.0-rc.136 +
类型：
false | CommentPluginOptions默认值：
false详情：
评论配置， 参考 此文档
该字段不支持在 主题配置文件
plume.config.js中进行配置。
watermark 1.0.0-rc.136 +
类型：
false | WatermarkPluginOptions默认值：
false详情：
水印配置， 参考 此文档
该字段不支持在 主题配置文件
plume.config.js中进行配置。
readingTime 1.0.0-rc.136 +
类型：
false | ReadingTimePluginOptions默认值：
false详情：
阅读时长配置， 参考 此文档
该字段不支持在 主题配置文件
plume.config.js中进行配置。
copyCode 1.0.0-rc.136 +
类型：
false | CopyCodePluginOptions默认值：
{}详情：
复制代码配置， 参考 此文档
该字段不支持在 主题配置文件
plume.config.js中进行配置。
replaceAssets 1.0.0-rc.139 +
类型：
false | ReplaceAssetsPluginOptions默认值：
false详情：
替换资源配置， 参考 此文档
该字段不支持在 主题配置文件
plume.config.js中进行配置。
hostname
类型：
string默认值：
''详情：
部署站点域名。
当
hostname配置为有效域名时，主题将会生成sitemap和seo相关的内容。该字段不支持在 主题配置文件
plume.config.js中进行配置。
autoFrontmatter
类型：
false | AutoFrontmatterOptions详情：
是否为 markdown 文件自动添加 frontmatter 配置
interface AutoFrontmatterOptions { /** * 是否自动生成 permalink * * @default true * - true: 自动生成 permalink * - false: 不生成 permalink * - 'filepath': 根据文件路径生成 permalink */ permalink?: boolean | 'filepath' /** * 是否自动生成 createTime * * 默认读取 文件创建时间，`createTitme` 比 vuepress 默认的 `date` 时间更精准到秒 */ createTime?: boolean /** * 是否自动生成 title * * 默认读取文件名作为标题 */ title?: boolean }
cache
类型：
false | 'memory' | 'filesystem'默认值：
filesystem详情：
是否启用 编译缓存，或配置缓存方式
此配置项用于解决 VuePress 启动速度慢的问题，在首次启动服务时，对编译结果进行缓存，二次启动时 直接读取缓存，跳过编译，从而加快启动速度。
false：禁用 缓存'memory'：使用内存缓存，此方式可获得更快的启动速度，但随着项目文件数量增加，内存占用会增加， 适合文章数量较少的项目使用'filesystem'：使用文件系统缓存，此方式可获得相对快且稳定的启动速度，更适合内容多的项目使用
注意
该字段不支持在 主题配置文件
plume.config.js中进行配置。为了使缓存能够生效，您应该 删除
package.json中vuepress dev开发服务启动脚本中的--clean-cache参数。
docsRepo
- 类型：
string - 默认值：
'' - 详情： 文档仓库配置, 用于生成
Edit this page链接。
docsBranch
- 类型：
string - 默认值：
'' - 详情： 文档仓库分支配置，用于生成
Edit this page链接。
docsDir
- 类型：
string - 默认值：
'' - 详情： 文档仓库目录配置，用于生成
Edit this page链接。
editLink
类型：
boolean默认值：
true详情： 是否启用 编辑链接
该字段不支持在 主题配置文件
plume.config.js中进行配置。
lastUpdated
- 类型：
false | LastUpdatedOptions - 默认值：
{ formatOptions: { dateStyle: 'short', timeStyle: 'short' } } - 详情： 最后更新时间
interface LastUpdatedOptions {
/**
* 设置最后更新时间格式的选项。
* @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat#using_options
*
* @default
* { dateStyle: 'short', timeStyle: 'short' }
*/
formatOptions?: Intl.DateTimeFormatOptions & { forceLocale?: boolean }
}该字段不支持在 主题配置文件 plume.config.js 中进行配置。
contributors
类型：
boolean | ContributorsOptions默认值：
true详情： 是否显示贡献者
更多配置请参考 此文档
该字段不支持在 主题配置文件
plume.config.js中进行配置。
changelog
类型：
boolean | ChangelogOptions默认值：
false详情： 是否显示页面变更历史
更多配置请参考 此文档
该字段不支持在 主题配置文件
plume.config.js中进行配置。
locales
- 类型：
Record<string, ThemeLocaleData> - 默认值：
{} - 详情： 多语言配置
不同语言的文本配置，参考 此文档
多语言配置支持以下 Locale 所有配置选项以控制不同语言下的主题行为。
Locale 配置
以下所有字段也均是基础配置字段，可以与 locales 等字段平级配置。
home
- 类型：
false | string - 默认值：
/ - 详情： 首页的路径， 它将被用于：
- 导航栏中 logo的链接；
- 404页面的 返回首页 的链接；
logo
- 类型:
false | string - 默认值：
false - 详情： 导航栏中的logo。
logoDark
- 类型
false | string - 默认值：
false - 详情： Dark模式下，导航栏中的logo。
appearance
- 类型：
boolean | 'dark' | 'force-dark - 默认值：
true
是否启用 深色模式。
- 如果该选项设置为
true，则默认主题将由用户的首选配色方案决定。 - 如果该选项设置为
dark，则默认情况下主题将是深色的，除非用户手动切换它。 - 如果该选项设置为
false，用户将无法切换主题。 - 如果该选项设置为
force-dark，则用户将无法切换主题，但会强制将主题更改为深色。
此选项注入一个内联脚本，从本地存储恢复用户设置。这确保在呈现页面之前应用 [data-theme="dark"] 以避免闪烁。
profile
- 类型：
ProfileOptions - 默认值：
{} - 详情： 配置站点博主的个人信息
profile.avatar: 头像地址，用于右侧博主信息展示profile.name: 名称， 用于右侧博主信息展示profile.description: 个人描述，用于右侧博主信息展示profile.circle: 是否为圆形头像profile.location: 用户地理位置profile.organization: 用户所在组织/公司profile.layout: 个人信息展示在左侧还是右侧，'left' | 'right'
示例：
export default defineUserConfig({
theme: plumeTheme({
profile: {
avatar: '/avatar.jpg',
name: '张三',
description: '此处无银三百两，隔壁王二不曾偷',
circle: true,
location: '杭州，中国',
organization: 'xxx公司',
layout: 'right',
}
})
})social
类型：
false | SocialLink[]默认值：
false详情： 个人社交信息配置。
将作为 图标链接 展示在 导航栏最右侧。
支持 Iconify 任意图标，直接使用 iconify name 即可自动加载。
对于
simple-icons集合下的图标，可以省略simple-icons:前缀，如simple-icons:github可以简写为github常见的社交图标示例：
- discord
- telegram
- github
- mastodon
- npm
- slack
- x
- youtube
- bluesky
- tiktok
- bilibili
- gitlab
- docker
- juejin
- zhihu
- douban
- steam
- stackoverflow
- xbox
- kuaishou
- twitch
- xiaohongshu
如果 Iconify 无法满足你的需求，可以传入
{ svg: string, name?: string }的格式，使用自定义图标，传入 svg 源码字符串，可选name字段，用于配置navbarSocialInclude
示例：
export default defineUserConfig({
theme: plumeTheme({
social: [
// 使用 iconify name
{ icon: 'github', link: 'https://github.com/zhangsan' },
{
// 使用自定义图标
icon: { svg: '<svg>xxxxx</svg>', name: 'xxx' },
link: 'https://xxx.com'
},
]
})
})navbarSocialInclude
类型：
string[]默认值：
['github', 'twitter', 'discord', 'facebook']详情：
允许显示在导航栏的社交链接。 该配置仅在 PC 端下有效。
如果
social配置为{ svg: string, name: string}则可将name作为navbarSocialInclude的值。
navbar
类型：
NavItem[]默认值：
[]详情： 导航栏配置。
为了配置导航栏元素，你可以将其设置为 导航栏数组 ，其中的每个元素是
string或NavItem对象NavItem对象应该有一个 text 字段和一个 link 字段，还有一个可选的activeMatch字段。string表示是一个页面文件路径，或者是一个页面的访问路径。
type NavItem = string | {
text: string
link: string
/**
* 当前分组的页面前缀
*/
prefix?: string
/**
* 该分组下的导航项
*/
items?: NavItem[]
/**
* 支持 iconify 图标，直接使用 iconify name 即可自动加载
*
* @see https://icon-sets.iconify.design/
*/
icon: string
/**
* 控制元素何时被激活
*/
activeMatch?: string
}示例1：
export default defineUserConfig({ theme: plumeTheme({ navbar: [ // NavbarItem { text: 'Foo', link: '/foo/' }, // NavbarGroup { text: 'Group', prefix: '/group/', items: ['foo/', 'bar/'], }, // 字符串 - 页面文件路径 '/bar', // 可以直接省略后缀 `.md` ], }), })示例2：
export default defineUserConfig({ theme: plumeTheme({ navbar: [ // 嵌套 Group - 最大深度为 2 { text: 'Group', items: [ { text: 'SubGroup', items: ['/group/sub/', '/group/sub/bar/'], }, ], }, // 控制元素何时被激活 { text: 'Group 2', items: [ { text: 'Always active', link: '/', // 该元素将一直处于激活状态 activeMatch: '/', }, { text: 'Active on /foo/', link: '/not-foo/', // 该元素在当前路由路径是 /foo/ 开头时激活 // 支持正则表达式 activeMatch: '^/foo/', }, ], }, ], }), })
collections
类型：
ThemeCollectionItem[]默认值：
[]详情： 文档集合配置
sidebar
类型：
false | SidebarMulti详情：
侧边栏配置。主题更推荐在 collections 配置 中进行侧边栏配置。
配置对象的
key为侧边栏公共访问路径前缀。对于
value:'auto'表示自动根据目录结构生成侧边栏string表示侧边栏对应的页面文件路径SidebarItem表示侧边栏单项配置
type ThemeIcon = string | { svg: string }
type SidebarMulti = Record<
string,
| 'auto'
| (string | SidebarItem)[]
| { items: 'auto' | (string | SidebarItem)[], prefix?: string }
>
interface SidebarItem {
/**
* 侧边栏文本
*/
text?: string
/**
* 侧边栏链接
*/
link?: string
/**
* 侧边栏图标
*/
icon?: ThemeIcon
/**
* 次级侧边栏分组
*/
items?: 'auto' | (string | SidebarItem)[]
/**
* 如果未指定，组不可折叠。
* 如果为`true`，组可折叠，并默认折叠。
* 如果为`false`，组可折叠，但默认展开。
*/
collapsed?: boolean
/**
* 当前分组的链接前缀
*/
prefix?: string
rel?: string
target?: string
}sidebarScrollbar
类型：
boolean默认值：
true详情： 是否显示侧边栏滚动条
设置为
false时，仅隐藏滚动条，但不改变滚动行为。
aside
类型：
boolean | 'left'默认值：
true详情：
是否显示侧边栏
false表示禁用 右侧边栏true表示启用 右侧边栏'left表示将有侧边栏移动到文章内容左侧，sidebar 右侧
每个页面可以通过 frontmatter aside 覆盖层级配置。
outline
类型：
false | number | [number, number] | 'deep'默认值：
[2, 3]详情：
要显示的标题级别。
单个数字表示只显示该级别的标题。
如果传递的是一个元组，第一个数字是最小级别，第二个数字是最大级别。
'deep'与[2, 6]相同，将显示从<h2>到<h6>的所有标题。当 aside 被禁用时，
outline也会被禁用每个页面可以通过 frontmatter outline 覆盖层级配置。
transition
类型：
boolean | TransitionOptions默认值：
true详情：
是否启用过渡动画。
传入
boolean类型时，true代表启用，false代表禁用。也可以传入一个对象，具体配置见下
interface TransitionOptions { /** * 是否启用 页面间跳转过渡动画 * @default true */ page?: boolean /** * 是否启用 博客文章列表过渡动画 * @default true */ postList?: boolean /** * 是否启用 深色/浅色 模式切换过渡动画， * 或配置过渡动画类型 * @default 'fade' */ appearance?: boolean | 'fade' | 'circle-clip' | 'horizontal-clip' | 'vertical-clip' | 'skew-clip' | 'blinds-vertical' | 'blinds-horizontal' | 'soft-blur-fade' | 'diamond-reveal' }
footer
- 类型：
false | { message: string; copyright: string } - 默认值：
false - 详情： 页脚配置。
bulletin
类型：
boolean | BulletinOptions默认值：
false详情： 公告板配置
详情请参考 公告板
editLinkPattern
类型：
string默认值：
''详情： 编辑链接的正则表达式
示例：
':repo/edit/:branch/:path'
copyright
类型：
boolean | CopyrightLicense | CopyrightOptions默认值：
false详情： 版权配置
详情请参考 版权所有
prevPage
- 类型：
boolean - 默认值：
true - 详情： 是否显示上一页
nextPage
- 类型：
boolean - 默认值：
true - 详情： 是否显示下一页
createTime
类型：
boolean | 'only-posts'默认值：
true详情： 是否显示创建时间
false- 不显示'only-posts'- 只显示在文章列表页面true- 显示在所有文章页面
