Frontmatter

Learn how to use frontmatter to configure pages and add metadata in VitePress.

Basic Frontmatter

YAML Frontmatter

Add frontmatter at the top of your Markdown files:

markdown

---
title: Page Title
description: Page description for SEO
layout: doc
---

# Page Content

Your markdown content goes here.

JSON Frontmatter

You can also use JSON format:

markdown

---
{
  "title": "Page Title",
  "description": "Page description",
  "layout": "doc"
}
---

# Page Content

Page Configuration

Basic Page Options

yaml

---
# Page title (overrides h1)
title: Custom Page Title

# Page description for SEO
description: This page explains how to use frontmatter

# Layout type
layout: doc  # doc, page, home

# Show/hide page title
titleTemplate: false

# Custom head tags
head:
  - - meta
    - name: keywords
      content: vitepress, frontmatter, configuration

# Page-specific navbar
navbar: true

# Page-specific sidebar
sidebar: true

# Show/hide outline
outline: deep  # false, [2,3], deep

# Last updated timestamp
lastUpdated: true

# Edit link
editLink: true

# Previous/next page links
prev: false
next: 
  text: Next Page
  link: /guide/next-page

# Footer
footer: true
---

Layout Types

yaml

---
# Documentation layout (default)
layout: doc

# Home page layout
layout: home

# Custom page layout
layout: page

# Custom layout component
layout: CustomLayout
---

SEO and Meta Tags

Basic SEO

yaml

---
title: Complete Guide to VitePress
description: Learn everything about VitePress, from basic setup to advanced customization
head:
  - - meta
    - name: keywords
      content: vitepress, vue, documentation, static site generator
  - - meta
    - property: og:title
      content: Complete Guide to VitePress
  - - meta
    - property: og:description
      content: Learn everything about VitePress
  - - meta
    - property: og:image
      content: https://example.com/og-image.jpg
  - - meta
    - property: og:url
      content: https://example.com/guide/
  - - meta
    - name: twitter:card
      content: summary_large_image
---

Advanced Meta Tags

yaml

---
head:
  # Canonical URL
  - - link
    - rel: canonical
      href: https://example.com/guide/frontmatter
  
  # Alternate languages
  - - link
    - rel: alternate
      hreflang: en
      href: https://example.com/en/guide/frontmatter
  - - link
    - rel: alternate
      hreflang: zh
      href: https://example.com/zh/guide/frontmatter
  
  # Preload resources
  - - link
    - rel: preload
      href: /fonts/custom-font.woff2
      as: font
      type: font/woff2
      crossorigin: ""
  
  # Custom CSS
  - - link
    - rel: stylesheet
      href: /css/custom-page.css
  
  # Custom JavaScript
  - - script
    - src: /js/custom-page.js
      defer: true
---

Home Page Configuration

Hero Section

yaml

---
layout: home

hero:
  name: VitePress
  text: Vite & Vue powered static site generator
  tagline: Simple, powerful, and performant. Meet the modern SSG framework you've been waiting for.
  image:
    src: /logo-with-shadow.png
    alt: VitePress logo
  actions:
    - theme: brand
      text: Get Started
      link: /guide/getting-started
    - theme: alt
      text: View on GitHub
      link: https://github.com/vuejs/vitepress
---

Features Section

yaml

---
layout: home

features:
  - icon: ⚡️
    title: Vite, The DX that can't be beat
    details: Feel the speed of Vite. Instant server start and lightning fast HMR that stays fast regardless of the app size.
  - icon: 💡
    title: Designed to be simplicity first
    details: With Markdown-centered content, it's built to help you focus on writing and deployed with minimum configuration.
  - icon: 🛠️
    title: Power of Vue meets Markdown
    details: Enhance your content with all the features of Vue in Markdown, while being able to customize your site with Vue.
  - icon: 🔥
    title: Fast by default
    details: Fast site, fast theme with instant navigation. Built on top of Vite for the best DX.
---

yaml

---
# Hide navbar for this page
navbar: false

# Custom previous/next links
prev:
  text: Previous Chapter
  link: /guide/chapter-1
next:
  text: Next Chapter  
  link: /guide/chapter-3

# Custom sidebar for this page
sidebar:
  - text: Introduction
    link: /guide/
  - text: Getting Started
    link: /guide/getting-started
  - text: Configuration
    items:
      - text: Site Config
        link: /guide/site-config
      - text: Theme Config
        link: /guide/theme-config
---

Outline Configuration

yaml

---
# Disable outline
outline: false

# Custom outline levels
outline: [2, 3]

# Deep outline (all levels)
outline: deep

# Custom outline title
outline:
  level: [2, 3]
  label: Page Contents
---

Custom Data

Page-specific Data

yaml

---
# Custom data for use in components
author: John Doe
publishDate: 2024-01-15
category: tutorial
tags:
  - vitepress
  - documentation
  - tutorial
difficulty: beginner
estimatedTime: 15 minutes

# Custom page variables
customData:
  showToc: true
  highlightCode: true
  enableComments: true
---

Using Custom Data

vue

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

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

<template>
  <div v-if="frontmatter.author" class="author-info">
    <p>Author: {{ frontmatter.author }}</p>
    <p>Published: {{ frontmatter.publishDate }}</p>
    <p>Difficulty: {{ frontmatter.difficulty }}</p>
  </div>
  
  <div v-if="frontmatter.tags" class="tags">
    <span 
      v-for="tag in frontmatter.tags" 
      :key="tag" 
      class="tag"
    >
      {{ tag }}
    </span>
  </div>
</template>

Dynamic Frontmatter

Computed Values

yaml

---
title: API Reference
description: Complete API documentation
lastUpdated: true

# Dynamic values using JavaScript
head:
  - - meta
    - property: og:title
      content: !expr `${title} - My Site`
  - - meta
    - property: og:description
      content: !expr `${description} for developers`
---

Environment-based Configuration

yaml

---
title: My Page
description: Page description

# Different configurations for different environments
head: !expr |
  process.env.NODE_ENV === 'production' 
    ? [
        ['meta', { name: 'robots', content: 'index,follow' }],
        ['script', { src: '/analytics.js' }]
      ]
    : [
        ['meta', { name: 'robots', content: 'noindex,nofollow' }]
      ]
---

Validation and Types

TypeScript Support

typescript

// types/frontmatter.d.ts
export interface PageFrontmatter {
  title?: string
  description?: string
  layout?: 'doc' | 'home' | 'page'
  author?: string
  publishDate?: string
  tags?: string[]
  difficulty?: 'beginner' | 'intermediate' | 'advanced'
  customData?: {
    showToc?: boolean
    highlightCode?: boolean
    enableComments?: boolean
  }
}

Frontmatter Validation

javascript

// .vitepress/config.js
export default {
  transformPageData(pageData) {
    // Validate required frontmatter
    if (pageData.relativePath.startsWith('guide/') && !pageData.frontmatter.title) {
      throw new Error(`Missing title in ${pageData.relativePath}`)
    }
    
    // Set default values
    pageData.frontmatter.layout = pageData.frontmatter.layout || 'doc'
    
    return pageData
  }
}

Best Practices

Organization

Keep frontmatter consistent across similar pages
Use meaningful and descriptive titles
Include relevant meta descriptions
Organize custom data logically

Performance

Minimize head tags
Use preload for critical resources
Optimize images referenced in frontmatter
Avoid heavy JavaScript in head

SEO

Always include title and description
Use structured data when appropriate
Implement proper Open Graph tags
Add canonical URLs for duplicate content

Maintainability

Document custom frontmatter fields
Use TypeScript for type safety
Validate frontmatter in build process
Keep frontmatter DRY (Don't Repeat Yourself)

Common Patterns

Blog Posts

yaml

---
title: How to Build Fast Websites
description: Learn the secrets of building lightning-fast websites
author: Jane Developer
publishDate: 2024-01-15
category: web-development
tags:
  - performance
  - optimization
  - web-vitals
readingTime: 8 minutes
featured: true
image: /images/blog/fast-websites.jpg
---

API Documentation

yaml

---
title: User API
description: Complete reference for the User API endpoints
layout: doc
outline: deep
sidebar: true
prev:
  text: Authentication
  link: /api/auth
next:
  text: Posts API
  link: /api/posts
---

Landing Pages

yaml

---
layout: page
title: Product Landing Page
description: Discover our amazing product features
navbar: false
sidebar: false
footer: false
head:
  - - link
    - rel: stylesheet
      href: /css/landing.css
  - - script
    - src: /js/landing.js
      defer: true
---

Frontmatter

Basic Frontmatter

YAML Frontmatter

JSON Frontmatter

Page Configuration

Basic Page Options

Layout Types

SEO and Meta Tags

Basic SEO

Advanced Meta Tags

Home Page Configuration

Hero Section

Features Section

Navigation Configuration

Custom Navigation

Outline Configuration

Custom Data

Page-specific Data

Using Custom Data

Dynamic Frontmatter

Computed Values

Environment-based Configuration

Validation and Types

TypeScript Support

Frontmatter Validation

Best Practices

Organization

Performance

SEO

Maintainability

Common Patterns

Blog Posts

API Documentation

Landing Pages

Frontmatter ​

Basic Frontmatter ​

YAML Frontmatter ​

JSON Frontmatter ​

Page Configuration ​

Basic Page Options ​

Layout Types ​

SEO and Meta Tags ​

Basic SEO ​

Advanced Meta Tags ​

Home Page Configuration ​

Hero Section ​

Features Section ​

Navigation Configuration ​

Custom Navigation ​

Outline Configuration ​

Custom Data ​

Page-specific Data ​

Using Custom Data ​

Dynamic Frontmatter ​

Computed Values ​

Environment-based Configuration ​

Validation and Types ​

TypeScript Support ​

Frontmatter Validation ​

Best Practices ​

Organization ​

Performance ​

SEO ​

Maintainability ​

Common Patterns ​

Blog Posts ​

API Documentation ​

Landing Pages ​

Frontmatter

Basic Frontmatter

YAML Frontmatter

JSON Frontmatter

Page Configuration

Basic Page Options

Layout Types

SEO and Meta Tags

Basic SEO

Advanced Meta Tags

Home Page Configuration

Hero Section

Features Section

Navigation Configuration

Custom Navigation

Outline Configuration

Custom Data

Page-specific Data

Using Custom Data

Dynamic Frontmatter

Computed Values

Environment-based Configuration

Validation and Types

TypeScript Support

Frontmatter Validation

Best Practices

Organization

Performance

SEO

Maintainability

Common Patterns

Blog Posts

API Documentation

Landing Pages