主页
VitePress

VitePress 首页自定义实战教程：从添加广告位到重构页面布局，如何优雅地在首页添加广告位与自定义布局

想要在 VitePress 静态网站首页添加广告、使用指南或 FAQ？本文分享一次实战经验，教你如何利用 Vue 组件和 Slot 插槽，优雅地扩展 index.md 的功能，实现灵活的广告位管理。
08yt

在之前的一篇文章中，我们添加了GoogleAdSense谷歌广告。这一篇文章，主要是我在一个机场网站中，如何通过自定义布局，添加除了谷歌广告的其他推广广告的。

在使用 VitePress 搭建文档站或博客时，默认的 index.md 虽然简洁，但有时无法满足个性化的需求。比如，我想在“特性（Features）”板块下方加一个醒目的广告横幅，或者添加一栏“使用指南”和“常见问题”。

如果直接在 Markdown 里写大量的 HTML，代码会变得难以维护。经过一番折腾和优化，我摸索出了一套基于 Vue 组件化 的解决方案。

本文将记录我从“硬编码”到“组件化”，最后实现“一键切换广告形式”的全过程。

第一阶段：初尝试——创建广告组件

最开始，我的需求很简单：在首页加一个类似“机场”风格的广告位（左侧 Logo，右侧卖点）。为了不污染 Markdown 文件，我决定创建一个 Vue 组件。（ps:教程与实际不一致，我希望大家不要完全照搬教程，要有所不同，有利于谷歌SEO。）

1. 创建组件文件

在 .vitepress/theme/components/ 目录下新建 MyAdBanner.vue。

Vue组件

代码结构如下（使用 Vue 3 Setup 语法）：

代码段

<template>
  <a href="https://example.com" class="custom-ad-banner" target="_blank">
    <div class="ad-image-section">
      <img src="/images/logo.png" alt="Logo">
    </div>
    <div class="ad-content-section">
      <h3>稳定、高速直连</h3>
      <ul>
        <li>✅ 解锁流媒体</li>
        <li>✅ 多线接入</li>
      </ul>
      <span class="tag">赞助商广告</span>
    </div>
  </a>
</template>

<style scoped>
/* 这里写样式，使用 scoped 防止污染全局 */
.custom-ad-banner { /* ...样式代码... */ }
</style>

2. 全局注册

要在 Markdown 中使用它，必须在 .vitepress/theme/index.js 中注册：

JavaScript

import DefaultTheme from 'vitepress/theme'
import MyAdBanner from './components/MyAdBanner.vue'

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

3. 插入首页

利用 VitePress 的 home-features-after 插槽，将广告精准投放到“特性”板块之后。

Markdown

---
home: true
hero: ...
features: ...
---

<template #home-features-after>
  <div class="container">
     <MyAdBanner />
  </div>
</template>

网站首页自定义广告区

第二阶段：进阶——重构为完整页面布局

随着需求增加，我不仅要放广告，还想在广告下面加“使用教程”和“FAQ（常见问题）”。如果在 index.md 里堆砌多个组件，文件会变得很乱。

于是，我决定创建一个聚合组件 HomePageLayout.vue。

1. 封装布局组件

新建 HomePageLayout.vue，它像一个容器，把广告、教程、FAQ 包装在一起（ps:也可以分开，我选择了分开）：

代码段

<template>
  <div class="home-layout">
    <div class="section">
      <MyAdBanner />
    </div>

    <section class="usage-guide">
      <h2>使用指南</h2>
      </section>

    <section class="faq-list">
      <h2>常见问题</h2>
      </section>
  </div>
</template>

首页自定义布局

2. 极简的 index.md

现在，我的首页 Markdown 文件变得异常干净，只负责通过插槽调用这一个大组件：

Markdown

<div class="home-layout-container">
  <template #home-features-after>
    <HomePageLayout />
  </template>
</div>

这样做的好处是：业务逻辑和内容（HTML/CSS）全部在 Vue 文件里维护，Markdown 只负责结构配置。

第三阶段：灵活应对——一键修改广告形式

后来，我觉得“左图右文”的广告太复杂了，想换成一张简单粗暴的大图横幅（Image Banner）。

得益于之前的组件化设计，我不需要修改 index.md，也不需要修改 HomePageLayout.vue。

我只需要修改最底层的 MyAdBanner.vue 组件即可。

修改 MyAdBanner.vue

代码段

<template>
  <div class="image-ad-container">
    <a :href="link" target="_blank" class="ad-link">
      <img src="/images/banner-wide.jpg" alt="推荐广告" />
    </a>
  </div>
</template>

<style scoped>
.ad-link img {
  width: 100%;
  border-radius: 12px;
  transition: transform 0.2s;
}
.ad-link:hover img {
  transform: translateY(-2px);
}
</style>

保存文件，刷新页面。首页原本复杂的广告区瞬间变成了一张精美的大图，而下方的“使用指南”和“FAQ”依然完美保留，布局没有丝毫错乱。

随着你的广告的变化，广告形式也跟着变化，这样来测试广告效果。

总结

通过这次折腾，我深刻体会到了在 VitePress 中混合使用 Markdown 和 Vue 组件的威力：

  1. Slot 插槽是神器：利用 home-features-after 等插槽，可以在不破坏默认主题的前提下插入自定义内容。

  2. 组件化降低耦合：将广告、FAQ 等功能块独立为组件，修改一个模块不会影响其他模块。

  3. 维护更轻松：以后的内容更新主要在 .vue 文件中进行，拥有完整的 CSS 支持和脚本能力，比在 Markdown 里写内联 HTML 舒服太多。

希望这篇经验能帮到同样想“魔改” VitePress 首页的朋友！

发表评论