Overview

vuepress-theme-plume is a theme developed based on VuePress, and its configuration fully adheres to VuePress's configuration specifications.

VuePress provides three configuration types:

• Site Configuration: The object directly exported from the configuration file (e.g., .vuepress/config.ts)
• Theme Configuration: The parameter object passed to the plumeTheme() function
• Page Configuration: Defined in the page Frontmatter using YAML syntax

VuePress Configuration File

The base configuration file for VuePress is typically .vuepress/config.js, while TypeScript configuration files are also supported. Using .vuepress/config.ts provides more comprehensive type hints.

VuePress resolves configuration files in the following priority order:

In the current working directory (cwd):

• vuepress.config.ts
• vuepress.config.js
• vuepress.config.mjs

In the source directory (sourceDir):

• .vuepress/config.ts Recommended
• .vuepress/config.js
• .vuepress/config.mjs

Basic Configuration Example:

.vuepress/config.ts

import { 
viteBundler
 } from '@vuepress/bundler-vite'
import { 
defineUserConfig
 } from 'vuepress'
import { 
plumeTheme
 } from 'vuepress-theme-plume'

export default 
defineUserConfig
({
  // VuePress Base Configuration
  
lang
: 'zh-CN',
  
title
: 'Hello, VuePress!',
  
description
: 'This is my first VuePress site',
  // ...

  // Use Vite as the bundler
  
bundler
: 
viteBundler
(),

  // Enable the Plume theme
  
theme
: 
plumeTheme
({ 
    // Theme configuration options
    // ...
  }),
})

Theme Configuration File

Typically, we configure the theme in .vuepress/config.ts:

.vuepress/config.ts

import { 
defineUserConfig
 } from 'vuepress'
import { 
plumeTheme
 } from 'vuepress-theme-plume'

export default 
defineUserConfig
({
  
theme
: 
plumeTheme
({
    // Theme configuration
  }),
  // ...
})

However, modifying this file causes the VuePress service to restart and perform a full refresh. For small sites, this process is quick; but for sites with substantial content, each restart requires considerable time.

Frequent configuration file modifications can also easily lead to VuePress service crashes, requiring manual service restarts and severely impacting content writing efficiency.

Solution: Theme Hot-Reload Configuration:

The theme provides a plume.config.ts configuration file. Modifications to this file support hot-reload and do not require restarting the service .

You can configure hot-reload supported fields within it, such as navbar, profile, etc.

Tips

These fields can still be configured within the theme section of the VuePress configuration file, but the settings from the theme configuration file will ultimately be merged into the main configuration.

To avoid data duplication, please do not configure the same field in both locations.

What is Hot-Reload?

Hot-Reload is a development technique that, in the context of VuePress, manifests as:

• Configuration changes take effect immediately without restarting the service; the browser does not refresh the page
• Page modifications take effect immediately; the browser updates content without a full refresh

Configuration Method

Create the plume.config.ts file in the same directory as the VuePress configuration file:

docs

.vuepress

config.ts

plume.config.ts

plume.config.ts

import { 
defineThemeConfig
 } from 'vuepress-theme-plume'
import 
navbar
 from './navbar'

export default 
defineThemeConfig
({
  // Theme configuration
  
profile
: {
    
name
: 'Your name',
  },
  
navbar
,
})

The defineThemeConfig(config) function provides full type hints. Except for plugins, most configurations can be defined in this file.

Notes

• The theme configuration file only supports hot-reload for specific fields.
• Avoid reconfiguring fields in the VuePress configuration file that have already been set in the theme configuration file.

Custom Configuration File Path

If a non-default path is required, it can be specified in the VuePress configuration:

.vuepress/config.ts

import 
path
 from 'node:path'
import { 
defineUserConfig
 } from 'vuepress'
import { 
plumeTheme
 } from 'vuepress-theme-plume'

export default 
defineUserConfig
({
  
theme
: 
plumeTheme
({
    // Custom configuration file path
    
configFile
: 
path
.
join
(
__dirname
, 'custom/config.ts'), 
  }),
})

Not recommended for beginners; custom paths might cause unexpected issues.

Page Configuration

Using the YAML Frontmatter at the top of the page, the theme can be configured individually for each page:

article.md

---
title: Article Title
createTime: 2024/09/08 22:53:34
permalink: /article/xxx/
---

The section wrapped by the --- delimiters at the top of a Markdown file is the Frontmatter, which uses YAML syntax for configuration.

For an introduction to basic YAML syntax, please refer to this blog post

Contributors

pengzhanbo

Changelog

10/9/25, 7:46 AM

View All Changelog

• 38505-docs: update en docs (#708)on 10/9/25
• 4d236-feat(theme)!: add collections support (#704)on 10/7/25
• 0fd6c-refactor(theme): improve types and flat config (#524)on 3/15/25
• c56ba-feat: 全新的文档！on 3/8/24