Frontmatter 配置
Frontmatter 是 Markdown 文件顶部的 YAML 格式配置块，用于设置页面级别的配置。
基础用法
yaml
---
title: 页面标题
description: 页面描述
---基础配置
title
- 类型：
string - 默认值：文件名
页面标题，会覆盖站点默认标题。
yaml
---
title: 快速开始
---titleTemplate
- 类型：
string | boolean - 默认值：继承站点配置
标题后缀模板，设为 false 可禁用。
yaml
---
title: 快速开始
titleTemplate: false # 不显示后缀
---
---
title: 快速开始
titleTemplate: ' - 我的博客' # 自定义后缀
---description
- 类型：
string - 默认值：站点描述
页面描述，用于 SEO 和社交分享。
yaml
---
description: 学习如何快速搭建 VitePress 站点
---head
- 类型：
HeadConfig[] - 默认值：无
页面级 head 标签。
yaml
---
head:
- - meta
- name: keywords
content: VitePress, 教程
- - meta
- property: og:image
content: /og-image.png
---布局配置
layout
- 类型：
'doc' | 'home' | 'page' - 默认值：
'doc'
页面布局类型。
yaml
---
layout: home # 首页布局
---
---
layout: doc # 文档布局（带侧边栏）
---
---
layout: page # 简单页面（无侧边栏）
---hero
- 类型：
HeroConfig - 默认值：无
首页 Hero 区域配置，仅 layout: home 时生效。
yaml
---
layout: home
hero:
name: VitePress
text: 快速、简洁的静态站点生成器
tagline: 基于 Vue 和 Vite
image:
src: /logo.svg
alt: VitePress Logo
actions:
- theme: brand
text: 快速开始
link: /guide/what-is-vitepress
- theme: alt
text: GitHub
link: https://github.com/vuejs/vitepress
---features
- 类型：
FeatureConfig[] - 默认值：无
首页特性展示区域，仅 layout: home 时生效。
yaml
---
layout: home
features:
- title: 🚀 极速开发
details: Vite 驱动，毫秒级热更新
- title: 🎨 灵活主题
details: CSS 变量覆盖，轻松定制
- title: 📦 开箱即用
details: 内置 Markdown 扩展和搜索
---导航配置
navbar
- 类型：
boolean - 默认值：
true
是否显示导航栏。
yaml
---
navbar: false # 隐藏导航栏
---sidebar
- 类型：
boolean | SidebarConfig - 默认值：
true
侧边栏配置。
yaml
---
sidebar: false # 隐藏侧边栏
---
---
sidebar:
- text: 指南
items:
- text: 介绍
link: /guide/
---aside
- 类型：
boolean | 'left' - 默认值：
true
右侧大纲位置。
yaml
---
aside: false # 隐藏大纲
aside: left # 大纲显示在左侧
---outline
- 类型：
number | false | OutlineConfig - 默认值：
2
大纲显示级别。
yaml
---
outline: 3 # 显示到 h3
outline: false # 隐藏大纲
outline:
level: 3
label: 目录
---SEO 配置
lastUpdated
- 类型：
boolean - 默认值：继承站点配置
是否显示最后更新时间。
yaml
---
lastUpdated: true
---editLink
- 类型：
boolean - 默认值：继承站点配置
是否显示编辑链接。
yaml
---
editLink: false # 隐藏编辑链接
---prev / next
- 类型：
NavLink | false - 默认值：自动推断
上一篇/下一篇链接。
yaml
---
prev:
text: 上一页
link: /guide/installation
next:
text: 下一页
link: /guide/configuration
---
---
prev: false # 禁用上一篇
next: false # 禁用下一篇
---外观配置
pageClass
- 类型：
string - 默认值：无
为页面添加自定义 CSS 类。
yaml
---
pageClass: custom-page
---css
/* .vitepress/theme/style.css */
.custom-page {
background-color: #f5f5f5;
}heroImage
- 类型：
string - 默认值：无
Hero 图片，用于 OG 图像。
yaml
---
heroImage: /hero.png
---自定义数据
Frontmatter 支持自定义字段，可在组件中访问：
yaml
---
title: 我的文章
author: 张三
date: 2026-04-04
tags:
- VitePress
- 教程
difficulty: Beginner
---在组件中访问：
vue
<script setup>
import { useData } from 'vitepress'
const { frontmatter } = useData()
</script>
<template>
<div>
<p>作者：{{ frontmatter.author }}</p>
<p>难度：{{ frontmatter.difficulty }}</p>
<p v-for="tag in frontmatter.tags" :key="tag">{{ tag }}</p>
</div>
</template>完整示例
yaml
---
title: 快速开始
titleTemplate: ' - VitePress 学习指南'
description: 5 分钟快速搭建你的第一个 VitePress 站点
head:
- - meta
- name: keywords
content: VitePress, 快速开始, 教程
layout: doc
hero:
name: 快速开始
text: 5 分钟上手
lastUpdated: true
editLink: true
pageClass: guide-page
author: VitePress 学习指南
date: 2026-04-04
tags:
- 入门
- 教程
---
# 快速开始
页面内容...类型定义
ts
interface FrontmatterConfig {
// 基础配置
title?: string
titleTemplate?: string | boolean
description?: string
head?: HeadConfig[]
// 布局配置
layout?: 'doc' | 'home' | 'page'
hero?: HeroConfig
features?: FeatureConfig[]
// 导航配置
navbar?: boolean
sidebar?: boolean | SidebarConfig
aside?: boolean | 'left'
outline?: number | false | OutlineConfig
// SEO 配置
lastUpdated?: boolean
editLink?: boolean
prev?: NavLink | false
next?: NavLink | false
// 外观配置
pageClass?: string
heroImage?: string
// 自定义字段
[key: string]: any
}参考链接
- 站点配置 - 全局配置选项
- 主题配置 - 主题配置选项
- VitePress 官方 Frontmatter 文档