Theme Configuration
About 2379 wordsAbout 8 min
2025-10-09
Overview
Theme configuration is used to customize various features of the theme and control its behavior. You can configure it in either .vuepress/config.ts
or .vuepress/plume.config.ts
.
When a field description includes the following statement, it indicates that the field is not supported for configuration in .vuepress/plume.config.ts
:
This field is not supported for configuration in the Theme Config File plume.config.js
.
For fields without the above declaration, you can configure them in either .vuepress/config.ts
or .vuepress/plume.config.ts
. It is generally recommended to configure them in .vuepress/plume.config.ts
.
Avoid reconfiguring a field that has already been configured in one configuration file within another configuration file.
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
// Theme configuration
})
})
import { defineThemeConfig } from 'vuepress-theme-plume'
export default defineThemeConfig({
// Theme configuration
})
Basic Configuration
configFile
Type:
string
Default:
''
Details:
Custom path to the theme configuration file.
Refer to Theme Config File
plume.config.js
for more information.This field is not supported for configuration in the Theme Config File
plume.config.js
.
plugins
Type:
PlumeThemePluginOptions
Default:
{}
Details:
Custom configuration for plugins used internally by the theme.
The plugins used by the theme are configured by default. In most cases, modification is not required. For detailed customization, please refer to this documentation.
This field is not supported for configuration in the Theme Config File
plume.config.js
.
markdown 1.0.0-rc.136 +
Type:
MarkdownOptions
Default:
{}
Details:
Markdown feature configuration. Refer to this documentation.
This field is not supported for configuration in the Theme Config File
plume.config.js
.
codeHighlighter 1.0.0-rc.136 +
Type:
false | ShikiPluginOptions
Default:
{}
Details:
Code highlighting configuration. Refer to this documentation.
This field is not supported for configuration in the Theme Config File
plume.config.js
.
search 1.0.0-rc.136 +
Type:
false | SearchOptions
Default:
{ provider: 'local' }
Details:
Search configuration. Refer to this documentation.
This field is not supported for configuration in the Theme Config File
plume.config.js
.
comment 1.0.0-rc.136 +
Type:
false | CommentPluginOptions
Default:
false
Details:
Comment configuration. Refer to this documentation.
This field is not supported for configuration in the Theme Config File
plume.config.js
.
watermark 1.0.0-rc.136 +
Type:
false | WatermarkPluginOptions
Default:
false
Details:
Watermark configuration. Refer to this documentation.
This field is not supported for configuration in the Theme Config File
plume.config.js
.
readingTime 1.0.0-rc.136 +
Type:
false | ReadingTimePluginOptions
Default:
false
Details:
Reading time configuration. Refer to this documentation.
This field is not supported for configuration in the Theme Config File
plume.config.js
.
copyCode 1.0.0-rc.136 +
Type:
false | CopyCodePluginOptions
Default:
{}
Details:
Copy code configuration. Refer to this documentation.
This field is not supported for configuration in the Theme Config File
plume.config.js
.
replaceAssets 1.0.0-rc.139 +
Type:
false | ReplaceAssetsPluginOptions
Default:
false
Details:
Replace assets configuration. Refer to this documentation.
This field is not supported for configuration in the Theme Config File
plume.config.js
.
hostname
Type:
string
Default:
''
Details:
Deployment site domain name.
When
hostname
is configured to a valid domain, the theme will generatesitemap
and SEO-related content.This field is not supported for configuration in the Theme Config File
plume.config.js
.
autoFrontmatter
Type:
false | AutoFrontmatterOptions
Details:
Whether to automatically add frontmatter configuration to markdown files.
interface AutoFrontmatterOptions { /** * Whether to automatically generate permalink * * @default true */ permalink?: boolean /** * Whether to automatically generate createTime * * Reads file creation time by default. `createTime` is more precise (to the second) than the default VuePress `date` field. */ createTime?: boolean /** * Whether to automatically generate title * * Uses the filename as the title by default. */ title?: boolean }
cache
Type:
false | 'memory' | 'filesystem'
Default:
filesystem
Details:
Whether to enable compilation cache, or configure the caching method.
This configuration item addresses the slow startup speed of VuePress. It caches the compilation results during the first service start. On subsequent starts, it reads the cache directly, skipping compilation to speed up startup.
false
: Disable cache.'memory'
: Use memory cache. This method provides faster startup speed but increases memory usage as the number of project files grows. Suitable for projects with fewer articles.'filesystem'
: Use filesystem cache. This method provides a relatively fast and stable startup speed, more suitable for projects with substantial content.
Warning
This field is not supported for configuration in the Theme Config File
plume.config.js
.For the cache to take effect, you should remove the
--clean-cache
parameter from thevuepress dev
development server startup script in yourpackage.json
.
docsRepo
- Type:
string
- Default:
''
- Details: Documentation repository configuration, used to generate the
Edit this page
link.
docsBranch
- Type:
string
- Default:
''
- Details: Documentation repository branch configuration, used to generate the
Edit this page
link.
docsDir
- Type:
string
- Default:
''
- Details: Documentation repository directory configuration, used to generate the
Edit this page
link.
editLink
Type:
boolean
Default:
true
Details: Whether to enable the edit link.
This field is not supported for configuration in the Theme Config File
plume.config.js
.
lastUpdated
- Type:
false | LastUpdatedOptions
- Default:
{ formatOptions: { dateStyle: 'short', timeStyle: 'short' } }
- Details: Last updated time.
interface LastUpdatedOptions {
/**
* Options to set the format of the last updated time.
* @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 }
}
This field is not supported for configuration in the Theme Config File plume.config.js
.
contributors
Type:
boolean | ContributorsOptions
Default:
true
Details: Whether to display contributors.
For more configuration, please refer to this documentation.
This field is not supported for configuration in the Theme Config File
plume.config.js
.
changelog
Type:
boolean | ChangelogOptions
Default:
false
Details: Whether to display page change history.
For more configuration, please refer to this documentation.
This field is not supported for configuration in the Theme Config File
plume.config.js
.
locales
- Type:
Record<string, ThemeLocaleData>
- Default:
{}
- Details: Multi-language configuration.
Text configuration for different languages. Refer to this documentation.
The multi-language configuration supports all configuration options under the following Locale to control theme behavior in different languages.
Locale Configuration
All the following fields are also basic configuration fields and can be configured at the same level as fields like locales
.
home
- Type:
false | string
- Default:
/
- Details: The path to the home page. It will be used for:
- The logo link in the navbar;
- The Back to Home link on the 404 page;
logo
- Type:
false | string
- Default:
false
- Details: Logo in the navbar.
logoDark
- Type:
false | string
- Default:
false
- Details: Logo in the navbar for Dark mode.
appearance
- Type:
boolean | 'dark' | 'force-dark'
- Default:
true
Whether to enable dark mode.
- If this option is set to
true
, the default theme will be determined by the user's preferred color scheme. - If this option is set to
dark
, the theme will be dark by default unless the user manually toggles it. - If this option is set to
false
, the user will not be able to switch themes. - If this option is set to
force-dark
, the user will not be able to switch themes, and the theme will be forced to dark.
This option injects an inline script that restores user settings from local storage. This ensures [data-theme="dark"]
is applied before the page is rendered to avoid flashing.
profile
- Type:
ProfileOptions
- Default:
{}
- Details: Configure the site owner's personal information.
profile.avatar
: Avatar URL, used for displaying blogger information on the right.profile.name
: Name, used for displaying blogger information on the right.profile.description
: Personal description, used for displaying blogger information on the right.profile.circle
: Whether the avatar is circular.profile.location
: User's geographical location.profile.organization
: User's organization/company.profile.layout
: Whether to display personal information on the left or right,'left' | 'right'
.
Example:
export default defineUserConfig({
theme: plumeTheme({
profile: {
avatar: '/avatar.jpg',
name: 'Zhang San',
description: 'Here is no silver three hundred two, next door Wang Er never stole',
circle: true,
location: 'Hangzhou, China',
organization: 'XXX Company',
layout: 'right',
}
})
})
social
Type:
false | SocialLink[]
Default:
false
Details: Personal social information configuration.
Displayed as icon links on the far right of the navbar.
Available icon options:
'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 }
: Custom icon, pass the SVG source string. The optionalname
field is used to configurenavbarSocialInclude
.
Example:
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
Type:
string[]
Default:
['github', 'twitter', 'discord', 'facebook']
Details:
Social links allowed to be displayed in the navbar. This configuration is only effective on PC.
If
social
is configured as{ svg: string, name: string}
, thenname
can be used as a value fornavbarSocialInclude
.
navbar
Type:
NavItem[]
Default:
[]
Details: Navbar configuration.
To configure navbar elements, you can set it to a navbar array, where each element is a
string
or aNavItem
object.- A
NavItem
object should have atext
field and alink
field, with an optionalactiveMatch
field. - A
string
represents a page file path or a page access path.
- A
type NavItem = string | {
text: string
link: string
/**
* The page prefix for the current group.
*/
prefix?: string
/**
* Navigation items under this group.
*/
items?: NavItem[]
/**
* Supports iconify icons. Use the iconify name directly and it will be loaded automatically.
*
* @see https://icon-sets.iconify.design/
*/
icon: string
/**
* Controls when the element is active.
*/
activeMatch?: string
}
Example 1:
export default defineUserConfig({ theme: plumeTheme({ navbar: [ // NavbarItem { text: 'Foo', link: '/foo/' }, // NavbarGroup { text: 'Group', prefix: '/group/', items: ['foo/', 'bar/'], }, // String - page file path '/bar', // The `.md` extension can be omitted directly. ], }), })
Example 2:
export default defineUserConfig({ theme: plumeTheme({ navbar: [ // Nested Group - maximum depth is 2 { text: 'Group', items: [ { text: 'SubGroup', items: ['/group/sub/', '/group/sub/bar/'], }, ], }, // Control when the element is active { text: 'Group 2', items: [ { text: 'Always active', link: '/', // This element will always be active activeMatch: '/', }, { text: 'Active on /foo/', link: '/not-foo/', // This element is active when the current route path starts with /foo/ // Supports regular expressions activeMatch: '^/foo/', }, ], }, ], }), })
collections
Type:
ThemeCollectionItem[]
Default:
[]
Details: Documentation collections configuration.
sidebar
Type:
false | SidebarMulti
Details:
Sidebar configuration. The theme recommends configuring the sidebar in collections configuration.
The
key
of the configuration object is the common access path prefix for the sidebar.For
value
:'auto'
means automatically generate the sidebar based on the directory structure.string
represents the page file path corresponding to the sidebar.SidebarItem
represents a single sidebar item configuration.
type ThemeIcon = string | { svg: string }
type SidebarMulti = Record<
string,
| 'auto'
| (string | SidebarItem)[]
| { items: 'auto' | (string | SidebarItem)[], prefix?: string }
>
interface SidebarItem {
/**
* Sidebar text.
*/
text?: string
/**
* Sidebar link.
*/
link?: string
/**
* Sidebar icon.
*/
icon?: ThemeIcon
/**
* Nested sidebar group.
*/
items?: 'auto' | (string | SidebarItem)[]
/**
* If not specified, the group is not collapsible.
* If `true`, the group is collapsible and collapsed by default.
* If `false`, the group is collapsible but expanded by default.
*/
collapsed?: boolean
/**
* Link prefix for the current group.
*/
prefix?: string
rel?: string
target?: string
}
sidebarScrollbar
Type:
boolean
Default:
true
Details: Whether to show the sidebar scrollbar.
When set to
false
, only the scrollbar is hidden, but the scrolling behavior remains unchanged.
aside
Type:
boolean | 'left'
Default:
true
Details:
Whether to display the aside (right sidebar).
false
disables the right aside.true
enables the right aside.'left'
moves the right aside to the left side of the article content, to the right of the main sidebar.
Each page can override this global configuration via frontmatter aside.
outline
Type:
false | number | [number, number] | 'deep'
Default:
[2, 3]
Details:
The heading levels to display.
A single number means only display headings of that level.
If a tuple is passed, the first number is the minimum level and the second is the maximum level.
'deep'
is the same as[2, 6]
, which displays all headings from<h2>
to<h6>
.When aside is disabled,
outline
is also disabled.Each page can override this global configuration via frontmatter outline.
transition
Type:
boolean | TransitionOptions
Default:
true
Details:
Whether to enable transition animations.
When passing a
boolean
,true
enables andfalse
disables.An object can also be passed for specific configuration, as shown below.
interface TransitionOptions { /** * Whether to enable page transition animations. * @default true */ page?: boolean /** * Whether to enable blog post list transition animations. * @default true */ postList?: boolean /** * Whether to enable dark/light mode switch transition animations, * or configure the transition animation type. * @default 'fade' */ appearance?: boolean | 'fade' | 'circle-clip' | 'horizontal-clip' | 'vertical-clip' | 'skew-clip' }
footer
- Type:
false | { message: string; copyright: string }
- Default:
false
- Details: Footer configuration.
bulletin
Type:
boolean | BulletinOptions
Default:
false
Details: Bulletin board configuration.
For details, please refer to Bulletin Board.
editLinkPattern
Type:
string
Default:
''
Details: Regular expression for the edit link.
Example:
':repo/edit/:branch/:path'
copyright
Type:
boolean | CopyrightLicense | CopyrightOptions
Default:
false
Details: Copyright configuration.
For details, please refer to Copyright.
prevPage
- Type:
boolean
- Default:
true
- Details: Whether to show the previous page link.
nextPage
- Type:
boolean
- Default:
true
- Details: Whether to show the next page link.
createTime
Type:
boolean | 'only-posts'
Default:
true
Details: Whether to display the creation time.
false
- Do not display.'only-posts'
- Only display on blog post list pages.true
- Display on all article pages.