首页布局

home 是 VanillaPress 提供的首页布局示例，用于展示如何通过 frontmatter 驱动一个更自由的页面结构。它在 .vp-header 内通过 {{{ slots.header }}} 复用站点通用响应式 header。内置模板和样式由已安装的 vanilla-press 依赖包提供。

启用方式

在页面 frontmatter 中声明：

YAML
layout: home

通常首页文件会放在语言目录的 index.md 中，例如：

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

完整示例

YAML
---layout: hometitle: 首页keywords: vanilla-press, markdown-it, 静态文档description: VanillaPress 是基于 markdown-it 和 vanilla-jui 的轻量静态文档生成器。layouts:  home:    hero:      badge: vanilla press      title: 轻量、优雅的静态文档生成器      description: 基于 `markdown-it` 的静态文档脚手架，按需引用功能和组件，最小化构建 JavaScript 运行时。      hint: 内置多语言、搜索、SEO、主题模式等常用功能。      actions:        - text: 快速开始          link: ./guide/quick-start.html          variant: is-solid        - text: 查看组件          link: ./guide/components.html          variant: is-soft    quickStart:      title: 快速开始      groups:        - title: 创建并安装          lines:            - npm create vanilla-press@latest my-docs            - cd my-docs            - npm install            - npm run dev    features:      title: 为什么选择 VanillaPress      description: 保留静态部署的简单性，提供必要的运行时增强。      items:        - index: 1          title: 原生运行时          description: 不绑定 React 或 Vue，页面输出简单，适合低依赖、易部署的文档项目。    cta:      title: 从首页布局开始定制      description: 当前页面使用 layout: home 和 layouts.home 变量生成，可作为自定义布局模板的参考。      actions:        - text: 阅读指南          link: ./guide/quick-start.html          variant: is-solid---

home 布局的变量全部放在 layouts.home 下。模板内部通过 {{ layout.hero.title }}、{{ layout.features.title }} 这类写法读取当前布局变量。

Hero 区域

hero 控制首页首屏左侧内容。

actions 中常用字段：

快速开始区域

quickStart 控制首屏右侧代码卡片。

YAML
quickStart:  title: 快速开始  groups:    - title: 创建并安装      lines:        - npm create vanilla-press@latest my-docs        - cd my-docs        - npm install        - npm run dev

每个 groups 项会渲染为一个命令分组。lines 是字符串数组，模板会逐行输出到代码块中。

特性区域

features 控制首页中段的卡片列表。

YAML
features:  title: 为什么选择 VanillaPress  description: 保留静态部署的简单性，提供必要的运行时增强。  items:    - index: 1      title: 原生运行时      description: 不绑定 React 或 Vue，页面输出简单。

items 中的每一项会渲染为一张卡片。index 用于卡片左上角的编号，也可以换成短文本。

CTA 区域

cta 控制首页底部行动区。

YAML
cta:  title: 从首页布局开始定制  description: 当前页面使用 layout: home 和 layouts.home 变量生成。  actions:    - text: 阅读指南      link: ./guide/quick-start.html      variant: is-solid

Markdown 正文

home 模板仍然保留了 {{{ content }}} 插槽，但默认样式中隐藏了 .vp-home-content。这样页面仍可以保留少量 Markdown 正文，供搜索索引、SEO 或后续自定义模板复用。

如果你希望首页显示 Markdown 正文，可以覆盖 home 布局样式：

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

与默认布局的区别

home 布局只在 .vp-header 内使用通用头部插槽 {{{ slots.header }}}，不使用默认文档页的 {{{ slots.headerDocNav }}}、侧边栏、右侧目录和分页导航。即使 vp/config/runtime.ts 中开启了 server.prevNext，首页也不会渲染分页导航，因为 home 模板没有声明 <div data-vp-prev-next></div> 插槽。

如果你基于 home 复制出一个新的落地页布局，并希望显示分页导航，可以在模板中手动加入：

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

自定义样式

内置 home 样式包含背景光效、玻璃卡片、按钮动效、代码卡片、特性卡片 hover 效果和 CTA 渐变。你可以新增 vp/layouts/home/ 后按项目需要修改：

项目侧同名布局会覆盖内置布局，适合在不修改生成器源码的情况下定制首页。