Custom VitePress Homepage Layout (Hero + Features Grid)

Tested on: VitePress 1.6.3, Vue 3.4

docs/index.md

---
layout: home
title: My Docs
titleTemplate: false

hero:
  name: "My Docs"
  text: "Build faster with copy-paste guides"
  tagline: Battle-tested configs, not theory
  image:
    src: /logo.svg
    alt: Logo
  actions:
    - theme: brand
      text: Get Started
      link: /guide/getting-started
    - theme: alt
      text: GitHub
      link: https://github.com/org/repo

features:
  - icon: 🚀
    title: Fast
    details: Static export, edge CDN, sub-second TTFB.
  - icon: 📦
    title: Zero backend
    details: Pure HTML after build.
  - icon: 🔍
    title: Search built-in
    details: Local search, no Algolia queue.
---

Custom Vue section

.vitepress/theme/index.ts:

import DefaultTheme from 'vitepress/theme'
import HomeShowcase from './components/HomeShowcase.vue'
import './custom.css'

export default {
  ...DefaultTheme,
  enhanceApp({ app }) {
    app.component('HomeShowcase', HomeShowcase)
  }
}

CSS tweaks

.VPHero .name { font-size: 3.2rem; }
.VPFeatures { margin-top: 4rem; }
.dark .VPHero .text { color: var(--vp-c-text-1); }

Errors

layout: home ignored

Blank lines before front matter ---.

hero image 404

Use /logo.svg from docs/public/, not relative ./logo.svg.

Verify

npm run docs:dev
npm run docs:build && npm run docs:preview

Lighthouse homepage Performance 98.

Result

Bounce rate 62% → 41% via Get Started CTA.