frontmatter
Auto-generating Frontmatter
This feature automatically generates frontmatter for each Markdown file.
What is Frontmatter?
Frontmatter is a metadata block written in YAML format at the very beginning of a Markdown file. You can think of it as the "ID card" or "configuration manual" of the Markdown file. It won't be rendered into the web page content directly, but is used to configure relevant parameters for the file.
Frontmatter is wrapped using three dashes (---) and located at the very start of the file:
---
title: Post Title
createTime: 2026/01/15 15:03:10
---
Here is the Markdown content...The current theme supports auto-generated frontmatter including:
title: Article title, generated based on the file namecreateTime: Article creation time, generated based on the file creation timepermalink: Article permalink- Uses
nanoidto generate an 8-character random string by default - Can be set to
filepathto generate based on the file path
- Uses
Rule Priority
The priority of frontmatter generation from highest to lowest is:
- Manual Configuration: Frontmatter fields manually written in the Markdown file will not be automatically overwritten
- Collection Configuration: Frontmatter rules configured for a specific collection in
collections - Default Rules: Theme's built-in default generation rules
Configuration
Global Configuration
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
// autoFrontmatter: true, // Theme built-in configuration
autoFrontmatter: {
title: true, // Auto-generate title
createTime: true, // Auto-generate creation time
permalink: true, // Auto-generate permalink
}
})
})import { defineThemeConfig } from 'vuepress-theme-plume'
export default defineThemeConfig({
// autoFrontmatter: true, // Theme built-in configuration
autoFrontmatter: {
title: true, // Auto-generate title
createTime: true, // Auto-generate creation time
permalink: true, // Auto-generate permalink
}
})Collection Configuration
You can configure autoFrontmatter separately for each collection.
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
collections: [
{
type: 'doc',
dir: 'guide',
title: 'Guide',
// autoFrontmatter: true, // Theme built-in configuration
autoFrontmatter: {
title: true, // Auto-generate title
createTime: true, // Auto-generate creation time
permalink: true, // Auto-generate permalink
}
}
]
})
})import { defineThemeConfig } from 'vuepress-theme-plume'
export default defineThemeConfig({
collections: [
{
type: 'doc',
dir: 'guide',
title: 'Guide',
// autoFrontmatter: true, // Theme built-in configuration
autoFrontmatter: {
title: true, // Auto-generate title
createTime: true, // Auto-generate creation time
permalink: true, // Auto-generate permalink
}
}
]
})Custom Processing Logic
Use transform(data, context, locale) to configure custom processing logic. data is the frontmatter data, context is the file context, and locale is the current language path.
transform()can also be an async function, returning a Promise.transform()is applicable in both global configuration and collection configuration.
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
autoFrontmatter: {
title: true, // Auto-generate title
createTime: true, // Auto-generate creation time
permalink: true, // Auto-generate permalink
transform: (data, context, locale) => { // Custom transform
// context.filePath // File absolute path
// context.relativePath // File relative path, relative to source directory
// context.content // Markdown content
data.foo ??= 'foo'
return data
}
}
})
})import { defineThemeConfig } from 'vuepress-theme-plume'
export default defineThemeConfig({
autoFrontmatter: {
title: true, // Auto-generate title
createTime: true, // Auto-generate creation time
permalink: true, // Auto-generate permalink
transform: (data, context, locale) => { // Custom transform
// context.filePath // File absolute path
// context.relativePath // File relative path, relative to source directory
// context.content // Markdown content
data.foo ??= 'foo'
return data
}
}
})Interface
interface AutoFrontmatterContext {
/**
* File absolute path
*/
filepath: string
/**
* File relative path
*/
relativePath: string
/**
* File markdown content
*/
content: string
}
interface AutoFrontmatterOptions {
/**
* Whether to auto-generate permalink
*
* - `false`: Do not auto-generate permalink
* - `true`: Auto-generate permalink, using nanoid to generate an 8-digit random string
* - `filepath`: Generate permalink based on file path
*
* @default true
*/
permalink?: boolean | 'filepath'
/**
* Whether to auto-generate createTime
*
* Reads the file creation time by default. `createTime` is more precise to the second than VuePress's default `date` time.
*/
createTime?: boolean
/**
* Whether to auto-generate title
*
* Reads the file name as the title by default.
*/
title?: boolean
/**
* Custom frontmatter generation function
*
* - You should add new fields directly to `data`
* - If a completely new `data` object is returned, it will overwrite the previous frontmatter
* @param data Existing frontmatter on the page
* @param context Context information of the current page
* @param locale Current language path
* @returns Returns the processed frontmatter
*/
transform?: (data: AutoFrontmatterData, context: AutoFrontmatterContext, locale: string) => AutoFrontmatterData | Promise<AutoFrontmatterData>
}Permalink
The theme uses nanoid to generate an 8-character random string as the file's permalink by default.
You can also configure permalink as 'filepath' to generate the permalink based on the file path. Please note, if your file path contains Chinese characters, the theme recommends installing pinyin-pro in your project to support converting Chinese to pinyin.
Changing permalink changes the URL of every existing article
The value of autoFrontmatter.permalink determines the access path of already-generated articles. After changing it, the URL of every article using an auto-generated link will change, and previously published links, external references and search-engine-indexed addresses will break (404). This is not reversible.
Be careful when changing it on a production site. If you only want to adjust the link of a few articles, specify permalink manually in that article's frontmatter to lock it — it takes precedence over the auto-generated link:
---
title: My Article
permalink: /custom/my-article/
---npm i pinyin-propnpm add pinyin-proyarn add pinyin-proimport { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
autoFrontmatter: {
permalink: 'filepath',
}
})
})import { defineThemeConfig } from 'vuepress-theme-plume'
export default defineThemeConfig({
autoFrontmatter: {
permalink: 'filepath',
}
})Example:
---
title: Service
permalink: /blog/service/
------
title: Capital
permalink: /blog/capital/
---You probably noticed that in the example, the permalink for the capital.md file is /blog/capital/, which is incorrect. This is because pinyin-pro's default dictionary cannot accurately identify polyphonic characters. If you need a more precise conversion result,you can manually install @pinyin-pro/data, and the theme will automatically load this dictionary to improve accuracy.
npm i @pinyin-pro/datapnpm add @pinyin-pro/datayarn add @pinyin-pro/data---
title: Capital
permalink: /blog/capital/
---