Frontmatter Configuration

Frontmatter enables page-based configuration in VitePress. Every markdown file can use YAML frontmatter to override site-level or theme-level options.

Usage

VitePress parses YAML frontmatter using gray-matter. Place frontmatter at the top of your markdown file:

---
title: My Documentation Page
description: A comprehensive guide to our API
layout: doc
---

# Content starts here

Frontmatter must be at the very top of the file, before any elements including <script> tags.

Accessing Frontmatter Data

In Markdown

Access frontmatter via the $frontmatter global:

---
title: User Guide
author: Jane Smith
date: 2024-01-15
---

# {{ $frontmatter.title }}

By {{ $frontmatter.author }} on {{ $frontmatter.date }}

In Vue Components

Use the useData() helper in <script setup>:

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

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

<template>
  <div>
    <h1>{{ frontmatter.title }}</h1>
    <p>Last updated: {{ frontmatter.date }}</p>
  </div>
</template>

Site Configuration Fields

These fields override site-level configuration for individual pages.

title

Type: string Title for the page. Overrides the site-level title.

---
title: API Reference
---

How Title Generation Works

If title is set, it’s used as the page title
Combined with titleTemplate to generate the full <title> tag
Example: API Reference | My Docs

titleTemplate

Type: string | boolean Customize the title suffix or format for this page:

Custom Suffix
Custom Format
Disable Suffix

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

Result: API Reference | Developer Docs

---
title: API Reference
titleTemplate: ':title - Developer Portal'
---

Result: API Reference - Developer Portal

---
title: API Reference
titleTemplate: false
---

Result: API Reference

description

Type: string Page description for SEO. Renders as a <meta> tag:

---
title: Getting Started
description: Learn how to set up and configure VitePress in under 5 minutes
---

Generates:

<meta name="description" content="Learn how to set up and configure VitePress in under 5 minutes">

head

Type: HeadConfig[] Inject additional tags into the <head> section:

---
head:
  - - meta
    - name: keywords
      content: vitepress, documentation, vue
  - - meta
    - property: og:image
      content: https://example.com/image.png
  - - link
    - rel: canonical
      href: https://example.com/guide
---

The HeadConfig type is defined as:

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

Default Theme Fields

These options are specific to VitePress’s default theme.

layout

Type: 'doc' | 'home' | 'page'
Default: 'doc' Determines the page layout:

doc
home
page

Standard documentation layout with:

Sidebar navigation
Table of contents
Edit link
Last updated timestamp

---
layout: doc
---

Landing page layout for hero sections:

---
layout: home
hero:
  name: VitePress
  text: Vite & Vue powered static site generator
  actions:
    - theme: brand
      text: Get Started
      link: /quickstart
features:
  - title: Simple and Minimal
    details: Markdown-centered project structure
  - title: Fast
    details: Powered by Vite
---

Blank layout with no default styling:

---
layout: page
---

Perfect for fully custom pages.

hero

For home layout only Define the hero section on home pages. See Default Theme: Home Page for all options.

features

For home layout only Define feature items on home pages. See Default Theme: Home Page for all options. Type: boolean
Default: true Show or hide the navigation bar on this page:

---
navbar: false
---

Type: boolean
Default: true Show or hide the sidebar on this page:

---
sidebar: false
---

Useful for landing pages or full-width content.

aside

Type: boolean | 'left'
Default: true Control the table of contents aside component:

---
aside: false
---

---
aside: true
---

---
aside: left
---

outline

Type: number | [number, number] | 'deep' | false
Default: 2 Control which heading levels appear in the outline:

Single Level
Range
Deep
Disable

---
outline: 3
---

Shows h2 and h3 headings

---
outline: [2, 4]
---

Shows h2, h3, and h4 headings

---
outline: deep
---

Shows all heading levels (h2-h6)

---
outline: false
---

No outline shown

lastUpdated

Type: boolean | Date
Default: true Control the last updated timestamp display:

---
lastUpdated: false
---

---
lastUpdated: 2024-01-15
---

When true, VitePress uses Git commit timestamps. When a Date is provided, it’s displayed instead.

editLink

Type: boolean
Default: true Show or hide the edit link in the page footer:

---
editLink: false
---

Type: boolean
Default: true Show or hide the footer on this page:

---
footer: false
---

pageClass

Type: string Add custom CSS classes to the page wrapper:

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

Then style in your theme:

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

.custom-page-class .content {
  max-width: 1200px;
}

isHome

Type: boolean Force home page elements in custom layouts:

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

This is primarily used internally. Most users won’t need this field.

Custom Frontmatter Fields

Define your own frontmatter fields for custom functionality:

---
title: API Documentation
author: Jane Smith
tags: [api, reference, advanced]
difficulty: intermediate
estimatedTime: 15 min
---

Access custom fields in components:

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

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

<template>
  <div class="metadata">
    <span class="author">{{ frontmatter.author }}</span>
    <span class="difficulty">{{ frontmatter.difficulty }}</span>
    <span class="time">{{ frontmatter.estimatedTime }}</span>
  </div>
</template>

Alternative Formats

VitePress also supports JSON frontmatter:

---
{
  "title": "API Reference",
  "description": "Complete API documentation",
  "tags": ["api", "reference"]
}
---

TypeScript Support

Define types for custom frontmatter:

// types/frontmatter.d.ts
import { DefaultTheme } from 'vitepress'

declare module 'vitepress' {
  interface PageData {
    frontmatter: DefaultTheme.Config['frontmatter'] & {
      author?: string
      tags?: string[]
      difficulty?: 'beginner' | 'intermediate' | 'advanced'
      estimatedTime?: string
    }
  }
}

Best Practices

Be Consistent

Use consistent frontmatter structure across similar pages:

# All guide pages
---
title: Page Title
description: Brief description
category: Guide
---

Optimize for SEO

Always include title and description for better search rankings:

---
title: How to Deploy VitePress to Netlify
description: Step-by-step guide for deploying your VitePress site to Netlify with automatic builds and custom domains
---

Use Meaningful Defaults

Set sensible site-level defaults, override only when needed:

# Only override when different from site default
---
editLink: false
---

Document Custom Fields

Maintain a reference for custom frontmatter fields your team uses

Reference Implementation

Frontmatter parsing is handled by the @mdit-vue/plugin-frontmatter package. See src/node/markdown/markdown.ts:344 for integration details.

For a complete list of default theme frontmatter options, see the Frontmatter Config Reference.

Getting Started

Core Concepts

Customization

Advanced

Frontmatter Configuration

Frontmatter Configuration

Usage

Accessing Frontmatter Data

In Markdown

In Vue Components

Site Configuration Fields

title

titleTemplate

description

head

Default Theme Fields

layout

hero

features

navbar

sidebar

aside

outline

lastUpdated

editLink

footer

pageClass

isHome

Custom Frontmatter Fields

Alternative Formats

TypeScript Support

Best Practices

Reference Implementation

​Frontmatter Configuration

​Usage

​Accessing Frontmatter Data

​In Markdown

​In Vue Components

​Site Configuration Fields

​title

​titleTemplate

​description

​head

​Default Theme Fields

​layout

​hero

​features

​navbar

​sidebar

​aside

​outline

​lastUpdated

​editLink

​footer

​pageClass

​isHome

​Custom Frontmatter Fields

​Alternative Formats

​TypeScript Support

​Best Practices

​Reference Implementation

Frontmatter Configuration

Usage

Accessing Frontmatter Data

In Markdown

In Vue Components

Site Configuration Fields

title

titleTemplate

description

head

Default Theme Fields

layout

hero

features

navbar

sidebar

aside

outline

lastUpdated

editLink

footer

pageClass

isHome

Custom Frontmatter Fields

Alternative Formats

TypeScript Support

Best Practices

Reference Implementation