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

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

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

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

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

'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
home
page

---
layout: doc
---

# Regular Documentation Page

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

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

---
layout: page
---

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

hero

Hero

home layout onlyDefines 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

Feature[]

home layout onlyDefines 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

Whether to display the navbar on this page.

---
navbar: false
---

sidebar

boolean

default:"true"

Whether to display the sidebar on this page.

---
sidebar: false
---

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

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.

---
outline: 3
---

footer

boolean

default:"true"

Whether to display the footer on this page.Overrides theme-level footer.

---
footer: false
---

editLink

boolean

default:"true"

Whether to display the edit link in the footer of this page.Overrides theme-level editLink.

---
editLink: false
---

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.

---
lastUpdated: false
---

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

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

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

Customize or disable the next page link in the doc footer.Same options as prev.

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

Styling

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

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

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()
  }
}

Configuration

Node API

Client API

Frontmatter Config Reference

Frontmatter Config Reference

Site Metadata

title

titleTemplate

description

head

Layout

layout

hero

features

Navigation & Sidebar

navbar

sidebar

aside

outline

Footer & Navigation

footer

editLink

lastUpdated

prev

next

Styling

pageClass

Special Flags

isHome

Example: Complete Frontmatter

Accessing Frontmatter

In Markdown

In Vue Components

In Config Hooks

Build docs developers (and LLMs) love

Configuration

Node API

Client API

​Frontmatter Config Reference

​Site Metadata

​title

​titleTemplate

​description

​head

​Layout

​layout

​hero

​features

​Navigation & Sidebar

​navbar

​sidebar

​aside

​outline

​Footer & Navigation

​footer

​editLink

​lastUpdated

​prev

​next

​Styling

​pageClass

​Special Flags

​isHome

​SEO & Social

​Example: Complete Frontmatter

​Accessing Frontmatter

​In Markdown

​In Vue Components

​In Config Hooks

Build docs developers (and LLMs) love

Frontmatter Config Reference

Site Metadata

title

titleTemplate

description

head

Layout

layout

hero

features

Navigation & Sidebar

navbar

sidebar

aside

outline

Footer & Navigation

footer

editLink

lastUpdated

prev

next

Styling

pageClass

Special Flags

isHome

SEO & Social

Example: Complete Frontmatter

Accessing Frontmatter

In Markdown

In Vue Components

In Config Hooks