作者:duktig
博客:https://duktig.cn (文章首发)
优秀还努力。愿你付出甘之如饴,所得归于欢喜。
本篇文章将持续更新个人博客平台并置顶:基于VuePress搭建博客系统及优化过程(持续更新…)
文章目录
博客预览
本地搭建
直接基于主题 vuepress-theme-reco 进行搭建。
执行初始化命令
方式一:npx
npx @vuepress-reco/theme-cli init
npx @vuepress-reco/theme-cli init [文件夹名字]
方式一:npm
npm install @vuepress-reco/theme-cli -g theme-cli init
npm install @vuepress-reco/theme-cli -g theme-cli init [文件夹名字]
注意:init
后可以直接加文件夹根目录,避免初始化时需要再次生成目录(不创建目录执行,会发生些报错)。
上图这个步骤,What style do you want your home page to be?
有三个选项,分别是:
- blog(推荐)
- doc(和blog几乎一致,只不过
init
执行中输入的信息未应用,存在一些问题) - 2.x(目前还不成熟)
三个版本测试的时间为:2022.01.18
安装依赖
cd [文件夹名字]
npm install
本地运行
npm run dev
.vuepress/config.js
配置
修改静态文件输出目录
在 vuepress-theme-reco 主题中,"dest"
的值为public
;在 vuepress 官方中,"dest"
的值为.vuepress/dist
。
这个值意为,执行 npm run build
后,静态资源目录生成的位置,会影响到后边GitHub Actions的配置。
这里我们将"dest"
的值为.vuepress/dist
。
部署上线
方式一:GitHub Actions 自动部署
主分支存放代码,gh-pages
用于展示内容。
设置 Secrets
后面部署的 Action 需要有操作你的仓库的权限,因此提前设置好 GitHub personal access(个人访问令牌)。
生成教程可以看 GitHub 官方的帮助文档:创建用于命令行的个人访问令牌 (opens new window)。
授予权限的时候只给 repo
权限即可。
令牌名字一定要叫:ACCESS_TOKEN
,这是后面的 Action 需要用的。
编写 workflow 文件
持续集成一次运行的过程,就是一个 workflow(工作流程)。
创建.github/workflows/main.yml
文件,内容如下:
name: Deploy GitHub Pages
# 触发条件:在 push 到 master 分支后
on:
push:
branches:
- main
# 任务
jobs:
build-and-deploy:
# 服务器环境:最新版 Ubuntu
runs-on: ubuntu-latest
steps:
# 拉取代码
- name: Checkout
uses: actions/checkout@v2
with:
persist-credentials: false
# 生成静态文件
- name: Build
run: npm install && npm run build
# 部署到 GitHub Pages
- name: Deploy
uses: JamesIves/github-pages-deploy-action@releases/v3
with:
ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
BRANCH: gh-pages
FOLDER: .vuepress/dist # 静态资源目录
需要了解 workflow 的基本语法可以查看官方帮助 (opens new window),也可以参考阮一峰老师的 GitHub Actions 入门
具体参看文章:使用 GitHub Actions 自动部署博客
设置GitHub Pages
方式二:两个仓库
新建仓库一: USERNAME.github.io
(不用克隆到本地)
USERNAME
必须是你 Github 的账号名称,这个仓库用来展示博客。
新建仓库二:随便起一个名字,比如:vuepressBlog (克隆到本地)
这个项目是用来开发博客的,以后只需要改这个项目就够了。
创建部署脚本:
#!/usr/bin/env sh
# 确保脚本抛出遇到的错误
set -e
# 生成静态文件
npm run build
# 进入生成的文件夹
cd docs/.vuepress/dist
# 如果是发布到自定义域名
# echo 'www.yourwebsite.com' > CNAME
git init
git add -A
git commit -m 'deploy'
# 如果你想要部署到 https://USERNAME.github.io
git push -f git@github.com:USERNAME/USERNAME.github.io.git master
# 如果发布到 https://USERNAME.github.io/<REPO> REPO=github上的项目
# git push -f git@github.com:USERNAME/<REPO>.git master:gh-pages
cd -
修改仓库二中的 deploy.sh 发布脚本,把文件中的 USERNAME 改成 Github 账号名。
这样仓库二和仓库一就建立了关联。
简单说二者的关系是:仓库一负责显示网站内容,我们不需要改动它;日常开发和新增内容,都在仓库二中,并通过 npm run deploy 命令,将代码发布到仓库一。
在 package.json 文件夹中添加发布命令
"scripts": {
"deploy": "bash deploy.sh"
}
运行发布命令
npm run deploy
添加自定义域名
在仓库一 USERNAME.github.io 中找到 Settings > Custom domain 把 域名 添加进去即可。
具体参看文章:手把手教你使用 VuePress 搭建个人博客 (文中含有部署相关)
vuepress-theme-reco 主题优化
代码块样式选择
// .vuepress/config.js
module.exports = {
theme: 'reco',
themeConfig: {
/**
* support for
* 'default'
* 'funky'
* 'okaidia'
* 'solarizedlight'
* 'tomorrow'
*/
codeTheme: 'tomorrow' // default 'tomorrow'
}
}
vuepress-theme-reco 1.6.10版本,设置代码样式失效,详情参看:issues#397
评论系统
评论系统可以使用 Valine 或 Vssue。
两者对比:
Valine
-
支持的功能更多。比如邮件提醒、文章阅读量统计(文章多的时候会影响一定的性能)、自定义表情等。
-
使用的是Gravatar 作为评论列表头像,需用户注册和配置。
-
样式预览:
Vssue
- 最大的特性是支持 GitHub 登录。
- 基于 Issues 实现的评论系统。
这里暂时先使用 Vssue 搭建评论系统,详情可参看:
PWA 刷新插件
安装
npm install -D @vuepress/plugin-pwa
使用
本选项开启了一个用于刷新内容的弹窗。这个弹窗将会在站点有内容更新时显示出来,并提供了一个 refresh
按钮,允许用户立即刷新内容。
如果没有“刷新”按钮,则只有在所有的 Clients (opens new window)被关闭后,新的 Service Worker 才会处于活动状态。这意味着用户在关闭你网站的所有标签之前无法看到新内容。但是
refresh
按钮会立即激活新的 Service Worker。
['@vuepress/pwa', {
serviceWorker: true,
updatePopup: {
message: "发现新内容可用",
buttonText: "刷新"
}
}],
音乐播放器插件
音乐插件选用:meting
// 音乐插件
['meting', {
//metingApi: "https://meting.sigure.xyz/api/music",
meting: {
// 网易
server: "netease",
// 读取歌单
type: "playlist",
mid: "696441716",
},
// 不配置该项的话不会出现全局播放器
aplayer: {
// 吸底模式
fixed: true,
mini: true,
// 自动播放
autoplay: true,
// 歌曲栏折叠
listFolded:true,
// 颜色
theme: '#f9bcdd',
// 播放顺序为随机
order: 'random',
// 初始音量
volume: 0.1,
// 关闭歌词显示
lrcType: 0
},
mobile :{
// 手机端去掉cover图
cover: false,
}
}]
好用的MarkDown扩展语法
完整的md扩展,参看:https://vuepress.vuejs.org/zh/guide/markdown.html
GitHub 风格的表格
输入
| Tables | Are | Cool |
| ------------- |:-------------:| -----:|
| col 3 is | right-aligned | $1600 |
| col 2 is | centered | $12 |
| zebra stripes | are neat | $1 |
输出
Tables | Are | Cool |
---|---|---|
col 3 is | right-aligned | $1600 |
col 2 is | centered | $12 |
zebra stripes | are neat | $1 |
Emoji
输入
:tada: :100:
输出
🎉 💯
你可以在这个列表 (opens new window)找到所有可用的 Emoji。
目录
[[toc]]
自定义容器 (默认主题)
输入
::: tip
这是一个提示
:::
::: warning
这是一个警告
:::
::: danger
这是一个危险警告
:::
::: details
这是一个详情块,在 IE / Edge 中不生效
:::
代码块中的行高亮
输入
```js {4}
export default {
data () {
return {
msg: 'Highlighted!'
}
}
}
```
以上例子会在 第四行代码 加高亮显示。
除了单行以外,你也可指定多行,行数区间,或是两者都指定。
- 行数区间: 例如
{5-8}
,{3-10}
,{10-17}
- 多个单行: 例如
{4,7,9}
- 行数区间与多个单行: 例如
{4,7-13,16,23-27,40}
问题及解决
1. md文件名有中文不能正常路由跳转?
方法一:添加文件.vuepress/enhanceApp.js
添加文件.vuepress/enhanceApp.js,写入以下内容
export default ({
router, // 当前应用的路由实例
}) => {
// 解决中文路由无法被正确加载的问题
router.beforeEach((to, from, next) => {
if (decodeURIComponent(to.path) !== to.path) {
return next({
...to,
path: decodeURIComponent(to.path),
fullPath: decodeURIComponent(to.fullPath)
})
}
next()
})
}
vuepress-theme-reco 版本为 1.6.10 使用这种方式依然没有解决问题。
方法二:使用插件 vuepress-plugin-permalink-pinyin
但是原有的中文路由会转为拼音
当文件名含有中文时,对应页面无法跳转,可通过如下插件解决这个问题,这个插件会将中文路径转换为拼音路径
本地安装:
npm install -D vuepress-plugin-permalink-pinyin
然后配置插件:
module.exports = {
plugins: [
// 支持中文文件名
[
"permalink-pinyin",
{
lowercase: true, // Converted into lowercase, default: true
separator: "-", // Separator of the slug, default: '-'
},
],
]
}
vuepress-theme-reco 1.6.10 配置如下 永久链接格式,会导致插件 vuepress-plugin-permalink-pinyin 中文路由转拼音失效
module.exports = { permalink: "/:year/:month/:day/:slug", };
参看:https://github.com/vuepress-reco/vuepress-theme-reco/issues/395
2. 文章一级标题不在目录中显示
在 vuepress-theme-reco
中,请摒弃一级标题,使用 front-matter
生成标题以及其他文章信息,正文从二级标题开始。