主题配置
概述
主题配置用于定制主题的各项功能，以控制主题的行为， 您可以在 .vuepress/config.ts 或者 .vuepress/plume.config.ts 中进行配置。
当字段说明包含以下声明时，表示该字段不支持在 .vuepress/plume.config.ts 中进行配置：
该字段不支持在 主题配置文件 plume.config.ts 中进行配置。
无以上声明的字段，您可以在 .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.ts了解更多。该字段不支持在 主题配置文件
plume.config.ts中进行配置。
plugins
类型：
ThemeBuiltinPlugins默认值：
{}详情：
对主题内部使用的插件进行自定义配置。
主题使用的插件默认已进行了配置，大多数情况下您不需要进行修改，如果需要使用到细致的定制化，请查阅 此文档
该字段不支持在 主题配置文件
plume.config.ts中进行配置。
encrypt
类型：
EncryptOptions（{ global?: boolean; admin?: string | string[]; rules?: Record<string, string | string[]> }）默认值：
undefined详情：
站点加密配置，支持全站加密与文章级加密。
未配置时不会启用任何加密。
global为true时全站加密；admin为超级权限密码；rules以文件相对路径、页面访问路径或目录路径为 key 指定文章密码， key 以^开头时按正则表达式匹配。该字段支持在 主题配置文件
plume.config.ts中配置并热更新。
markdown 1.0.0-rc.136 +
类型：
MarkdownOptions默认值：
{}详情：
Markdown 功能配置， 参考 此文档
该字段不支持在 主题配置文件
plume.config.ts中进行配置。
codeHighlighter 1.0.0-rc.136 +
类型：
false | (ShikiPluginOptions & { renderIndentGuides?: boolean | object; colorizedBrackets?: boolean | object })默认值：
{}详情：
代码高亮配置， 参考 此文档
除 @vuepress/plugin-shiki 的选项外， 还额外支持
renderIndentGuides（缩进参考线）与colorizedBrackets（彩色括号）两个主题扩展配置。该字段不支持在 主题配置文件
plume.config.ts中进行配置。
components
类型：
MarkdownPowerPluginOptions['components']默认值：
undefined详情：
自动导入组件配置。主题使用 unplugin-vue-components 实现组件自动导入，继承其完整配置项（
include、exclude除外）。import path from 'node:path' import { defineThemeConfig } from 'vuepress-theme-plume' export default defineThemeConfig({ components: { dirs: [path.resolve(import.meta.dirname, 'components')], }, })该字段不支持在 主题配置文件
plume.config.ts中进行配置。
search 1.0.0-rc.136 +
类型：
boolean | SearchOptions默认值：
{ provider: 'local' }详情：
搜索配置， 参考 此文档
true等价于{ provider: 'local' }；false表示禁用搜索。该字段不支持在 主题配置文件
plume.config.ts中进行配置。
comment 1.0.0-rc.136 +
类型：
false | CommentPluginOptions默认值：
false详情：
评论配置， 参考 此文档
该字段不支持在 主题配置文件
plume.config.ts中进行配置。
watermark 1.0.0-rc.136 +
类型：
boolean | (WatermarkPluginOptions & { fullPage?: boolean })默认值：
false详情：
水印配置， 参考 此文档
除 @vuepress/plugin-watermark 的选项外， 主题额外支持
fullPage（默认true）：为true时水印铺满整个页面，为false时仅覆盖文章内容区域。该字段不支持在 主题配置文件
plume.config.ts中进行配置。
readingTime 1.0.0-rc.136 +
类型：
false | ReadingTimePluginOptions默认值：
false详情：
阅读时长配置， 参考 此文档
该字段不支持在 主题配置文件
plume.config.ts中进行配置。
copyCode 1.0.0-rc.136 +
类型：
false | CopyCodePluginOptions默认值：
{}详情：
复制代码配置， 参考 此文档
此功能默认 启用。
该字段不支持在 主题配置文件
plume.config.ts中进行配置。
replaceAssets 1.0.0-rc.139 +
类型：
false | ReplaceAssetsPluginOptions默认值：
false详情：
替换资源配置， 参考 此文档
该字段不支持在 主题配置文件
plume.config.ts中进行配置。
llmstxt
类型：
boolean | LlmsPluginOptions默认值：
false详情：
是否生成
llms.txt与llms-full.txt，用于向大语言模型提供站点内容。 该功能仅在生产构建（vuepress build）时生效。参考 此文档
该字段不支持在 主题配置文件
plume.config.ts中进行配置。
hostname
类型：
string默认值：
''详情：
部署站点域名。
当
hostname配置为有效域名时，主题将会生成sitemap和seo相关的内容。该字段不支持在 主题配置文件
plume.config.ts中进行配置。
autoFrontmatter
类型：
false | AutoFrontmatterOptions默认值： 默认启用，等价于
{ title: true, createTime: true, permalink: true }详情：
是否为 markdown 文件自动添加 frontmatter 配置。 只有显式设置为
false才会关闭该功能。interface AutoFrontmatterOptions { /** * 是否自动生成 permalink * * @default true * - true: 自动生成 permalink * - false: 不生成 permalink * - 'filepath': 根据文件路径生成 permalink */ permalink?: boolean | 'filepath' /** * 是否自动生成 createTime * * 默认读取 文件创建时间，`createTime` 比 vuepress 默认的 `date` 时间更精准到秒 */ createTime?: boolean /** * 是否自动生成 title * * 默认读取文件名作为标题 */ title?: boolean }
cache
类型：
false | 'memory' | 'filesystem'默认值：
filesystem详情：
是否启用编译缓存，或配置缓存方式
此配置项用于解决 VuePress 启动速度慢的问题，在首次启动服务时，对编译结果进行缓存，二次启动时 直接读取缓存，跳过编译，从而加快启动速度。
false：禁用缓存'memory'：使用内存缓存，此方式可获得更快的启动速度，但随着项目文件数量增加，内存占用会增加， 适合文章数量较少的项目使用'filesystem'：使用文件系统缓存，此方式可获得相对快且稳定的启动速度，更适合内容多的项目使用
该字段不支持在 主题配置文件
plume.config.ts中进行配置。为了使缓存能够生效，您应该 删除
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.ts中进行配置。
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.ts 中进行配置。
contributors
类型：
boolean | (ContributorsOptions & { mode?: 'inline' | 'block' })默认值：
true详情： 是否显示贡献者
传入对象时可使用 @vuepress/plugin-git 的
ContributorsOptions选项，以及主题扩展的mode?: 'inline' | 'block'（贡献者的展示模式）。更多配置请参考 此文档
该字段不支持在 主题配置文件
plume.config.ts中进行配置。
changelog
类型：
boolean | ChangelogOptions默认值：
false详情： 是否显示页面变更历史
更多配置请参考 此文档
该字段不支持在 主题配置文件
plume.config.ts中进行配置。
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 - 默认值:
undefined
配置博主个人资料，显示在博客右侧侧边栏。
import { defineThemeConfig } from 'vuepress-theme-plume'
export default defineThemeConfig({
profile: {
avatar: '/avatar.png',
name: 'Your Name',
description: 'Your description',
circle: true,
location: 'Hangzhou, China',
organization: 'Your Company',
layout: 'right',
},
})avatar
- 类型:
string - 默认值:
undefined
头像图片链接，支持本地路径或网络地址。
name
- 类型:
string - 默认值:
undefined
博主名称，显示在头像下方。
description
- 类型:
string - 默认值:
undefined
个人描述或签名，显示在名称下方。
circle
- 类型:
boolean - 默认值:
false
是否以圆形裁剪显示头像。
location
- 类型:
string - 默认值:
undefined
地理位置信息，显示在个人资料中。
organization
- 类型:
string - 默认值:
undefined
组织或公司信息，显示在个人资料中。
layout
- 类型:
'left' | 'right' - 默认值:
'right'
个人资料的布局位置。right 显示在右侧侧边栏，left 显示在左侧侧边栏。
social
- 类型:
SocialLink[] - 默认值:
[]
配置社交账号链接，显示在个人资料区域。支持 30+ 内置图标（如 github、twitter、discord、weibo、bilibili、zhihu 等），也支持自定义 SVG 图标。
import { defineThemeConfig } from 'vuepress-theme-plume'
export default defineThemeConfig({
social: [
{ icon: 'github', link: 'https://github.com/your-username' },
{ icon: 'twitter', link: 'https://twitter.com/your-username' },
{ icon: 'weibo', link: 'https://weibo.com/your-username' },
// 自定义 SVG 图标
{ icon: { svg: '<svg>...</svg>', name: 'custom' }, link: 'https://example.com' },
],
})icon
- 类型:
string | { svg: string, name?: string } - 必填
社交图标。可以是内置图标名称（如 github、twitter、discord、facebook、instagram、linkedin、mastodon、npm、slack、youtube、qq、weibo、bilibili、gitlab、docker、juejin、zhihu、douban、steam、stackoverflow、xbox、tiktok、kuaishou、bytedance、xiaohongshu、bluesky、gmail 等），也可以是包含 svg 和可选 name 的自定义图标对象。
link
- 类型:
string - 必填
社交链接地址。
ariaLabel
- 类型:
string - 默认值:
undefined
无障碍标签，用于屏幕阅读器读取。未设置时将根据图标名称自动生成。
navbarSocialInclude
- 类型:
string[] - 默认值:
['github', 'twitter', 'discord', 'facebook']
控制哪些社交链接同时显示在导航栏中。仅 social 中配置的且 icon 在此列表中的社交链接会显示在导航栏右侧。
import { defineThemeConfig } from 'vuepress-theme-plume'
export default defineThemeConfig({
social: [
{ icon: 'github', link: 'https://github.com/your-username' },
{ icon: 'twitter', link: 'https://twitter.com/your-username' },
{ icon: 'weibo', link: 'https://weibo.com/your-username' },
],
navbarSocialInclude: ['github', 'weibo'], // 只有 github 和 weibo 显示在导航栏
})navbar
类型：
NavItem[]默认值：
[]（但仍有运行时兜底，见下文）详情： 导航栏配置。
未配置时并非空导航栏
当
navbar为空时，主题会按当前集合自动注入「首页 / 博客（或首个 post 集合）/ 标签 / 归档」四项兜底导航（见theme/src/node/config/resolveThemeData.ts）。若想完全自定义导航栏，显式传入数组即可覆盖。为了配置导航栏元素，你可以将其设置为导航栏数组 ，其中的每个元素是
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
是否启用过渡动画效果。设置为 false 可完全禁用所有过渡动画。传入对象可分别控制各类动画。
import { defineThemeConfig } from 'vuepress-theme-plume'
export default defineThemeConfig({
transition: {
page: true,
postList: true,
appearance: 'fade',
},
})page
- 类型:
boolean - 默认值:
true
是否启用页面跳转时的过渡动画。
postList
- 类型:
boolean - 默认值:
true
是否启用文章列表的过渡动画。
appearance
- 类型:
boolean | 'fade' | 'circle-clip' | 'horizontal-clip' | 'vertical-clip' | 'skew-clip' | 'blinds-vertical' | 'blinds-horizontal' | 'soft-blur-fade' | 'diamond-reveal' - 默认值:
'fade'
深色/浅色模式切换时的过渡动画。设为 false 可单独关闭该动画（不影响 page、postList）。
支持以下 9 种动画效果：
fade：淡入淡出（默认）circle-clip：圆形裁剪horizontal-clip：水平裁剪vertical-clip：垂直裁剪skew-clip：倾斜裁剪blinds-vertical：垂直百叶窗blinds-horizontal：水平百叶窗soft-blur-fade：柔和模糊淡出diamond-reveal：菱形揭示
readAid
类型：
boolean | 'mask' | 'left' | 'right'默认值：
false详情： 是否显示阅读辅助线，（辅助线可帮助用户视觉聚焦到鼠标所在区域）
false- 不显示'mask'- 显示遮罩'left'- 显示左侧辅助线'right'- 显示右侧辅助线
footer
类型：
false | { message: string; copyright?: string }默认值：
{ message: 'Powered by VuePress & vuepress-theme-plume' }详情： 页脚配置。
默认并非「不显示」
即使不配置
footer，主题也会渲染一个指向 VuePress 与主题官网的默认页脚（内容见上方默认值）。若想彻底隐藏，必须显式设置为false：theme: plumeTheme({ footer: false })
bulletin
类型：
boolean | BulletinOptions默认值：
false详情： 公告板配置
详情请参考 公告板
editLinkPattern
类型：
string默认值：
''详情： 编辑链接的正则表达式
示例：
':repo/edit/:branch/:path'
externalLinkIcon
- 类型：
boolean - 默认值：
true - 详情： 是否在外部链接后显示外部链接图标
copyright
类型：
boolean | CopyrightLicense | CopyrightOptions默认值：
false详情： 版权配置
详情请参考 版权所有
prevPage
- 类型：
boolean - 默认值：
true - 详情： 是否显示上一页
nextPage
- 类型：
boolean - 默认值：
true - 详情： 是否显示下一页
createTime
类型：
boolean | 'only-posts'默认值：
true详情： 是否显示创建时间
false- 不显示'only-posts'- 只显示在文章列表页面true- 显示在所有文章页面
