Frontmatter Config Reference

Complete reference for VitePress page-level frontmatter configuration

Frontmatter Config Reference

Frontmatter enables page-based configuration. Use YAML frontmatter at the top of any markdown file to override site-level or theme-level options.

---
title: My Page Title
description: My page description
layout: doc
---

# Content starts here

Access frontmatter data via the $frontmatter global in Vue expressions: {{ $frontmatter.title }}

Site Metadata

These options override site-level configuration for individual pages.

title

title · string

Title for the page. Overrides site-level title.

This becomes the page’s <title> tag and is combined with titleTemplate if configured.

---
title: Getting Started
---

titleTemplate

titleTemplate · string | boolean

The suffix for the title. Overrides site-level titleTemplate.

Use :title as a placeholder for the page’s main title. Set to false to disable the suffix.

---
title: API Reference
titleTemplate: Developer Docs
---

description

description · string

Description for the page. Overrides site-level description.

Renders as a <meta name="description"> tag.

---
description: Learn how to get started with VitePress
---

head

head · HeadConfig[]

Additional head tags to inject for the current page. Appended after site-level head tags.

Show Type Definition

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

---
head:
  - - meta
    - name: og:title
      content: My Page Title
  - - meta
    - name: og:description
      content: My page description
---

Layout

Control the page layout and structure.

layout

layout · 'doc' | 'home' | 'page' · default: "doc"

Determines the layout of the page.

• doc: Default documentation styles applied to markdown content
• home: Special layout for home/landing pages with hero and features sections
• page: Similar to doc but no styles applied - fully custom page

doc

---
layout: doc
---

# Regular Documentation Page

This page uses the default doc layout with sidebar and outline.

home

---
layout: home

hero:
  name: VitePress
  text: Vite & Vue powered static site generator
  tagline: Simple, powerful, and fast
  actions:
    - theme: brand
      text: Get Started
      link: /quickstart
    - theme: alt
      text: View on GitHub
      link: https://github.com/vuejs/vitepress

features:
  - icon: ⚡️
    title: Vite-Powered
    details: Lightning fast hot module replacement
  - icon: 🎨
    title: Customizable
    details: Theming support with custom components
---

page

---
layout: page
---

<div class="custom-page">
  <h1>Fully Custom Page</h1>
  <p>No default styles applied.</p>
</div>

hero

hero · Hero

home layout only

Defines the hero section content when layout is set to home.

Show Hero Configuration

---
layout: home

hero:
  name: VitePress
  text: Vite & Vue powered static site generator
  tagline: Simple, powerful, and fast
  image:
    src: /logo.svg
    alt: VitePress Logo
  actions:
    - theme: brand
      text: Get Started
      link: /quickstart
    - theme: alt
      text: View on GitHub
      link: https://github.com/vuejs/vitepress
---

Hero Options:

• name: Main heading (large text)
• text: Secondary heading
• tagline: Subheading/tagline
• image: Hero image (string or { src, alt } object)
• actions: Array of action buttons
  • theme: 'brand' | 'alt' | 'sponsor'
  • text: Button text
  • link: Button link

features

features · Feature[]

home layout only

Defines feature items to display when layout is set to home.

Show Features Configuration

---
layout: home

features:
  - icon: ⚡️
    title: Vite-Powered
    details: Lightning fast hot module replacement and build times
    link: /guide/why-vitepress
  
  - icon: 📝
    title: Markdown-Powered
    details: Focus on your content with minimal configuration
    link: /concepts/markdown
  
  - icon:
      src: /custom-icon.svg
      alt: Custom Icon
    title: Customizable
    details: Full theming support with Vue components
    link: /guide/customization
---

Feature Options:

• icon: Emoji string or { src, alt } object for image
• title: Feature title
• details: Feature description
• link: Optional link URL
• linkText: Optional custom link text
• rel: Optional rel attribute for link
• target: Optional target attribute for link

Navigation & Sidebar

navbar

navbar · boolean · default: "true"

Whether to display the navbar on this page.

---
navbar: false
---

sidebar

sidebar · boolean · default: "true"

Whether to display the sidebar on this page.

---
sidebar: false
---

aside

aside · boolean | 'left' · default: "true"

Controls the aside (table of contents) rendering.

• false: No aside
• true: Aside to the right
• 'left': Aside to the left

Overrides theme-level aside.

---
aside: left
---

outline

outline · number | [number, number] | 'deep' | false · default: "2"

The levels of headers to display in the outline.

• Number: Single level (e.g., 2 for only <h2>)
• Array: Range (e.g., [2, 4] for <h2> to <h4>)
• 'deep': All levels from <h2> to <h6> (equivalent to [2, 6])
• false: Disable outline

Overrides the level from theme-level outline.

Single Level

---
outline: 3
---

Footer & Navigation

footer

footer · boolean · default: "true"

Whether to display the footer on this page.

Overrides theme-level footer.

---
footer: false
---

editLink

editLink · boolean · default: "true"

Whether to display the edit link in the footer of this page.

Overrides theme-level editLink.

---
editLink: false
---

lastUpdated

lastUpdated · boolean | Date · default: "true"

Whether to display the last updated timestamp in the footer.

If a Date object is provided, it will be displayed instead of the Git timestamp.

Disable

---
lastUpdated: false
---

prev

prev · string | boolean | { text: string; link: string }

Customize or disable the previous page link in the doc footer.

• String: Use as link text with auto-detected URL
• Boolean false: Disable previous link
• Object: Fully customize text and link

Text Only

---
prev: 'Installation Guide'
---

next

next · string | boolean | { text: string; link: string }

Customize or disable the next page link in the doc footer.

Same options as prev.

Text Only

---
next: 'Advanced Configuration'
---

Styling

pageClass

pageClass · string

Add an extra CSS class name to this specific page for custom styling.

---
pageClass: custom-page-class
---

Then style it in .vitepress/theme/custom.css:

.custom-page-class {
  /* page-specific styles */
  background: linear-gradient(to bottom, #f0f0f0, #ffffff);
}

.custom-page-class h1 {
  color: #ff6600;
}

Special Flags

isHome

isHome · boolean

Force the page to be treated as the home page by the theme.

Useful when using a custom layout but wanting home page elements to appear.

---
layout: page
isHome: true
---

SEO & Social

While not built-in frontmatter options, you can add custom frontmatter and use it with hooks:

---
title: My Page
image: /images/og-image.jpg
author: John Doe
date: 2024-01-15
tags:
  - guide
  - tutorial
---

Access in your theme or via transformPageData:

// .vitepress/config.ts
export default {
  transformPageData(pageData) {
    pageData.frontmatter.head ??= []
    
    if (pageData.frontmatter.image) {
      pageData.frontmatter.head.push([
        'meta',
        { property: 'og:image', content: pageData.frontmatter.image }
      ])
    }
  }
}

Example: Complete Frontmatter

Here’s a comprehensive example showing many options together:

---
# Metadata
title: Complete Configuration Guide
description: A comprehensive guide to configuring VitePress
head:
  - - meta
    - property: og:type
      content: article
  - - meta
    - name: twitter:card
      content: summary_large_image

# Layout
layout: doc
aside: left
outline: [2, 3]

# Navigation
navbar: true
sidebar: true

# Footer
footer: true
editLink: true
lastUpdated: true

prev:
  text: 'Installation'
  link: '/guide/installation'

next:
  text: 'Advanced Features'
  link: '/guide/advanced'

# Styling
pageClass: config-guide-page

# Custom fields (accessible via $frontmatter)
author: VitePress Team
date: 2024-01-15
tags:
  - configuration
  - guide
  - advanced
---

# Your content here

Accessing Frontmatter

In Markdown

Use the $frontmatter global:

Author: {{ $frontmatter.author }}
Published: {{ $frontmatter.date }}

In Vue Components

Use the useData() composable:

<script setup>
import { useData } from 'vitepress'

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

<template>
  <div>Author: {{ frontmatter.author }}</div>
</template>

In Config Hooks

Access via the pageData parameter:

export default {
  async transformPageData(pageData) {
    console.log(pageData.frontmatter)
    
    // Modify or augment frontmatter
    pageData.frontmatter.processedDate = new Date(
      pageData.frontmatter.date
    ).toLocaleDateString()
  }
}