vitepress 最详细教程之Home Page的配置

Home Page

文章目录

Home Page

简单介绍

Home Page 页面是文档的主页面，拥有一个好看的主页可以大大吸引用户的注意力，增加自己文档网站的流量，接下来的内容就是介绍如何拥有一个好看的主页。
下图这是作者自己配置的组件库的主页，大家觉得不错可以慢慢看下去，看完教程后我觉得你一定也可以拥有比这更好看的主页 👍。

Home Page 的基本使用

我们在上一节已经介绍了文档的大致目录结构，如果没看过的可以在vitepress 最详细教程之开始使用的目录结构部分查看。
目前效果如下：

首先我们需要在 index.md 中把原有内容清空，然后写入如下内容：

---
layout: home
---

这样我们就开启了首页的布局配置，然而，仅此选项不会有多大作用，你可以通过设置其他选项（如 hero 和 features）向主页添加几个不同的预模板 sections。

Hero 部分

Hero 部分位于主页顶部，下面是如何配置 Hero 部分。

标题部分

layout: home

hero:
  name: VitePress
  text: Vite & Vue powered static site generator.
  tagline: Lorem ipsum...

其中：

name 是文档标题
text 是类似于文档副标题
tagline 是文档标语
现在不清楚不要紧，文章会在最后列出详细注释让你们明白每个配置的作用
现在页面应该是这样的：

不用奇怪为什么没加配置还会出现两个按钮和图片，即使你不写也会按默认配置来的

图片部分

我们在上述例子中可以发现，我们右侧的图片不显示，那么本节教大家如何配置图片。

hero:
  image:
    src: /logo.png
    alt: 网页的logo图标

更改配置后大家一定会发现右侧的图标文字变了，那么一定能想到 img 标签的 alt 属性，没错，这里配置中的 alt 就相当于img 标签的 alt 属性。

那么我们加入图片，大家肯定会问在哪加呢？我们启动项目的命令是 vitepress dev docs，那么我们的图片都根目录就是 docs 所以上面配置中是 /logo.png，我们只需要在 docs 中加入名为 logo.png 的图片后就会显示，效果如下：

图片的配置接口如下，大家可以试试给网站配置不同主题的图片，让网页效果更好 😄，我们上述演示的是第二类的配置：

type ThemeableImage =
  | string
  | { src: string; alt?: string }
  | { light: string; dark: string; alt?: string }

按钮部分

现在开始配置页面中的两个按钮。

hero:
  actions:
    - theme: brand
      text: 开始使用
      link: /guide/start
    - theme: alt
      text: 在 GitHub 上查看
      link: https://github.com/ox4f5da2

其中：

theme 是按钮的主题，只有 brand 和 alt 两种，也就是分别对应目前网页中绿色和灰色按钮
text 是按钮的文字
link 是按钮的链接，点击后壳跳转，可以是 URL，也可以是文档中的绝对路径，根路径是 docs，可以省略文档类型，默认是 md

下面我们来实战一下，首先在 docs 下创建 guide 目录，然后再这个 guide 目录下创建 start.md 文件，写入：

# 开始

然后另一个按钮的链接写上 GitHub 地址，然后去点击试试吧：

在这里插入图片描述
actions 的配置接口如下：

interface HeroAction {
  theme?: 'brand' | 'alt'
  text: string
  link: string
}

Features 部分

相关配置如下：

features:
  - icon: 🛠️
    title: Simple and minimal, always
    details: Lorem ipsum...
    link: /guide/start
    linkText: 了解更多
  - icon: ⚡️
    title: Another cool feature
    details: Lorem ipsum...
  - icon: 🌞
    title: Another cool feature
    details: Lorem ipsum...

其中：

icon 是每个 feature 盒子的图标
title 是每个 feature 盒子的标题
details 是每个 feature 盒子的详细描述
link 是每个 feature 盒子的单击要素组件时链接，链接可以是内部链接，也可以是外部链接。
linkText 是每个 feature 盒子的链接要显示在要素组件内部的文本。最好与 link 选项一起使用。
效果如下：

在这里插入图片描述
如下是 features 的相关配置：

interface Feature {
  icon?: FeatureIcon
  title: string
  details: string
  link?: string
  linkText?: string
}

type FeatureIcon =
  | string
  | { src: string; alt?: string; width?: string; height: string }
  | {
      light: string
      dark: string
      alt?: string
      width?: string
      height: string
    }

icon 还有很多配置，感兴趣的小伙伴可以自行配置一下哈 😄

写在最后

到目前我们已经有了一个好看的 Home Page 了，以后会教大家配置自己的主题颜色等，然后下一节会教大家配置导航栏 nav，如果大家喜欢可以点赞➕收藏这个专栏。