如何采用VuePress构建文档网站

作者：倾城

博客： https://www.codingbrick.com

寄语：当你意识到面子不重要时，你才算个真正的成年人。

在建设博客的初期，我采用GitBook构建了编码专家的专栏系统。GitBook是基于Node.js的静态页构建组件，可以将Markdown文档渲染为静态页，支持插件扩展，使用非常简单。由于它不支持深度的定制，使用了一段时间后，无法满足我的要求了。

有一天我看到某博客采用VuePress，简洁美观、功能强大。VuePress的帮助文档非常详实，是Vue团队的诚意之作。正好我有一些Vue开发的功底，犹如出狱的色狼碰上了洗澡的刘亦菲。如果时间可以倒流，我绝对不会用WordPress来构建我的博客。WordPress固然成熟，设计的太“重”了。

VuePress 是一个 Vue 驱动的静态网站生成器，使用Markdown编写文档，提供成熟的主题、侧边栏、搜索功能等，轻松创建如何结构清晰、易于导航和搜索的文档网站。VuePress集成了自动化部署工具，可以将生成的静态网站部署到各种托管平台上，如GitHub Pages、Netlify等。VuePress还支持自动化的更新和发布，使得您可以轻松地更新网站内容，并保持与代码仓库的同步。(来自VuePress官网)

1 安装Nodejs

根据Vuepress官网的部署指南，Vuepress v2.0依赖Node.js版本是v16.19.0+。推荐采用 yum 方式安装首先确认镜像地址是否可用，文件路径是：/etc/yum.repos.d/CentOS-Base.repo，参考内容如下所示：

# CentOS-Base.repo
#
# The mirror system uses the connecting IP address of the client and the
# update status of each mirror to pick mirrors that are updated to and
# geographically close to the client.  You should use this for CentOS updates
# unless you are manually picking other mirrors.
#
# If the mirrorlist= does not work for you, as a fall back you can try the
# remarked out baseurl= line instead.
#
#

[base]
name=CentOS-$releasever - Base - mirrors.aliyun.com
failovermethod=priority
baseurl=http://mirrors.aliyun.com/centos/$releasever/os/$basearch/
        http://mirrors.aliyuncs.com/centos/$releasever/os/$basearch/
        http://mirrors.cloud.aliyuncs.com/centos/$releasever/os/$basearch/
gpgcheck=1
gpgkey=http://mirrors.aliyun.com/centos/RPM-GPG-KEY-CentOS-7

#released updates
[updates]
name=CentOS-$releasever - Updates - mirrors.aliyun.com
failovermethod=priority
baseurl=http://mirrors.aliyun.com/centos/$releasever/updates/$basearch/
        http://mirrors.aliyuncs.com/centos/$releasever/updates/$basearch/
        http://mirrors.cloud.aliyuncs.com/centos/$releasever/updates/$basearch/
gpgcheck=1
gpgkey=http://mirrors.aliyun.com/centos/RPM-GPG-KEY-CentOS-7

#additional packages that may be useful
[extras]
name=CentOS-$releasever - Extras - mirrors.aliyun.com
failovermethod=priority
baseurl=http://mirrors.aliyun.com/centos/$releasever/extras/$basearch/
        http://mirrors.aliyuncs.com/centos/$releasever/extras/$basearch/
        http://mirrors.cloud.aliyuncs.com/centos/$releasever/extras/$basearch/
gpgcheck=1
gpgkey=http://mirrors.aliyun.com/centos/RPM-GPG-KEY-CentOS-7

#additional packages that extend functionality of existing packages
[centosplus]
name=CentOS-$releasever - Plus - mirrors.aliyun.com
failovermethod=priority
baseurl=http://mirrors.aliyun.com/centos/$releasever/centosplus/$basearch/
        http://mirrors.aliyuncs.com/centos/$releasever/centosplus/$basearch/
        http://mirrors.cloud.aliyuncs.com/centos/$releasever/centosplus/$basearch/
gpgcheck=1
enabled=0
gpgkey=http://mirrors.aliyun.com/centos/RPM-GPG-KEY-CentOS-7

#contrib - packages by Centos Users
[contrib]
name=CentOS-$releasever - Contrib - mirrors.aliyun.com
failovermethod=priority
baseurl=http://mirrors.aliyun.com/centos/$releasever/contrib/$basearch/
        http://mirrors.aliyuncs.com/centos/$releasever/contrib/$basearch/
        http://mirrors.cloud.aliyuncs.com/centos/$releasever/contrib/$basearch/
gpgcheck=1
enabled=0
gpgkey=http://mirrors.aliyun.com/centos/RPM-GPG-KEY-CentOS-7

yum 方式安装的默认版本是16.18.1，达不到VuePress 2.0需要的最小版本16.19.0，必须指定版本号，命令如下：

# 检查可用版本
yum list available nodejs
# 安装指定版本
yum install nodejs-16.20.0

有时候 yum 源里面没有相应的Node.js版本，可以采用n模块安装指定版本，命令如下：

# 首先安装npm模块
yum install npm
# 利用npm安装n模块
npm install -g n
# 安装最新版
n latest
# 或者指定版本
n 16.20.0
# 显示版本号，证明安装成功
node -v

2 初始化项目

VuePress的默认主题比较简陋，缺乏SEO、Markdown 语法扩展等功能，推荐直接使用vuepress-theme-hope。这个版本提供了更加美观的主题，默认集成许多实用的插件，大大增强了原有的功能。

首先初始化项目，命令如下：

npm init vuepress-theme-hope

这个命令会下载所有的依赖包，根据提示依次设置项目名称、版本号等信息，最终会生成带有空页面的初始工程。

采用如下命令启动调试：

npm run docs:dev

开发完毕后，可以构建静态页部署到服务器上，静态页默认输出路径是 .vuepress/dist/，构建命令如下：

npm run docs:build

3 迁移项目

如果重新部署项目，需要再次安装依赖包，下载项目源码后，在根目录执行命令：

npm install vuepress@next
npm install vuepress-theme-hope

4 开发经验

4.1 配置插件

VuePress支持很多插件，以安装搜索插件为例，命令如下：

# 安装搜索插件
npm i -D vuepress-plugin-search-pro

在 config.ts 文件里面找到 defineUserConfig，在配置项里增加代码：

  plugins: [
    searchProPlugin({
      // 索引全部内容
      indexContent: true,
      hotReload: true,
      // 为分类和标签添加索引
      customFields: [
        {
          getter: (page) => page.frontmatter.category,
          formatter: "分类：$content",
        },
        {
          getter: (page) => page.frontmatter.tag,
          formatter: "标签：$content",
        }
      ]
    })
  ]

4.2 百度统计

在 config.ts文件里面找到 defineUserConfig，在这个配置项的 header 里插入百度统计的脚本，如下所示：

  head: [
    // 百度统计
    [
      "script",
      {},
      `
      var _hmt = _hmt || [];
      (function() {
        var hm = document.createElement("script");
        hm.src = "https://hm.baidu.com/hm.js?去百度统计网站获取相应代码";
        var s = document.getElementsByTagName("script")[0];
        s.parentNode.insertBefore(hm, s);
      })();
        `
    ]
  ]

新建文件 enhanceApp.ts ，加入如下内容：

export default ({ router }) => {
    /**
     * vuepress 是基于 vue 的单页面应用，页面切换过程中不会重新加载页面，不会触发百度统计。
     * 以下代码用于监听路由切换事件，当切换页面时,手动上报百度统计
     */
    router.beforeEach((to, from, next) => {
      console.log("切换路由", to.fullPath, from.fullPath);

      //触发百度的pv统计
      if (typeof _hmt != "undefined") {
        if (to.path) {
          _hmt.push(["_trackPageview", to.fullPath]);
          console.log("上报百度统计", to.fullPath);
        }
      }
      // continue
      next();
    });
  };

4.3 辅助脚本

懒得去记忆npm原始命令，编写一个Shell脚本用来构建站点，代码如下：

#!/bin/sh

echo "please choose your option(1、2):"
echo "1: hot deploy for developing"
echo "2: build static page(default path: .vuepress/dist/)"

read item
if [ $item == 1 ]
then
  git pull
  npm run docs:dev
elif [ $item == 2 ]
then
  git pull
  npm run docs:build
else
    choose
fi

5 参考文档

https://v2.vuepress.vuejs.org/zh/guide/

https://theme-hope.vuejs.press/zh/guide/