主题配置
概述
主题配置用于定制主题的各项功能，以控制主题的行为， 您可以在 .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中进行配置。
blog
类型：
false | BlogOptions默认值：
{ link: '/blog/', include: ['**/*.md'], exclude: [] }详情：
博客配置。
该字段不支持在 主题配置文件
plume.config.js中进行配置。
interface BlogOptions {
/**
* blog list link
*
* @default '/blog/'
*/
link?: string
/**
* 在 `{sourceDir}` 目录中，通过 glob string 配置包含文件
*
* @default - ['**\*.md']
*/
include?: string[]
/**
* 在 `{sourceDir}` 目录中，通过 glob string 配置排除的文件
*
* @default - ['.vuepress/', 'node_modules/']
*/
exclude?: string[]
/**
* 分页配置
*
* - `false` - 不启用分页
* - `number` - 每页显示的文章数量
*/
pagination?: false | number | {
/**
* 每页显示的文章数量
* @default 10
*/
perPage?: number
}
/**
* 是否启用标签页
* @default true
*/
tags?: boolean
/**
* 自定义标签页链接
*
* @default '/blog/tags/'
*/
tagsLink?: string
/**
* 标签颜色主题
*
* - `colored`： 彩色标签，不同标签颜色不同
* - `brand`: 使用主题颜色作为标签颜色
* - `gray`: 使用 灰色 作为标签颜色
*
* @default 'colored'
*/
tagsTheme?: 'colored' | 'gray' | 'brand'
/**
* 是否启用归档页
* @default true
*/
archives?: boolean
/**
* 自定义归档页链接
*
* @default '/blog/archives/'
*/
archivesLink?: string
/**
* 是否启用分类页
* @default true
*/
categories?: boolean
/**
* 自定义分类页链接
*
* @default '/blog/categories/'
*/
categoriesLink?: string
/**
* 分类页展开深度
*
* @default 'deep'
*/
categoriesExpand?: number | 'deep'
/**
* 文章分类列表转换函数，比如排除不需要的一级分类
* @param categories 分类列表
* @returns 返回一个新的分类列表
*/
categoriesTransform?: (categories: PageCategoryData[]) => PageCategoryData[]
/**
* 博客文章封面图
*
* 配置封面图的位置，支持 `'left'`、`'right'`、`'top'`、`'top-inside'`
*
* @default 'right'
*/
postCover?: BlogPostCoverLayout | BlogPostCoverStyle
}
type BlogPostCoverLayout = 'left' | 'right' | 'odd-left' | 'odd-right' | 'top'
interface BlogPostCoverStyle {
/**
* 博客文章封面图的位置
*/
layout?: BlogPostCoverLayout
/**
* 博客文章封面图的比例
*
* @default '4:3'
*/
ratio?: number | `${number}:${number}`
/**
* 封面图的宽度, 仅在 layout 为 'left' 或 'right' 时生效
*
* @default 240
*/
width?: number
/**
* 是否使用紧凑模式，紧凑模式下，封面图紧贴容器边缘
* @default false
*/
compact?: boolean
}article
类型：
string默认值：
/article/详情： 文章链接前缀
该字段不支持在 主题配置文件
plume.config.js中进行配置。
autoFrontmatter
类型：
false | AutoFrontmatterOptions详情：
是否为 markdown 文件自动添加 frontmatter 配置
interface AutoFrontmatterOptions { /** * glob 匹配，被匹配的文件将会自动生成 frontmatter * * @default ['**\/*.md'] */ include?: string | string[] /** * glob 匹配，被匹配的文件将不会自动生成 frontmatter */ exclude?: string | string[] /** * 是否自动生成 permalink * * @default true */ permalink?: boolean /** * 是否自动生成 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详情： 个人社交信息配置。
将作为 图标链接 展示在 导航栏最右侧。
图标可选值：
'github''gitlab''npm''docker''discord''telegram''facebook''instagram''linkedin''mastodon''slack''twitter''x''youtube''juejin''stackoverflow''qq''weibo''bilibili''zhihu''douban''steam''xbox'{ svg: string, name?: string }: 自定义图标，传入 svg 源码字符串，可选name字段，用于配置navbarSocialInclude
示例：
export default defineUserConfig({
theme: plumeTheme({
social: [
{ 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/', }, ], }, ], }), })
notes
类型：
false | NotesOptions默认值：
{ link: '/note', dir: 'notes', notes: [] }详情：
笔记配置， 笔记中的文章默认不会出现在首页文章列表
你可以将配置的notes 配置到 navbar中，以便浏览查看
详细配置请查看 此文档
sidebar
类型：
false | SidebarMulti详情：
侧边栏配置。主题更推荐在 notes 配置 中进行侧边栏配置。
当你不希望使用
notes功能，但又期望给文档增加侧边栏时，可以使用此配置。配置对象的
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' }
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-blog'默认值：
true详情： 是否显示创建时间
false- 不显示'only-blog'- 只显示在博客文章页面true- 显示在所有文章页面
