Homepage Hero

Style a VitePress homepage with a hero section, action buttons, and optional feature cards using the built-in home layout.

When to use

Use this pattern when setting up a VitePress documentation site's landing page. The home layout provides a polished hero section with zero custom CSS — just frontmatter configuration.

The pattern

VitePress's home layout reads structured frontmatter to render a hero area with a name, tagline, call-to-action buttons, and an optional feature grid.

Basic homepage

Create index.md at the site root:

---
layout: home
title: My Project
titleTemplate: Documentation
hero:
  name: My Project
  text: A Short Description
  tagline: One-line summary of what this project does
  actions:
    - theme: brand
      text: Get Started
      link: /guide/
    - theme: alt
      text: GitHub
      link: https://github.com/user/repo
---

Key fields:

• layout: home — activates the homepage layout instead of the default doc layout.
• title — the page <title>, not displayed visually.
• titleTemplate — appended to title in the browser tab (e.g., "My Project | Documentation").
• hero.name — large heading with the VitePress brand color gradient.
• hero.text — secondary heading below the name, white/light text.
• hero.tagline — muted text below the heading pair.
• hero.actions — buttons below the tagline. theme: brand renders the primary button; theme: alt renders a secondary/muted button.

Adding feature cards

Add a features array to show a grid of cards below the hero:

---
layout: home
hero:
  name: My Project
  text: A Short Description
  tagline: What this project does
  actions:
    - theme: brand
      text: Get Started
      link: /guide/
features:
  - icon: 🎯
    title: Feature One
    details: Brief description of this feature
    link: /guide/feature-one
  - icon: 📦
    title: Feature Two
    details: Brief description of this feature
    link: /guide/feature-two
  - icon: ⚡
    title: Feature Three
    details: Brief description of this feature
    link: /guide/feature-three
---

Each feature card supports:

• icon — emoji or image path.
• title — card heading.
• details — short description text.
• link — optional; makes the entire card clickable.

Feature cards work best in groups of 3, 4, or 6 for balanced grid layouts.

Adding content below the hero

Any markdown content after the closing --- renders below the hero and feature sections. This is useful for a quick-start guide or additional context:

---
layout: home
hero:
  name: My Project
  text: Tools for building things
  tagline: Fast and simple
  actions:
    - theme: brand
      text: Browse Docs
      link: /docs/
---

## Quick Start

1. Install the package
2. Run the setup script
3. Open the dashboard

The body content uses standard VitePress doc styling, appearing below the hero area in a centered content column.

Checks

• [ ] layout: home is set in frontmatter
• [ ] Hero renders name, text, and tagline
• [ ] Action buttons link to correct destinations
• [ ] Feature cards (if used) display in a balanced grid
• [ ] Page title and titleTemplate produce a correct browser tab title
• [ ] Content below the frontmatter renders below the hero area
• [ ] Build completes without errors (npm run docs:build)