Skip to main content

​
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
---
  • 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: 
---
title: API Reference
titleTemplate: Developer Docs
---
Result: API Reference | Developer Docs

​
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">
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:
Standard documentation layout with:
  • Sidebar navigation
  • Table of contents
  • Edit link
  • Last updated timestamp
---
layout: doc
---

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

​
outline

Type: number | [number, number] | 'deep' | false
Default: 2 Control which heading levels appear in the outline: 
---
outline: 3
---
Shows h2 and h3 headings

​
lastUpdated

Type: boolean | Date
Default: true Control the last updated timestamp display: 
---
lastUpdated: false
---
When true, VitePress uses Git commit timestamps. When a Date is provided, it’s displayed instead.
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

1

Be Consistent

Use consistent frontmatter structure across similar pages:
# All guide pages
---
title: Page Title
description: Brief description
category: Guide
---
2

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

Use Meaningful Defaults

Set sensible site-level defaults, override only when needed:
# Only override when different from site default
---
editLink: false
---
4

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.

Build docs developers (and LLMs) love

Get started for freeTalk to us