如何采用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/