Home Layout

home is the homepage layout example provided by VanillaPress. It shows how to drive a freer page structure from frontmatter. It reuses the shared responsive site header through {{{ slots.header }}} inside .vp-header. The built-in template and styles are shipped by the installed vanilla-press package.

Enable It

Declare the layout in page frontmatter:

YAML
layout: home

Homepage files are usually placed at index.md inside each language directory, for example:

Markdown
docs/zh/index.mddocs/en/index.md

Complete Example

YAML
---layout: hometitle: Homekeywords: vanilla-press, markdown-it, static docsdescription: VanillaPress is a lightweight static documentation generator built with markdown-it and vanilla-jui.layouts:  home:    hero:      badge: vanilla press      title: Lightweight, elegant static documentation generator      description: A markdown-it based static documentation scaffold that loads features and components on demand and keeps the generated JavaScript runtime small.      hint: Built-in multilingual support, search, SEO, theme modes, and other common documentation features.      actions:        - text: Quick Start          link: ./guide/quick-start.html          variant: is-solid        - text: View Components          link: ./guide/components.html          variant: is-soft    quickStart:      title: Quick Start      groups:        - title: Create and Install          lines:            - npm create vanilla-press@latest my-docs            - cd my-docs            - npm install            - npm run dev    features:      title: Why VanillaPress      description: Keep static deployment simple while adding the runtime enhancements a documentation site needs.      items:        - index: 1          title: Native Runtime          description: No React or Vue runtime binding. The output stays simple and works well for low-dependency documentation projects.    cta:      title: Start customizing from the home layout      description: This page is generated with layout: home and layouts.home variables, and can be used as a reference for custom layout templates.      actions:        - text: Read the Guide          link: ./guide/quick-start.html          variant: is-solid---

All variables for the home layout are placed under layouts.home. Inside the template, values are read with expressions such as {{ layout.hero.title }} and {{ layout.features.title }}.

Hero Area

hero controls the left side of the homepage first screen.

Common fields in actions:

Quick Start Area

quickStart controls the code card on the right side of the first screen.

YAML
quickStart:  title: Quick Start  groups:    - title: Create and Install      lines:        - npm create vanilla-press@latest my-docs        - cd my-docs        - npm install        - npm run dev

Each groups item renders as a command group. lines is an array of strings, and the template outputs each line into the code block.

Features Area

features controls the card list in the middle of the homepage.

YAML
features:  title: Why VanillaPress  description: Keep static deployment simple while adding the runtime enhancements a documentation site needs.  items:    - index: 1      title: Native Runtime      description: No React or Vue runtime binding. The output stays simple.

Each item in items renders as a card. index is used as the card number in the upper-left corner, and can also be replaced with short text.

CTA Area

cta controls the action area near the bottom of the homepage.

YAML
cta:  title: Start customizing from the home layout  description: This page is generated with layout: home and layouts.home variables.  actions:    - text: Read the Guide      link: ./guide/quick-start.html      variant: is-solid

Markdown Content

The home template still keeps a {{{ content }}} slot, but .vp-home-content is hidden by default. This lets the page keep a small amount of Markdown content for the search index, SEO, or later template reuse.

If you want the homepage to show Markdown content, override the home layout style:

CSS
.vp-home-content {  display: block;}

Difference from the Default Layout

The home layout only uses the shared header slot {{{ slots.header }}} inside .vp-header. It does not use the default documentation {{{ slots.headerDocNav }}}, sidebar, right-side table of contents, or previous/next navigation. Even if server.prevNext is enabled in vp/config/runtime.ts, the homepage will not render previous/next navigation because the home template does not declare a <div data-vp-prev-next></div> slot.

If you copy home into a new landing-page layout and want to show previous/next navigation, add the slot manually:

HTML
<div data-vp-prev-next></div>

Custom Styles

The built-in home styles include background light effects, glass cards, button motion, code cards, feature card hover effects, and a CTA gradient. You can add vp/layouts/home/ and customize it for your project:

A project layout with the same name overrides the built-in layout, which is useful for customizing the homepage without modifying generator source code.