Default Theme: Home Page

Learn how to configure and customize the home page layout in the VitePress default theme.

Basic Home Page Setup

Enable Home Layout

Set the layout to home in your frontmatter:

markdown

---
layout: home
---

Complete Home Page Example

markdown

---
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
  actions:
    - theme: brand
      text: Get Started
      link: /guide/getting-started
    - theme: alt
      text: View on GitHub
      link: https://github.com/vuejs/vitepress

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

Hero Section Configuration

Basic Hero

markdown

---
layout: home

hero:
  name: "My Project"
  text: "Amazing documentation site"
  tagline: "Build beautiful docs with ease"
---

Hero with Image

markdown

---
layout: home

hero:
  name: "My Project"
  text: "Amazing documentation site"
  tagline: "Build beautiful docs with ease"
  image:
    src: /hero-image.png
    alt: My Project Logo
---

Hero with Background Image

markdown

---
layout: home

hero:
  name: "My Project"
  text: "Amazing documentation site"
  tagline: "Build beautiful docs with ease"
  image:
    src: /hero-bg.jpg
    alt: Background
  style: |
    .VPHero .image {
      background: linear-gradient(45deg, #42b883, #35495e);
    }
---

Hero Actions

markdown

---
layout: home

hero:
  name: "My Project"
  text: "Amazing documentation site"
  actions:
    - theme: brand
      text: Get Started
      link: /guide/
    - theme: alt
      text: View on GitHub
      link: https://github.com/username/repo
    - theme: sponsor
      text: Sponsor
      link: https://github.com/sponsors/username
---

Features Section

Basic Features

markdown

---
layout: home

features:
  - title: Fast
    details: Lightning fast hot reload and build times
  - title: Simple
    details: Minimal configuration required
  - title: Powerful
    details: Full Vue.js support in Markdown
---

Features with Icons

markdown

---
layout: home

features:
  - icon: 🚀
    title: Fast Performance
    details: Built on Vite for lightning-fast development and optimized production builds
  - icon: 📝
    title: Markdown-Centered
    details: Focus on your content with Markdown, enhanced with Vue components
  - icon: 🎨
    title: Customizable
    details: Flexible theming system with full Vue.js component support
---

Features with Custom Icons

markdown

---
layout: home

features:
  - icon:
      src: /icons/performance.svg
      alt: Performance
    title: Optimized Performance
    details: Fast loading times and excellent Core Web Vitals scores
  - icon:
      src: /icons/developer.svg
      alt: Developer Experience
    title: Great DX
    details: Hot module replacement, TypeScript support, and modern tooling
---

Features with Links

markdown

---
layout: home

features:
  - title: Getting Started
    details: Learn the basics and get up and running quickly
    link: /guide/getting-started
    linkText: Start Learning
  - title: API Reference
    details: Complete API documentation with examples
    link: /api/
    linkText: View API
  - title: Examples
    details: Real-world examples and use cases
    link: /examples/
    linkText: Browse Examples
---

Advanced Hero Configuration

Multi-line Hero Text

markdown

---
layout: home

hero:
  name: "VitePress"
  text: |
    Vite & Vue powered
    static site generator
  tagline: Simple, powerful, and performant
---

Hero with Gradient Text

markdown

---
layout: home

hero:
  name: "VitePress"
  text: "Next Generation SSG"
  tagline: "The future of documentation"

style: |
  .VPHero .name {
    background: linear-gradient(135deg, #42b883 0%, #35495e 100%);
    -webkit-background-clip: text;
    -webkit-text-fill-color: transparent;
  }
---

Animated Hero

markdown

---
layout: home

hero:
  name: "VitePress"
  text: "Static Site Generator"
  tagline: "Build amazing documentation sites"

style: |
  .VPHero .name {
    animation: fadeInUp 1s ease-out;
  }
  
  .VPHero .text {
    animation: fadeInUp 1s ease-out 0.2s both;
  }
  
  .VPHero .tagline {
    animation: fadeInUp 1s ease-out 0.4s both;
  }
  
  @keyframes fadeInUp {
    from {
      opacity: 0;
      transform: translateY(30px);
    }
    to {
      opacity: 1;
      transform: translateY(0);
    }
  }
---

Custom Home Page Sections

Adding Custom Sections

markdown

---
layout: home

hero:
  name: "My Project"
  text: "Amazing documentation"

features:
  - title: Feature 1
    details: Description of feature 1
---

## Why Choose Our Solution?

<div class="custom-section">
  <div class="section-content">
    <h3>Built for Developers</h3>
    <p>Our solution is designed with developers in mind, providing the tools and flexibility you need.</p>
  </div>
</div>

## Testimonials

<div class="testimonials">
  <div class="testimonial">
    <blockquote>
      "This tool has revolutionized our documentation workflow."
    </blockquote>
    <cite>— John Doe, Senior Developer</cite>
  </div>
</div>

<style>
.custom-section {
  padding: 48px 24px;
  background: var(--vp-c-bg-soft);
  border-radius: 12px;
  margin: 48px 0;
}

.testimonials {
  display: grid;
  gap: 24px;
  margin: 48px 0;
}

.testimonial {
  padding: 24px;
  border-left: 4px solid var(--vp-c-brand-1);
  background: var(--vp-c-bg-soft);
}

.testimonial blockquote {
  margin: 0 0 16px 0;
  font-style: italic;
  font-size: 18px;
}

.testimonial cite {
  color: var(--vp-c-text-2);
  font-size: 14px;
}
</style>

Styling the Home Page

Custom Hero Styling

css

/* Custom hero styles */
.VPHero {
  padding-top: 120px;
  padding-bottom: 80px;
}

.VPHero .container {
  max-width: 1200px;
}

.VPHero .name {
  font-size: 64px;
  font-weight: 900;
  line-height: 1.1;
  background: linear-gradient(135deg, #42b883 0%, #35495e 100%);
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
}

.VPHero .text {
  font-size: 32px;
  font-weight: 600;
  color: var(--vp-c-text-1);
  margin: 24px 0;
}

.VPHero .tagline {
  font-size: 20px;
  color: var(--vp-c-text-2);
  margin-bottom: 48px;
}

.VPHero .image {
  max-width: 400px;
  margin: 0 auto;
}

.VPHero .actions {
  gap: 16px;
  margin-top: 48px;
}

Custom Features Styling

css

/* Custom features styles */
.VPFeatures {
  padding: 80px 24px;
  background: var(--vp-c-bg-soft);
}

.VPFeatures .container {
  max-width: 1200px;
  margin: 0 auto;
}

.VPFeatures .items {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
  gap: 32px;
}

.VPFeature {
  padding: 32px;
  background: var(--vp-c-bg);
  border-radius: 12px;
  border: 1px solid var(--vp-c-border);
  transition: all 0.3s ease;
}

.VPFeature:hover {
  border-color: var(--vp-c-brand-1);
  transform: translateY(-4px);
  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.1);
}

.VPFeature .icon {
  font-size: 48px;
  margin-bottom: 16px;
  display: block;
}

.VPFeature .title {
  font-size: 20px;
  font-weight: 600;
  margin-bottom: 12px;
  color: var(--vp-c-text-1);
}

.VPFeature .details {
  font-size: 16px;
  line-height: 1.6;
  color: var(--vp-c-text-2);
}

Responsive Design

Mobile-First Hero

css

/* Mobile-first hero design */
.VPHero .name {
  font-size: 32px;
}

.VPHero .text {
  font-size: 20px;
}

.VPHero .tagline {
  font-size: 16px;
}

@media (min-width: 640px) {
  .VPHero .name {
    font-size: 48px;
  }
  
  .VPHero .text {
    font-size: 24px;
  }
  
  .VPHero .tagline {
    font-size: 18px;
  }
}

@media (min-width: 960px) {
  .VPHero .name {
    font-size: 64px;
  }
  
  .VPHero .text {
    font-size: 32px;
  }
  
  .VPHero .tagline {
    font-size: 20px;
  }
}

Responsive Features Grid

css

/* Responsive features grid */
.VPFeatures .items {
  grid-template-columns: 1fr;
  gap: 24px;
}

@media (min-width: 640px) {
  .VPFeatures .items {
    grid-template-columns: repeat(2, 1fr);
    gap: 32px;
  }
}

@media (min-width: 960px) {
  .VPFeatures .items {
    grid-template-columns: repeat(3, 1fr);
  }
}

SEO Optimization

Meta Tags for Home Page

markdown

---
layout: home
title: My Project - The Best Documentation Tool
description: Build amazing documentation sites with My Project. Fast, simple, and powerful static site generator.
head:
  - - meta
    - name: keywords
      content: documentation, static site generator, vue, vite
  - - meta
    - property: og:title
      content: My Project - The Best Documentation Tool
  - - meta
    - property: og:description
      content: Build amazing documentation sites with My Project
  - - meta
    - property: og:image
      content: https://example.com/og-image.jpg
  - - meta
    - property: og:url
      content: https://example.com
  - - meta
    - name: twitter:card
      content: summary_large_image

hero:
  name: "My Project"
  text: "The Best Documentation Tool"
  tagline: "Build amazing documentation sites with ease"
---

Structured Data

markdown

---
layout: home

hero:
  name: "My Project"
  text: "Documentation Tool"

head:
  - - script
    - type: application/ld+json
    - |
      {
        "@context": "https://schema.org",
        "@type": "SoftwareApplication",
        "name": "My Project",
        "description": "Build amazing documentation sites",
        "url": "https://example.com",
        "applicationCategory": "DeveloperApplication",
        "operatingSystem": "Any",
        "offers": {
          "@type": "Offer",
          "price": "0",
          "priceCurrency": "USD"
        }
      }
---

Performance Optimization

Lazy Loading Images

markdown

---
layout: home

hero:
  name: "My Project"
  image:
    src: /hero-image.png
    alt: My Project
    loading: lazy

features:
  - icon:
      src: /icons/feature1.svg
      alt: Feature 1
      loading: lazy
    title: Feature 1
    details: Description
---

Optimized Images

markdown

---
layout: home

hero:
  image:
    src: /hero-image.webp
    alt: My Project
    srcset: |
      /hero-image-320w.webp 320w,
      /hero-image-640w.webp 640w,
      /hero-image-1280w.webp 1280w
    sizes: |
      (max-width: 320px) 280px,
      (max-width: 640px) 600px,
      1200px
---

Accessibility

markdown

---
layout: home

hero:
  name: "My Project"
  text: "Documentation Tool"
  tagline: "Build amazing documentation sites"
  image:
    src: /hero-image.png
    alt: "My Project logo featuring a modern design with blue and green gradients"
  actions:
    - theme: brand
      text: Get Started
      link: /guide/
      ariaLabel: "Get started with My Project documentation"
    - theme: alt
      text: View on GitHub
      link: https://github.com/username/repo
      ariaLabel: "View My Project source code on GitHub"

features:
  - icon: 🚀
    title: Fast Performance
    details: Lightning fast development and build times
    ariaLabel: "Learn about fast performance features"
  - icon: 📝
    title: Markdown-Centered
    details: Focus on content with enhanced Markdown
    ariaLabel: "Learn about Markdown-centered approach"
---

css

/* Keyboard navigation styles */
.VPHero .action:focus,
.VPFeature .link:focus {
  outline: 2px solid var(--vp-c-brand-1);
  outline-offset: 2px;
  border-radius: 4px;
}

.VPHero .action:focus:not(:focus-visible),
.VPFeature .link:focus:not(:focus-visible) {
  outline: none;
}

/* Skip to content link */
.skip-to-content {
  position: absolute;
  top: -40px;
  left: 6px;
  background: var(--vp-c-brand-1);
  color: white;
  padding: 8px;
  text-decoration: none;
  border-radius: 4px;
  z-index: 1000;
}

.skip-to-content:focus {
  top: 6px;
}

Best Practices

Content Guidelines

Clear value proposition - Make it obvious what your project does
Compelling hero text - Use action-oriented language
Benefit-focused features - Focus on user benefits, not just features
Social proof - Include testimonials, stats, or logos

Design Guidelines

Visual hierarchy - Use size, color, and spacing effectively
Consistent branding - Maintain brand consistency throughout
Mobile-first - Design for mobile devices first
Performance - Optimize images and minimize JavaScript

SEO Guidelines

Descriptive titles - Use clear, keyword-rich titles
Meta descriptions - Write compelling meta descriptions
Structured data - Include relevant schema markup
Internal linking - Link to important internal pages

Accessibility Guidelines

Alt text - Provide descriptive alt text for images
Color contrast - Ensure sufficient color contrast
Keyboard navigation - Support keyboard-only users
Screen readers - Use semantic HTML and ARIA labels

Default Theme: Home Page ​

Basic Home Page Setup ​

Enable Home Layout ​

Complete Home Page Example ​

Hero Section Configuration ​

Basic Hero ​

Hero with Image ​

Hero with Background Image ​

Hero Actions ​

Features Section ​

Basic Features ​

Features with Icons ​

Features with Custom Icons ​

Features with Links ​

Advanced Hero Configuration ​

Multi-line Hero Text ​

Hero with Gradient Text ​

Animated Hero ​

Custom Home Page Sections ​

Adding Custom Sections ​

Styling the Home Page ​

Custom Hero Styling ​

Custom Features Styling ​

Responsive Design ​

Mobile-First Hero ​

Responsive Features Grid ​

SEO Optimization ​

Meta Tags for Home Page ​

Structured Data ​

Performance Optimization ​

Lazy Loading Images ​

Optimized Images ​

Accessibility ​

Screen Reader Support ​

Keyboard Navigation ​

Best Practices ​

Content Guidelines ​

Design Guidelines ​

SEO Guidelines ​

Accessibility Guidelines ​

Default Theme: Home Page

Basic Home Page Setup

Enable Home Layout

Complete Home Page Example

Hero Section Configuration

Basic Hero

Hero with Image

Hero with Background Image

Hero Actions

Features Section

Basic Features

Features with Icons

Features with Custom Icons

Features with Links

Advanced Hero Configuration

Multi-line Hero Text

Hero with Gradient Text

Animated Hero

Custom Home Page Sections

Adding Custom Sections

Styling the Home Page

Custom Hero Styling

Custom Features Styling

Responsive Design

Mobile-First Hero

Responsive Features Grid

SEO Optimization

Meta Tags for Home Page

Structured Data

Performance Optimization

Lazy Loading Images

Optimized Images

Accessibility

Screen Reader Support

Keyboard Navigation

Best Practices

Content Guidelines

Design Guidelines

SEO Guidelines

Accessibility Guidelines