VitePress 默认主题首页Home Page布局完整配置指南Hero、Features 与自定义内容【免费下载链接】vitepressVite Vue powered static site generator.项目地址: https://gitcode.com/gh_mirrors/vi/vitepressVitePress 默认主题内置了一套开箱即用的首页Home Page布局通过layout: home即可在任意页面启用再配合hero、features等前置元数据frontmatter选项就能搭建出包含品牌主视觉、行动按钮、特性卡片与自由 Markdown 内容的落地页。本文以docs/en/reference/default-theme-home-page.md为骨架结合仓库源码与类型定义系统讲解首页布局的每一个配置项、渲染链路与样式定制技巧读完即可在项目中直接落地一套完整的首页。启用首页布局layout: homeVitePress 默认主题将首页布局应用在本站首页上见 docs/en/index.md。你可以在任何页面的 frontmatter 配置 中通过layout: home启用它--- layout: home ---不过仅此一项并不会产生太多效果。要让首页真正丰富起来还需要通过hero、features等选项为页面添加多个预制区块。从源码看这些区块最终由 VPHome.vue 按固定顺序组装home-hero-before 插槽 └─ VPHomeHero Hero 区块品牌名、标语、图片、行动按钮 home-hero-after 插槽 home-features-before 插槽 └─ VPHomeFeatures Features 区块特性卡片网格 home-features-after 插槽 └─ VPHomeContent 前置元数据分隔线---以下的 Markdown 内容其中VPHomeHero、VPHomeFeatures组件会分别读取frontmatter.hero与frontmatter.features只要前置元数据中不存在对应键相应区块就不会渲染VPHomeHero.vue、VPHomeFeatures.vue 中均以v-iffm.hero/v-iffm.features守卫。Hero 区块品牌首屏视觉Hero 区块位于首页顶部是访客最先看到的品牌区域。下面是一个完整的 Hero 配置示例--- layout: home hero: name: VitePress text: Vite Vue powered static site generator. tagline: Lorem ipsum... image: src: /logo.png alt: VitePress actions: - theme: brand text: Get Started link: /guide/what-is-vitepress - theme: alt text: View on GitHub link: https://example.com ---对应的 TypeScript 类型定义如下该定义同时体现在 VPHero.vue 的 props 上interface Hero { // 显示在 text 上方的字符串自带品牌色期望较短如产品名。 name?: string // Hero 区块的主文本会被渲染为 h1 标签。 text: string // 显示在 text 下方的标语。 tagline?: string // 显示在文本与标语区域旁边的图片。 image?: ThemeableImage // 首页 Hero 区块中展示的操作按钮。 actions?: HeroAction[] } type ThemeableImage | string | { src: string; alt?: string } | { light: string; dark: string; alt?: string } interface HeroAction { // 按钮配色主题默认 brand。 theme?: brand | alt // 按钮上的文字。 text: string // 按钮的跳转地址。 link: string // 链接的 target 属性。 target?: string // 链接的 rel 属性。 rel?: string }各字段的要点说明字段必填说明name否显示在text上方的品牌名默认使用品牌色渲染通常较短如产品名text是Hero 主标题渲染为h1标签tagline否主标题下方的标语/副文案image否与文本并排展示的图片支持字符串路径、{ src, alt }或{ light, dark, alt }三种形态actions否操作按钮数组每个按钮可配置themebrand/alt、text、link、target、relHero 图片的浅色/深色适配ThemeableImage的第三种形态{ light, dark }允许你为浅色与深色主题分别提供图片。该逻辑由 VPImage.vue 实现它会同时渲染两张图再通过 CSS 规则html:not(.dark) .VPImage.dark { display: none }与html.dark .VPImage.light { display: none }按当前主题显示其中一张。图片路径统一经withBase处理后指向站点根目录即public目录下的静态资源因此示例中的/logo.png实际对应public/logo.png。源码视角Hero 的渲染链路从组件调用链看Hero 区块的渲染路径为VPHome.vue→VPHomeHero.vue→ VPHero.vue。在 VPHero.vue 中可以看到几个关键实现细节name、text、tagline均通过v-html渲染并以dirauto自动适配文字方向RTL 站点也可正常显示name使用span.clip包裹配合-webkit-background-clip: text实现渐变文字效果每个action渲染为一个 VPButton.vuetheme决定按钮配色组件支持home-hero-info-before、home-hero-image等具名插槽便于自定义主题时扩展。此外Hero 图片背景还暴露了两个样式变量--vp-home-hero-image-background-image与--vp-home-hero-image-filter定义于 vars.css默认分别为none可在全局样式中覆写为渐变或滤镜为图片添加圆形光晕等装饰效果。自定义 name 颜色与渐变效果VitePress 默认使用品牌色--vp-c-brand-1渲染name该值定义于 vars.css:root { --vp-home-hero-name-color: var(--vp-c-brand-1); --vp-home-hero-name-background: transparent; }你可以通过覆写--vp-home-hero-name-color变量来改变品牌名的颜色:root { --vp-home-hero-name-color: blue; }更进一步可以组合--vp-home-hero-name-background给name添加渐变效果。实现原理是将文字颜色设为透明再以背景渐变配合background-clip: text将渐变裁剪进文字笔画内对应 VPHero.vue 中.clip类的样式:root { --vp-home-hero-name-color: transparent; --vp-home-hero-name-background: -webkit-linear-gradient(120deg, #bd34fe, #41d1ff); }VitePress 官网首页的品牌名渐变即由此实现。需要注意的是渐变方向参数如120deg与颜色可以任意调整但务必同时设置--vp-home-hero-name-color: transparent否则渐变会被不透明的文字颜色盖住。Features 区块特性卡片网格在 Hero 区块之后可以通过features选项展示任意数量的特性卡片。每个特性可以配置一个图标图标既可以是 emoji也可以是任意类型的图片svg、png、jpeg 等。使用图片作为图标时必须提供合适的宽高需要适配深浅主题时还可以分别提供dark/light变体--- layout: home features: - icon: ️ title: Simple and minimal, always details: Lorem ipsum... - icon: src: /cool-feature-icon.svg title: Another cool feature details: Lorem ipsum... - icon: dark: /dark-feature-icon.svg light: /light-feature-icon.svg title: Another cool feature details: Lorem ipsum... ---对应的类型定义如下interface Feature { // 在特性卡片上显示的图标。 icon?: FeatureIcon // 特性的标题。 title: string // 特性的详细描述。 details: string // 点击特性卡片时跳转的链接支持站内与站外地址。 // // e.g. guide/reference/default-theme-home-page 或 https://example.com link?: string // 特性卡片内展示的链接文字通常配合 link 使用。 // // e.g. Learn more、Visit page 等 linkText?: string // 配合 link 使用的 rel 属性。 // // e.g. external rel?: string // 配合 link 使用的 target 属性。 target?: string } type FeatureIcon | string | { src: string; alt?: string; width?: string; height: string } | { light: string dark: string alt?: string width?: string height: string }各字段的要点说明字段必填说明icon否特性图标。字符串时直接作为 emoji/文字渲染对象形式需提供src或light/dark与heightwidth、alt可选title是特性标题details是特性描述文字link否整张卡片变为链接支持站内与站外地址linkText否卡片内的链接文字如 Learn more右侧会自动带一个箭头图标rel/target否配合link使用的链接属性源码视角图标渲染与卡片细节在 VPFeature.vue 中可以看到三个值得注意的实现点图标形态分发字符串图标通过v-html直接渲染emoji 天然支持对象形态的图标交给VPImage渲染默认宽高均为48可通过width/height覆写对象还支持wrap布尔属性为true时图标会被包裹进带背景的.icon容器中details支持数组details除了字符串还可以是字符串数组此时会渲染为无序列表ul适合展示特性要点卡片链接交互配置link后卡片整体变为可点击链接a标签悬停时边框会过渡为品牌色--vp-c-brand-1配置linkText时卡片底部会显示品牌色链接文字与vpi-arrow-right箭头图标。源码视角网格自适应规则卡片网格的列数由 VPFeatures.vue 根据特性数量自动计算特性数量网格类名桌面端布局2 个grid-2两列3 个grid-3三列3 的倍数6、9…grid-6六列大于 3 且非 3 的倍数4、5、7…grid-4四列1 个无整行单列对应的 CSS 响应式断点如下grid-2/grid-4/grid-6在 ≥40rem 视口下每行 2 个grid-3/grid-6在 ≥48rem 视口下每行 3 个grid-4在 ≥60rem 视口下每行 4 个。也就是说想排 2 列就配置 2 或 4 个特性想排 3 列就配置 3 个或 3 的倍数规则直观且会自动适配移动端。在首页追加 Markdown 内容除了 Hero 与 Features 两个预制区块你还可以直接在 frontmatter 结束标记---下方编写 Markdown作为首页的附加内容例如快速上手指引、团队成员介绍、赞助商区块等--- layout: home hero: name: VitePress text: Vite Vue powered static site generator. --- ## Getting Started You can get started using VitePress right away using npx! sh npm init npx vitepress init 这段 Markdown 会被渲染在 Features 区块之后。从源码看VPHome.vue 会根据markdownStyles决定附加内容的渲染方式VPHomeContent v-iffrontmatter.markdownStyles ! false Content / /VPHomeContent Content v-else /::: info VitePress 并非从一开始就自动为layout: home页面的附加内容套用文档样式。如果你希望回退到旧行为不套用文档排版样式可以在 frontmatter 中添加markdownStyles: false。 :::默认情况下附加内容会被包裹在带vp-doc类的 VPHomeContent.vue 容器中因此标题、列表、代码块等都会获得与正文一致的排版样式设置markdownStyles: false后则原样输出Content /不套用任何文档样式适合嵌入完全自定义的组件内容。同时 VPHomeContent.vue 还针对VPHomeSponsors、VPTeamPage等全宽组件做了视口拉伸处理让首页附加内容可以容纳全宽区块。实战组装一个完整首页综合以上所有内容一个完整的首页示例可保存为站点根目录的index.md如下--- layout: home hero: name: My Docs text: A modern documentation site. tagline: Built with VitePress, powered by Vite Vue. image: src: /logo.png alt: My Docs logo actions: - theme: brand text: Get Started link: /guide/getting-started - theme: alt text: View on GitHub link: https://example.com target: _blank rel: external features: - icon: ⚡️ title: Blazing Fast details: Vite-powered development experience with instant HMR. - icon: src: /cool-feature-icon.svg width: 48 height: 48 title: Customizable details: Fully configurable via frontmatter and theme options. link: /guide/custom-theme linkText: Learn more - icon: dark: /dark-feature-icon.svg light: /light-feature-icon.svg width: 48 height: 48 title: Theme Aware details: Automatically switches between light and dark icons. --- ## Quick Start sh npm init npx vitepress init在撰写时请注意以下几点图片资源image与icon中的/xxx.png、/xxx.svg路径均以站点根目录为基准实际文件应放在项目根目录的public/文件夹下仓库示例见__tests__/base/fixture/public/样式定制颜色与渐变覆写建议写入主题的全局样式如docs/.vitepress/theme/index.ts引入的 CSS或自定义样式表中相关变量定义可参考 vars.css类型依据ThemeableImage与FeatureIcon的完整类型定义见 types/default-theme.d.ts编写自定义主题时可直接复用这些类型以保证兼容性。小结本文围绕 VitePress 默认主题的首页布局完整梳理了从layout: home启用、Hero 区块配置、name 渐变定制、Features 卡片网格到附加 Markdown 内容的全部要点并结合 VPHome.vue、VPHero.vue、VPFeatures.vue、VPFeature.vue 等源码揭示了其内部渲染链路与响应式规则。掌握这些配置与实现细节后你可以用纯 Markdown 前置元数据构建出风格统一、深浅色自适应的产品首页如需进一步定制可继续阅读 默认主题布局参考 与 frontmatter 配置参考深入理解首页布局与整个默认主题体系的关系。【免费下载链接】vitepressVite Vue powered static site generator.项目地址: https://gitcode.com/gh_mirrors/vi/vitepress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考