如何采用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/
公 众 号:编码专家
独立博客:codingbrick.com
文章出处:https://www.cnblogs.com/xiaoyangjia/p/17800255.html
本文版权归作者所有,任何人或团体、机构全部转载或者部分转载、摘录,请在文章明显位置注明作者和原文链接。