Frontmatter 配置

Frontmatter 是 Markdown 文件顶部的 YAML 格式配置块，用于设置页面级别的配置，会覆盖站点级和主题级的同名配置。

快速参考

所有 Frontmatter 字段一览：

字段	类型	默认值	说明
`title`	`string`	文件名	页面标题
`titleTemplate`	`string \| boolean`	继承站点配置	标题后缀模板
`description`	`string`	继承站点描述	页面描述（SEO）
`head`	`HeadConfig[]`	—	页面级 head 标签
`lang`	`string`	继承站点语言	页面语言
`layout`	`'doc' \| 'home' \| 'page'`	`'doc'`	页面布局类型
`hero`	`HeroConfig`	—	首页 Hero 区域配置
`features`	`FeatureConfig[]`	—	首页特性展示
`navbar`	`boolean`	`true`	是否显示导航栏
`sidebar`	`boolean \| SidebarConfig`	`true`	侧边栏配置
`aside`	`boolean \| 'left'`	`true`	右侧大纲位置
`outline`	`number \| false \| OutlineConfig`	`2`	大纲显示级别
`lastUpdated`	`boolean`	继承站点配置	是否显示最后更新时间
`editLink`	`boolean`	继承站点配置	是否显示编辑链接
`prev`	`NavLink \| false`	自动推断	上一篇链接
`next`	`NavLink \| false`	自动推断	下一篇链接
`pageClass`	`string`	—	页面自定义 CSS 类
`heroImage`	`string`	—	OG 图像 URL

基础用法

yaml

---
title: 页面标题
description: 页面描述
---

基础配置

title

类型： string
默认值： 文件名（首字母大写）

页面标题，会覆盖站点默认标题，显示在浏览器标签页和导航栏中。

yaml

---
title: 快速开始
---

标题与一级标题的区别

Frontmatter 的 title 设置的是页面元数据标题（显示在标签页和 SEO 中），而 Markdown 的 # 一级标题 是页面内容中的标题。两者通常保持一致。

titleTemplate

类型： string | boolean
默认值： 继承站点配置

标题后缀模板，设为 false 可禁用标题后缀。

yaml

---
title: 快速开始
titleTemplate: false  # 不显示后缀，标签页仅显示 "快速开始"
---

yaml

---
title: 快速开始
titleTemplate: ' - 我的博客'  # 标签页显示 "快速开始 - 我的博客"
---

description

类型： string
默认值： 继承站点描述

页面描述，用于 SEO <meta name="description"> 和社交分享（OG 标签），建议 150-160 个字符。

yaml

---
description: 学习如何快速搭建 VitePress 站点，5 分钟完成从安装到部署的完整流程
---

head

类型： HeadConfig[]
默认值： 无

页面级 <head> 标签，会与站点级 head 合并。

yaml

---
head:
  - - meta
    - name: keywords
      content: VitePress, 教程, 快速开始
  - - meta
    - property: og:image
      content: /images/og-guide.png
  - - link
    - rel: canonical
      href: https://example.com/guide/
---

HeadConfig 格式说明：

格式	说明	示例
`[标签名, 属性对象]`	自闭合标签	`['meta', { name: 'keywords', content: '...' }]`
`[标签名, 属性对象, 内联内容]`	带内容的标签	`['script', { type: 'application/ld+json' }, '{"@type":"Article"}']`

lang

类型： string
默认值： 继承站点 lang 配置

页面语言，设置 <html lang> 属性，对 SEO 和屏幕阅读器很重要。

yaml

---
lang: zh-CN
---

布局配置

layout

类型： 'doc' | 'home' | 'page'
默认值： 'doc'

页面布局类型，决定页面的整体结构：

布局	侧边栏	大纲	说明
`doc`	✅	✅	文档页面（默认），带侧边栏和右侧大纲
`home`	❌	❌	首页布局，配合 `hero` 和 `features` 使用
`page`	❌	❌	简单页面，无侧边栏，适合自定义内容

yaml

---
layout: home  # 首页布局
---

yaml

---
layout: doc   # 文档布局（带侧边栏）
---

yaml

---
layout: page  # 简单页面（无侧边栏）
---

hero

类型： HeroConfig
默认值： 无
仅 layout: home 时生效

首页 Hero 区域配置。

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
---

HeroConfig 字段详解：

字段	类型	说明
`name`	`string`	Hero 标题名称（带品牌色高亮）
`text`	`string`	Hero 主标题
`tagline`	`string`	副标题/标语
`image`	`HeroImageConfig`	Hero 图片配置
`actions`	`HeroActionConfig[]`	操作按钮列表

HeroImageConfig 字段详解：

字段	类型	说明
`src`	`string`	图片路径（必需）
`alt`	`string`	图片 alt 文本
`width`	`string`	图片宽度，如 `'300px'`
`height`	`string`	图片高度，如 `'200px'`

HeroActionConfig 字段详解：

字段	类型	说明
`theme`	`'brand' \| 'alt'`	按钮样式，`brand` 为主色，`alt` 为次要
`text`	`string`	按钮文本
`link`	`string`	链接地址

features

类型： FeatureConfig[]
默认值： 无
仅 layout: home 时生效

首页特性展示区域，每行显示 3 个特性卡片（移动端自动堆叠）。

yaml

---
layout: home
features:
  - title: 极速开发
    details: Vite 驱动，毫秒级热更新
    icon: 🚀
  - title: 灵活主题
    details: CSS 变量覆盖，轻松定制
    icon: 🎨
  - title: 开箱即用
    details: 内置 Markdown 扩展和搜索
    icon: 📦
---

FeatureConfig 字段详解：

字段	类型	说明
`title`	`string`	特性标题
`details`	`string`	特性描述（支持 Markdown）
`icon`	`string`	图标（Emoji 或 SVG）
`link`	`string`	点击跳转链接
`linkText`	`string`	链接文本，默认 `'Learn more'`
`rel`	`string`	链接 `rel` 属性
`target`	`string`	链接 `target` 属性

导航配置

类型： boolean
默认值： true

是否显示导航栏。设为 false 可隐藏当前页面的导航栏。

yaml

---
navbar: false  # 隐藏导航栏，适用于全屏展示页
---

类型： boolean | SidebarConfig
默认值： true

侧边栏配置。设为 false 隐藏侧边栏，也可自定义当前页面的侧边栏内容。

yaml

---
sidebar: false  # 隐藏侧边栏
---

yaml

---
sidebar:
  - text: 指南
    items:
      - text: 介绍
        link: /guide/
      - text: 安装
        link: /guide/installation
---

aside

类型： boolean | 'left'
默认值： true

右侧大纲（aside）位置配置。

值	效果
`true`	大纲显示在右侧（默认）
`false`	隐藏大纲
`'left'`	大纲显示在左侧

yaml

---
aside: false   # 隐藏大纲
aside: left    # 大纲显示在左侧
---

outline

类型： number | false | OutlineConfig
默认值： 2

大纲显示级别和配置。

yaml

---
outline: 3     # 显示 h2 和 h3
outline: false # 隐藏大纲
outline:
  level: [2, 4]  # 显示 h2 到 h4
  label: 目录
---

OutlineConfig 字段详解：

字段	类型	默认值	说明
`level`	`number \| [number, number]`	`2`	大纲级别，`3` 等同于 `[2, 3]`
`label`	`string`	`'On this page'`	大纲标题文本

SEO 配置

lastUpdated

类型： boolean
默认值： 继承站点配置

是否显示最后更新时间。需站点级启用 lastUpdated: true 并配置 Git。

yaml

---
lastUpdated: true   # 显示最后更新时间
lastUpdated: false  # 隐藏最后更新时间
---

editLink

类型： boolean
默认值： 继承站点配置

是否显示"编辑此页"链接。

yaml

---
editLink: false  # 隐藏编辑链接，适用于自动生成的页面
---

prev / next

类型： NavLink | false
默认值： 自动推断（按侧边栏顺序）

上一篇/下一篇导航链接。默认按侧边栏配置自动推断，可手动指定或禁用。

yaml

---
prev:
  text: 安装指南
  link: /guide/installation
next:
  text: 配置说明
  link: /guide/configuration
---

yaml

---
prev: false  # 禁用上一篇
next: false  # 禁用下一篇
---

NavLink 字段详解：

字段	类型	说明
`text`	`string`	链接文本
`link`	`string`	链接路径

外观配置

pageClass

类型： string
默认值： 无

为页面添加自定义 CSS 类，便于针对性定制样式。

yaml

---
pageClass: custom-page
---

css

/* .vitepress/theme/style.css */
.custom-page {
  /* 自定义样式 */
  background-color: var(--vp-c-bg-soft);
}

注意

pageClass 添加在 <div class="page"> 上，CSS 选择器需包含 .page 前缀：

css

/* ✅ 正确 */
.custom-page .content {
  max-width: 960px;
}

/* ❌ 错误：作用域不对 */
.custom-page {
  max-width: 960px;
}

heroImage

类型： string
默认值： 无

用于 OG（Open Graph）图像的 Hero 图片 URL，社交分享时显示。

yaml

---
heroImage: /images/hero-og.png
---

自定义数据

Frontmatter 支持任意自定义字段，可在 Vue 组件中通过 useData() 访问：

yaml

---
title: 我的文章
author: 张三
date: 2026-05-09
tags:
  - VitePress
  - 教程
difficulty: Beginner
category: 指南
---

在组件中访问自定义数据：

vue

<script setup lang="ts">
import { useData } from 'vitepress'

const { frontmatter } = useData()
</script>

<template>
  <div class="article-meta">
    <p>作者：{{ frontmatter.author }}</p>
    <p>难度：{{ frontmatter.difficulty }}</p>
    <p>分类：{{ frontmatter.category }}</p>
    <div class="tags">
      <span v-for="tag in frontmatter.tags" :key="tag" class="tag">
        {{ tag }}
      </span>
    </div>
  </div>
</template>

自定义数据的用途

文章元数据：作者、日期、分类、标签
页面定制：自定义布局开关、组件 props
SEO 增强：自定义 OG 标签、结构化数据
数据加载器：createContentLoader 可读取 frontmatter 用于列表生成

完整示例

文档页面

yaml

---
title: 快速开始
titleTemplate: ' - VitePress 学习指南'
description: 5 分钟快速搭建你的第一个 VitePress 站点
head:
  - - meta
    - name: keywords
      content: VitePress, 快速开始, 教程
layout: doc
aside: true
outline: [2, 3]
lastUpdated: true
editLink: true
prev:
  text: 什么是 VitePress
  link: /guide/what-is-vitepress
next:
  text: 安装
  link: /guide/installation
pageClass: guide-page
---

# 快速开始

页面内容...

首页

yaml

---
layout: home
hero:
  name: VitePress
  text: 静态站点生成器
  tagline: 快速、简洁、强大
  image:
    src: /logo.svg
    alt: VitePress Logo
  actions:
    - theme: brand
      text: 快速开始
      link: /guide/
    - theme: alt
      text: GitHub
      link: https://github.com/vuejs/vitepress
features:
  - title: 极速开发
    details: Vite 驱动，毫秒级热更新
    icon: 🚀
  - title: 灵活主题
    details: CSS 变量覆盖，完全定制
    icon: 🎨
  - title: 开箱即用
    details: 内置 Markdown 扩展和搜索
    icon: 📦
---

类型定义

interface FrontmatterConfig {
  // 基础配置
  title?: string
  titleTemplate?: string | boolean
  description?: string
  head?: HeadConfig[]
  lang?: string

  // 布局配置
  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
}

interface HeroConfig {
  name?: string
  text?: string
  tagline?: string
  image?: HeroImageConfig
  actions?: HeroActionConfig[]
}

interface HeroImageConfig {
  src: string
  alt?: string
  width?: string
  height?: string
}

interface HeroActionConfig {
  theme: 'brand' | 'alt'
  text: string
  link: string
}

interface FeatureConfig {
  title: string
  details: string
  icon?: string
  link?: string
  linkText?: string
  rel?: string
  target?: string
}

interface OutlineConfig {
  level?: number | [number, number]
  label?: string
}

interface NavLink {
  text: string
  link: string
}

type HeadConfig =
  | [string, Record<string, string>]
  | [string, Record<string, string>, string]

参考链接

站点配置 - 全局配置选项
主题配置 - 主题配置选项
运行时 API - 在组件中访问 Frontmatter
构建 API - 构建 API 参考
VitePress 官方 Frontmatter 文档

Frontmatter 配置 ​

快速参考 ​

基础用法 ​

基础配置 ​

title ​

titleTemplate ​

description ​

head ​

lang ​

布局配置 ​

layout ​

hero ​

features ​

导航配置 ​

navbar ​

sidebar ​

aside ​

outline ​

SEO 配置 ​

lastUpdated ​

editLink ​

prev / next ​

外观配置 ​

pageClass ​

heroImage ​

自定义数据 ​

完整示例 ​

文档页面 ​

首页 ​

类型定义 ​

参考链接 ​

📖 相关文章推荐

贡献者

Frontmatter 配置

快速参考

基础用法

基础配置

title

titleTemplate

description

head

lang

布局配置

layout

hero

features

导航配置

navbar

sidebar

aside

outline

SEO 配置

lastUpdated

editLink

prev / next

外观配置

pageClass

heroImage

自定义数据

完整示例

文档页面

首页

类型定义

参考链接