frontmatter
约 1274 字大约 4 分钟
2026-01-15
自动生成 frontmatter
主题 自动为每个 Markdown 文件生成 frontmatter。
什么是 frontmatter ?
Frontmatter(前言)是在 Markdown 文件最开头部分使用 YAML 格式编写的元数据区块。 你可以把它想象成 Markdown 文件的“身份证”或“配置说明书”,它不会被直接渲染成网页内容,而是用于配置该文件的相关参数。
Frontmatter 使用三个连字符(---)包裹,位于文件的最开头:
---
title: Post Title
createTime: 2026/01/15 15:03:10
---
这里是 Markdown 正文内容...当前主题支持自动生成的 frontmatter 包括:
title: 文章标题,根据文件名生成createTime: 文章创建时间,根据文件创建时间生成permalink: 文章链接- 默认使用
nanoid生成 8 位随机字符串 - 可以设置为
filepath根据文件路径生成
- 默认使用
配置
全局配置
.vuepress/config.ts
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
// autoFrontmatter: true, // 主题内置配置
autoFrontmatter: {
title: true, // 自动生成标题
createTime: true, // 自动生成创建时间
permalink: true, // 自动生成永久链接
}
})
}).vuepress/plume.config.ts
import { defineThemeConfig } from 'vuepress-theme-plume'
export default defineThemeConfig({
// autoFrontmatter: true, // 主题内置配置
autoFrontmatter: {
title: true, // 自动生成标题
createTime: true, // 自动生成创建时间
permalink: true, // 自动生成永久链接
}
})集合配置
可以给每一个集合单独配置 autoFrontmatter
.vuepress/config.ts
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
collections: [
{
type: 'doc',
dir: 'guide',
title: '指南',
// autoFrontmatter: true, // 主题内置配置
autoFrontmatter: {
title: true, // 自动生成标题
createTime: true, // 自动生成创建时间
permalink: true, // 自动生成永久链接
}
}
]
})
}).vuepress/plume.config.ts
import { defineThemeConfig } from 'vuepress-theme-plume'
export default defineThemeConfig({
collections: [
{
type: 'doc',
dir: 'guide',
title: '指南',
// autoFrontmatter: true, // 主题内置配置
autoFrontmatter: {
title: true, // 自动生成标题
createTime: true, // 自动生成创建时间
permalink: true, // 自动生成永久链接
}
}
]
})自定义处理逻辑
使用 transform(data, context, locale) 配置自定义处理逻辑,data 为 frontmatter 数据,context 为文件上下文,locale 为当前语言路径。
transform()也可以是异步函数,返回 Promise。transform()适用于 全局配置 和 集合配置 中。
.vuepress/config.ts
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
autoFrontmatter: {
title: true, // 自动生成标题
createTime: true, // 自动生成创建时间
permalink: true, // 自动生成永久链接
transform: (data, context, locale) => { // 自定义转换
// context.filePath // 文件绝对路径
// context.relativePath // 文件相对路径,相对于源目录
// context.content // markdown 正文内容
data.foo ??= 'foo'
return data
}
}
})
}).vuepress/plume.config.ts
import { defineThemeConfig } from 'vuepress-theme-plume'
export default defineThemeConfig({
autoFrontmatter: {
title: true, // 自动生成标题
createTime: true, // 自动生成创建时间
permalink: true, // 自动生成永久链接
transform: (data, context, locale) => { // 自定义转换
// context.filePath // 文件绝对路径
// context.relativePath // 文件相对路径,相对于源目录
// context.content // markdown 正文内容
data.foo ??= 'foo'
return data
}
}
})Interface
interface AutoFrontmatterContext {
/**
* 文件绝对路径
*/
filepath: string
/**
* 文件相对路径
*/
relativePath: string
/**
* 文件 markdown 内容
*/
content: string
}
interface AutoFrontmatterOptions {
/**
* 是否自动生成 permalink
*
* - `false`: 不自动生成 permalink
* - `true`: 自动生成 permalink ,使用 nanoid 生成 8 位数随机字符串
* - `filepath`: 根据文件路径生成 permalink
*
* @default true
*/
permalink?: boolean | 'filepath'
/**
* 是否自动生成 createTime
*
* 默认读取 文件创建时间,`createTime` 比 vuepress 默认的 `date` 时间更精准到秒
*/
createTime?: boolean
/**
* 是否自动生成 title
*
* 默认读取文件名作为标题
*/
title?: boolean
/**
* 自定义 frontmatter 生成函数
*
* - 你应该直接将新字段添加到 `data` 中
* - 如果返回全新的 `data` 对象,会覆盖之前的 frontmatter
* @param data 页面已存在的 frontmatter
* @param context 当前页面的上下文信息
* @param locale 当前语言路径
* @returns 返回处理后的 frontmatter
*/
transform?: (data: AutoFrontmatterData, context: AutoFrontmatterContext, locale: string) => AutoFrontmatterData | Promise<AutoFrontmatterData>
}永久链接 permalink
主题默认使用 nanoid 生成一个 8 位的随机字符串作为文件的永久链接。
还可以将 permalink 配置为 'filepath' ,根据文件路径生成永久链接。 请注意,如果你的文件路径中,包含中文,主题建议在你的项目中安装 pinyin-pro , 以支持将中文转换为拼音。
pnpm
pnpm add pinyin-proyarn
yarn add pinyin-pronpm
npm i pinyin-pro.vuepress/config.ts
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
autoFrontmatter: {
permalink: 'filepath',
}
})
}).vuepress/plume.config.ts
import { defineThemeConfig } from 'vuepress-theme-plume'
export default defineThemeConfig({
autoFrontmatter: {
permalink: 'filepath',
}
})示例:
docs
blog
服务.md
都城.md
docs/blog/服务.md
---
title: 服务
permalink: /blog/wu-fu/
---docs/blog/都城.md
---
title: 都城
permalink: /blog/dou-cheng/
---你应该已经发现 示例中的 都城.md 文件的 permalink 为 /blog/dou-cheng/ ,这显然是错误的,这是因为 pinyin-pro 默认的词库对于多音字并不能精确的识别,如果你需要更为精确的转换结果,可以手动安装 @pinyin-pro/data, 主题为自动加载该词库,以提高精度。
pnpm
pnpm add @pinyin-pro/datayarn
yarn add @pinyin-pro/datanpm
npm i @pinyin-pro/datadocs/blog/都城.md
---
title: 都城
permalink: /blog/du-cheng/
---