Vuepress搭建博客到自动部署，一篇就够了！

Vuepress介绍

VuePress 是 Vuejs 官方提供的一个是Vue驱动的静态网站生成器，基于Markdown语法生成网页。简单的说它就是一个快速建设文档站点的工具，在简单配置好功能后，需要做的事情就剩下写好一个个 Markdown 文档，并且可以将其发布到github。

VuePress ,一个全新的基于 vue 实现的静态网站生成器，实际上就是一个 vue 的 spa 应用，内置 webpack，可以用来写文档。

VuePress 由两部分组成：一个以 Vue 驱动的主题系统简约静态网站生成工具，和一个为编写技术文档而优化的默认主题。它是为了支持 Vue 子项目的文档需求而创建的。
vuepress官网：https://vuepress.vuejs.org/zh/

一、快速上手

依赖环境

Node.js v18.16.0+
包管理器，如 pnpm、yarn、npm 等。

创建项目

有两种创建项目的方式，分别为通过命令行创建和手动创建

1、命令行创建

直接在存放项目的目录下打开命令终端，然后输入命令。

npm init vuepress vuepress-starter

输入命令后跟随指引一步一步进行安装就行，可以参考我的配置：

在这里插入图片描述

2、手动创建（推荐）

推荐使用手动进行项目创建，更加灵活。

但是这里一定要注意，安装配置的node版本必须高于 18.19.0，否则会出现vuepress/bundler-vite和vuepress/theme-default版本冲突的问题。

mkdir vuepress-starter
cd vuepress-starter

初始化项目

npm init -y

在这里插入图片描述

安装 VuePress

# 安装 vuepress
npm install -D vuepress@next

创建 docs 目录和 docs/.vuepress 目录

mkdir docs
mkdir docs/.vuepress
mkdir docs/.vuepress/config.js

创建你的第一篇文档

echo '# Hello VuePress' > docs/README.md

创建完成后，你项目的目录结构应该是这样的：

├─ docs
│  ├─ .vuepress
│  │  └─ config.js
│  └─ README.md
└─ package.json

在这里插入图片描述

docs 目录是你放置 Markdown 文件的地方，它同时也会作为 VuePress 的源文件目录。

docs/.vuepress 目录，即源文件目录下的 .vuepress 目录，是放置所有和 VuePress 相关的文件的地方。当前这里只有一个配置文件。默认还会在该目录下生成临时文件、缓存文件和构建输出文件。建议你把它们添加到 .gitignore 文件中。

示例 .gitignore 文件

# VuePress 默认临时文件目录
.vuepress/.temp
# VuePress 默认缓存目录
.vuepress/.cache
# VuePress 默认构建生成的静态文件目录
.vuepress/dist

3、开始使用 VuePress

启动开发服务器

你可以在 package.json 中添加一些 scripts ：

{
    
    
  "scripts": {
    
    
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

在这里插入图片描述

运行 docs:dev 脚本可以启动开发服务器:

npm run docs:dev

VuePress 会在 http://localhost:8080 启动一个热重载的开发服务器。当你修改你的 Markdown 文件时，浏览器中的内容也会自动更新。

运行效果：

在这里插入图片描述

二、美化配置

初始化生成的这个页面只有较为简单的一些效果，如果需要美化一些内容需要进行config.js文件的配置，下面将介绍一些常见的配置，如果需要详细查看更多配置，可以去这个链接进行查看，咻~

站点配置

lang

类型： string
默认值： en-US
详情：

站点的语言。

它将会在最终渲染出的 HTML 中作为 <html> 标签的 lang 属性。

它可以设置在不同语言的 locales 中。
示例：

lang:'zh-CN'

title

类型： string
默认值： ''
详情：

站点的标题。

它将会作为所有页面标题的后缀，并且在默认主题的导航栏中显示。

它可以设置在不同语言的 locales 中。
示例：

title: "这是我的博客"

head

类型： HeadConfig[]
默认值： []
详情：

在最终渲染出的 HTML 的 <head> 标签内加入的额外标签。

你可以通过 [tagName, { attrName: attrValue }, innerHTML?] 的格式来添加标签。

它可以设置在不同语言的 locales 中。

需要注意的是，如果 attrValue 是一个 pathname ，它不会被自动添加 base 前缀，所以如果需要的话请记得手动添加前缀。
官方示例：

增加一个自定义的 favicon ：

export default {
    
    
  head: [['link', {
    
     rel: 'icon', href: '/images/logo.png' }]],
}

渲染为：

<head>
  <link rel="icon" href="/images/logo.png" />
</head>

主题配置

plugins

类型： PluginConfig[]
详情：

要使用的插件。

该配置项接收一个数组，其中的每一个数组项是一个或一组插件。
示例：

plugins: [
    ["@vuepress/back-to-top"],
]

markdown

类型： MarkdownOptions
默认值： {}
详情：

对 VuePress 内置的 Markdown 语法扩展进行配置。

它可以接收 markdown-it 的所有配置项，以及下列额外的配置项。
示例：

markdown: {
    // 开启代码块的行号
    lineNumbers: true,
    // 支持 4 级以上的标题渲染
    extractHeaders: ["h2", "h3", "h4", "h5", "h6"],
  },

themeConfig

类型： themeConfigOptions
默认值： {}
详情：

对页面的头部、内容、底部等进行配置
示例：

//支持从其他js文件中导入，这些配置的格式都为数组格式
import navbar from "./navbar";
import sidebar from "./sidebar";
import footer from "./footer";
import extraSideBar from "./extraSideBar";


themeConfig: {
    
    
    //导航栏logo
    logo: "/logo.png",
    nav: navbar,
    // 左侧导航栏
    sidebar,
    lastUpdated: "最近更新",
    // 编辑链接
    editLinks: true,
    editLinkText: "完善页面",
    // 底部版权信息
    footer,
    // 额外右侧边栏
    extraSideBar,
  },

三、部署上线

我这里选择的是部署到Github pages上，同时借助Github Actions进行自动部署。下面简单介绍一下如何操作，具体的实现可以参考我的另一篇文章。传送门

1、打包

执行下面的命令进行项目打包

npm run docs:build

打包完成后，会在默认构建输出目录.vuepress/dist下看到打包后的内容，只需要把dist文件夹的内容上次到github中的仓库里面。

2、配置Github Actions

代码上传好后，只需要在actions中配置工作流，这样当仓库中的代码更新后，就会自动进行更新部署。

下面给出一段官方的yml配置文件的示例仅供参考:

name: docs

on:
  # 每当 push 到 main 分支时触发部署
  push:
    branches: [main]
  # 手动触发部署
  workflow_dispatch:

jobs:
  docs:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
        with:
          # “最近更新时间” 等 git 日志相关信息，需要拉取全部提交记录
          fetch-depth: 0

      - name: Setup pnpm
        uses: pnpm/action-setup@v2
        with:
          # 选择要使用的 pnpm 版本
          version: 8
          # 使用 pnpm 安装依赖
          run_install: true

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          # 选择要使用的 node 版本
          node-version: 20
          # 缓存 pnpm 依赖
          cache: pnpm

      # 运行构建脚本
      - name: Build VuePress site
        run: pnpm docs:build

      # 查看 workflow 的文档来获取更多信息
      # @see https://github.com/crazy-max/ghaction-github-pages
      - name: Deploy to GitHub Pages
        uses: crazy-max/ghaction-github-pages@v4
        with:
          # 部署到 gh-pages 分支
          target_branch: gh-pages
          # 部署目录为 VuePress 的默认输出目录
          build_dir: docs/.vuepress/dist
        env:
          # @see https://docs.github.com/cn/actions/reference/authentication-in-a-workflow#about-the-github_token-secret
          GITHUB_TOKEN: ${
    
    {
    
     secrets.GITHUB_TOKEN }}