Configuration Guide
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.tsvuepress.config.jsvuepress.config.mjs
In the source directory (sourceDir):
.vuepress/config.tsRecommended.vuepress/config.js.vuepress/config.mjs
Basic Configuration Example:
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:
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:
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:
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:
---
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
