使用 Vitepress 构建博客并部署到 github 平台

前言

最近写了好多篇 Chrome 浏览器插件相关的文章，有十几二十篇，就想着构建个博客，用来放置相应的文章。
正好前段时间看到 VitePress 1.0.0 发布了，而且是用 markdown 写文章，正好写插件文章的时候文章都是 md 格式，所有用下这个然后顺便写一篇使用教程。

Chrome 插件开发博客地址：https://18055975947.github.io/extension/

一、VitePress

VitePress 官网：VitePress 中文版

1. 什么是 VitePress

VitePress 是一个静态站点生成器 (SSG)，专为构建快速、以内容为中心的站点而设计。简而言之，VitePress 获取用 Markdown 编写的内容，对其应用主题，并生成可以轻松部署到任何地方的静态 HTML 页面。

2. 性能

• 快速的初始加载
• 加载完成后可以快速切换
• 高效的交互

二、项目构建

1. 新建项目

NodeJS 版本需要 18 及以上版本

mkdir vitepress-demo 

2. 配置项目

2.1. 项目初始化

pnpm init

2.2. 安装 VitePress

pnpm add -D vitepress

2.3. 初始化 VitePress

pnpm vitepress init

初始化之后，会有对应的项目问题需要进行填写，示例如下：

3. 项目目录

tree -a -I 'node_modules' 

.
├── docs
│   ├── .vitepress
│   │   └── config.mts
│   ├── api-examples.md
│   ├── index.md
│   └── markdown-examples.md
├── package.json
└── pnpm-lock.yaml

在 docs 文件夹中创建 public 文件夹，用于存放项目图片

.
├── docs
│   ├── .vitepress
│   │   └── config.mts
│   ├── api-examples.md
│   ├── index.md
│   ├── markdown-examples.md
│   └── public # 增加 public 文件夹，存放项目开发使用的图片
├── package.json
└── pnpm-lock.yaml

4. 项目文件结构

• docs 文件夹：VitePress 项目的根目录
  • .vitepress：项目的配置文件、开发缓存、构建 dist 输出等
    • config.mts：项目配置文件
  • index.md：首页入口文件
  • **.md：其他页面
  • public：资源存放文件夹

5. 运行项目

pnpm run docs:dev

浏览器打开：http://localhost:5174/

可以看出我们设置的 site title 和 site description 字段已经展示在页面中了

三、项目开发

1. 首页

一般是指 index.md 文件

1.1. Layout

指定页面的布局

VitePress 默认主题提供了一个首页布局，可以通过 frontmatter 指定 layout: home 在任何页面上使用它

1.1.1. 类型

doc | home | page

1.1.2. 数据值

• doc：将默认文档样式应用于 .md 文件内容
• home：主页的特殊布局
• page：和 doc 类似，但不对内容应用任何样式

1.1.3. 示例

---
layout: home
---

1.1.4. 页面展示

home 展示

doc 展示

page 展示

1.2. Hero

hero 部分位于主页顶部。
当 layout 设置为 home 时，hero 配置才会生效。

1.2.1. 类型

interface Hero {
   
   
  // `text` 上方的字符，带有品牌颜色
  // 预计简短，例如产品名称
  name?: string
  // hero 部分的主要文字，
  // 被定义为 `h1` 标签
  text: string
  // `text` 下方的标语
  tagline?: string
  // text 和 tagline 区域旁的图片
  image?: ThemeableImage
  // 主页 hero 部分的操作按钮
  actions?: HeroAction[]
}

• name：文档标题
• text：副标题/描述
• tagline：文档标语
• image：右侧图片
• actions：操作按钮
  • theme：brand | alt 按钮主题，只有这两种主题，默认为 brand
    • brand：蓝色背景按钮
    • alt：灰色背景按钮
  • text：按钮文案
  • link：按钮的链接

1.2.2. 示例

找一张 ext.svg 图标放在 public 文件夹中

---
layout: home

hero:
  name: "My VitePress Demo Project"
  text: "This is my VitePress demo project"
  tagline: "My great project tagline"
  image:
    src: /ext.svg
    alt: Chrome 浏览器插件
  actions:
    - theme: brand
      text: Markdown Examples
      link: /markdown-examples
    - theme: alt
      text: API Examples
      link: /api-examples
    - theme: brand
      text: extension
      link: https://18055975947.github.io/extension/
      target: _blank
      rel: external
---

1.2.3. 页面展示

1.3. Features

可以在 Hero 部分之后列出任意数量的 Feature

1.3.1. 类型

interface Feature {
   
   
  // 在每个 feature 框中显示图标
  icon?: FeatureIcon
  // feature 的标题
  title: string
  // feature 的详情
  details: string
  // 点击 feature 组件时的链接，可以是内部链接，也可以是外部链接。
  link?: string
  // feature 组件内显示的链接文本，最好与 `link` 选项一起使用
  linkText?: string
  // `link` 选项的链接 rel 属性
  rel?: string
  // `link` 选项的链接 target 属性
  target?: string
}

• icon：图标
• title：标题
• details：描述
• link：跳转链接

1.3.2. 示例

找一些对应的图标放在 public 文件夹中

---
layout: home

features:
  - title: 什么是浏览器插件？
    icon:
      src: /ext.svg
    details: Chrome 插件可通过自定义界面、观察浏览器事件和修改网络来提升浏览体验。
  - title: Chrome 插件是如何构建的？
    icon:
      src: /develop.svg
    details: 使用与创建 Web 应用相同的 Web 技术来构建扩展程序：HTML、CSS 和 JavaScript。
  - title: Chrome 插件可以做些什么？
    icon:
      src: /ext-2.svg
    details: 设计界面、控制浏览器、管理插件、覆盖网页和设置、控制网络、注入 JS 和 CSS、录音和屏幕截图
  - title: Vue 开发插件
    icon:
      src: /vue.svg
    details: 是一个使用 Vue.js 框架开发的 Chrome 插件，旨在为开发者展示如何使用 Vue.js 构建强大的浏览器扩展。
    link: https://juejin.cn/post/7330227149177028617
    linkText: 查看详情
  - title: React 开发插件
    icon:
      src: /react.svg
    details: 是一个使用 React.js 框架开发的 Chrome 插件，旨在为开发者展示如何使用 React.js 构建强大的浏览器扩展。
    link: https://juejin.cn/post/7349936384512213027
    linkText: 查看详情
  - title: 实用插件推荐
    icon:
      src: /tj.svg
    details: 推荐一些对前端开发来说实用的 Chrome 插件。
    link: https://juejin.cn/post/7327893130572824611
    linkText: 查看详情
---

1.3.3 页面展示

1.4. 其他

如果到这个时候你觉得在首页 md 文件中还没有满足你的其他需求，可以在分隔符下继续以 md 的格式开发新内容。

1.4.1. 添加 MD 内容

## 首页模块 MD 文档

MD 文件

1.4.2 引入 MD 文件

1.4.2.1. 新建 MD 文件

在 docs 文件夹下创建 components 文件夹并创建 test.md 文件，并写入以下内容

---
layout: page
---

## Components

### test 模块

这个模块是 `components` 文件夹下的 `test` 模块

.
docs/components
└── test.md

1.4.2.2. 在 index.md 文件引入

使用<!--@include: xxx.md--> 的格式引入
在 index.md 文件添加以下内容

下面是添加 `style` 标签和引入 `md` 文件

<style module>
article>img{
  height: 48px;
}
</style>

<!--@include: ./components/test.md-->

1.4.2.3. 页面展示

1. 引入 MD 文件展示
   
2. Style 标签样式展示

2. 导航栏

Nav 是显示在页面顶部的导航栏。它包含站点标题、全局菜单链接等。

导航栏模块的配置是通过 docs/.vitepress/config.mts 文件配置的

config.mts 文件内容

import {
   
    defineConfig } from 'vitepress'
export default defineConfig({
   
   
  title: "My VitePress Demo Project",
  description: "This is my VitePress demo project",
  themeConfig: {
   
   
    nav: [
      {
   
    text: 'Home', link: '/' },
      {
   
    text: 'Examples', link: '/markdown-examples' }
    ],
    sidebar: [
      {
   
   
        text: 'Examples',
        items: [
          {
   
    text: 'Markdown Examples', link: '/markdown-examples' },
          {
   
    text: 'Runtime API Examples', link: '/api-examples' }
        ]
      }
    ],
    socialLinks: [
      {
   
    icon: 'github', link: 'https://github.com/vuejs/vitepress' }
    ]
  }
})

2.1. 站点标题和图标：sitTitle、logo

2.1.1. 在 themeConfig 中添加 logo 和 siteTitle 字段

2.1.1.1. 类型

string：logo 和 siteTitle 都是 string 类型

2.1.1.2. themeConfig 配置示例

import {
   
    defineConfig } from 'vitepress'
export default defineConfig({
   
   
  title: "My VitePress Demo Project",
  description: "This is my VitePress demo project",
  themeConfig: {
   
   
    logo: '/ext.svg',
    siteTitle: