展示

1.第一位是我友链里的一位大佬的,虽然他已经转来🦋 点我查看

2.znote大佬,博客搭建在Gitee上和我一样哈哈,关键他提供全站下载哦,我最早就是拿他的修改的,伸手党😄 点我查看

3.第三位当然是reco主题的作者,作者非常热心,帮我解决很多问题,他的博客也有很多优秀案例, 作者官博 优秀案例

4.最后是本人vuepress博客💃,确切说文档📑,魔改🌟后更加简洁和轻便 小弋の阅览室

前言

公众号📽

先谈谈我为,什么写博客(注意断句),主要还是因为年纪大了,很多知识点记不住,好记性不如烂笔头就写下来,随时随地可以翻翻看看。最早我是在公众号上写文章,期间认识了很多大佬,比如搞机器学习的OPPO超厉害员工机智的叉烧哥,东南大学的AI蜗牛车大哥,拿遍国内互联网offer的本科生大数据肌肉猿等等,TM都是一等一的大佬啊!和他们深入交流之后真的学到很多,再看看自己写的东西完全看不下去,后有一顿时间又沉迷于公众号的排版,吸粉,流量,没法好好写文章啊😄

Mkdocs📖

自学大数据相关的知识时,在一位姓蔡的大哥指点下,开始用Mkdocs写文档,编译可以部署在GitHub和Gitee上,其简洁的页面,优雅的伸缩折叠侧边栏吸引了我,所以后来技术文档都是采用Mkdocs,看到自己的学习结果越来越多,这也是我为什么一直坚持记录的原因。

好景不长,当文章多了之后,尤其本地图片一多,编译速度直线下降,更不能忍的是热更新,python的弊端开始显现,用markdown改一个字,要等上两分钟才能看到效果,我开始寻找其他的开源博客框架。

WordPress💮

当时白嫖阿里云(参加各种活动),搞了一台为期2年的ECS云服务器,一直落灰,偶尔拿出来12306抢抢票,玩玩微信机器人实在浪费,后在刷b站的时候突然发现了WordPress,具体可以看我的阿里云服务器+宝塔+WordPress,闲鱼买了10000套主题,刚开始觉得很有意思,玩了几天发现索然无味,根本不适合写文章,而且服务器早晚也会过期,我还是想找一个静态博客。

Hexo🦋

最后还是在那位姓蔡的大哥指点下,转向用Hexo写文章,hexo是一个快速、简洁且高效的博客框架,采用Markdown(或其他渲染引擎)解析文章,在几秒内,即可利用靓丽的主题生成静态网页,还有一堆堆的插件和主题。为了把网页做漂亮,疫情在家期间我还自学了HTNL+CSS+JS,虽然只是入门但是修改主题已经得心应手,推荐一下butterfly主题

Vuepress📀

可是已经有了hexo博客,为什么要还要大费周章搞个vuepress,主要还是想回归写单纯技术文档的时光,vuepress拥有更加强大的折叠侧边栏,可以在Markdown中使用Vue组件,又可以使用 Vue 来开发自定义主题。之前的vuepress一直有热更新的问题,所以我也一直在观望,最近的1.5.2版本已经解决了bug,是时候动手了,打算把Mkdocs上的文章迁移过来。

展望🏩

  • 未来打算在hexo上写一写生活心得,安装教程,各种技巧魔改等
  • 技术文档和hexo分离,在Vuepress上完成

Vuepress搭建教程

由于Vuepress官方文档说明已经非常详细,上手难度总体不是很高,这里主要针对关键配置进行说明,排除一些坑

  1. 安装nodejs环境
  2. 安装git
  3. 简单上手
  4. 使用reco主题搭建Vuepress
  5. 编写脚本,并部署到gitee

像数 1, 2, 3 一样容易

简单上手,如果能正常显示网页说明安装ok

1
2
3
4
5
6
7
8
9
10
11
# 安装
npm install -g vuepress

# 新建一个 markdown 文件
echo '# Hello VuePress!' > README.md

# 开始写作
vuepress dev .

# 构建静态文件
vuepress build .

使用reco主题

默认主题也不错,不过我这里推荐使用vuepress-theme-reco主题

1
2
3
4
5
6
7
8
9
10
# 初始化
npm install @vuepress-reco/theme-cli -g
theme-cli init my-blog

# 安装
cd my-blog
npm install

# 运行
npm run dev

待启动成功后打开地址即可:http://localhost:8080

另外可以生成静态文件,方便上传到托管平台部署

1
npm run build

了解目录结构

VuePress 遵循 “约定优于配置” 的原则,推荐的目录结构如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
.
├── docs
│ ├── .vuepress (可选的)
│ │ ├── components (可选的)
│ │ ├── theme (可选的)
│ │ │ └── Layout.vue
│ │ ├── public (可选的)
│ │ ├── styles (可选的)
│ │ │ ├── index.styl
│ │ │ └── palette.styl
│ │ ├── templates (可选的, 谨慎配置)
│ │ │ ├── dev.html
│ │ │ └── ssr.html
│ │ ├── config.js (可选的)
│ │ └── enhanceApp.js (可选的)
│ │
│ ├── README.md
│ ├── guide
│ │ └── README.md
│ └── config.md

└── package.json

请留意目录名的大写。

  • docs/.vuepress: 用于存放全局的配置、组件、静态资源等。
  • docs/.vuepress/components: 该目录中的 Vue 组件将会被自动注册为全局组件。
  • docs/.vuepress/theme: 用于存放本地主题。
  • docs/.vuepress/styles: 用于存放样式相关的文件。
  • docs/.vuepress/styles/index.styl: 将会被自动应用的全局样式文件,会生成在最终的 CSS 文件结尾,具有比默认样式更高的优先级。
  • docs/.vuepress/styles/palette.styl: 用于重写默认颜色常量,或者设置新的 stylus 颜色常量。
  • docs/.vuepress/public: 静态资源目录。
  • docs/.vuepress/templates: 存储 HTML 模板文件。
  • docs/.vuepress/templates/dev.html: 用于开发环境的 HTML 模板文件。
  • docs/.vuepress/templates/ssr.html: 构建时基于 Vue SSR 的 HTML 模板文件。
  • docs/.vuepress/config.js: 配置文件的入口文件,也可以是 YMLtoml
  • docs/.vuepress/enhanceApp.js: 客户端应用的增强。

注意:当你想要去自定义 templates/ssr.htmltemplates/dev.html 时,最好基于 默认的模板文件 来修改,否则可能会导致构建出错。

编写config.js

参考:https://vuepress-theme-reco.recoluan.com/views/1.x/configJs.html

这个是vuepress的主要配置文件,放于.vuepress文件夹下,以下是我的配置,这里说明一下

  • 导航栏分离出去,避免全部写在config.js显得很杂乱
  • 侧边栏分离出去
  • 插件分离出去
  • 注意这里的base选项,因为我在gitee上已经有了我的主站hexo,所以vuepress部署到二级目录,这里一定要设置二级目录名
  • type参数注释,这样会显示首页,不会直接进入博客
  • 注意sidebarDepth参数,这个表示目录深度,我设置为2,具体请参考官方文档

二级目录一定要设置base参数。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
//const path = require('path')
const nav = require('./config/nav/')
const sidebar = require('./config/sidebar/')
const plugins = require('./config/plugins/')

module.exports = {
title: "会飞的小弋",
description: '每个牛逼的人,都有一段苦逼的坚持!',
//dest: '/blog/',
// 如果是二级域名
base: '/blog/',
head: [
// 网页标签栏图标
['link', { rel: 'icon', href: '/vuepress/favicon.ico' }],
// 移动栏优化
['meta', { name: 'viewport', content: 'width=device-width,initial-scale=1,user-scalable=no' }]
],
theme: 'reco',
themeConfig: {
nav,
sidebar,
//type: 'blog',

// 博客设置
blogConfig: {
category: {
location: 2, // 在导航栏菜单中所占的位置,默认2
text: 'Category' // 默认 “分类”
},
tag: {
location: 3, // 在导航栏菜单中所占的位置,默认3
text: 'Tag' // 默认 “标签”
}
},
// 友链
friendLink: [
{
title: '午后南杂',
desc: 'Enjoy when you can, and endure when you must.',
email: '1156743527@qq.com',
link: 'https://www.recoluan.com'
},
{
title: 'vuepress-theme-reco',
desc: 'A simple and beautiful vuepress Blog & Doc theme.',
avatar: "https://vuepress-theme-reco.recoluan.com/icon_vuepress_reco.png",
link: 'https://vuepress-theme-reco.recoluan.com'
},
],
// 导航栏图标
logo: '/vuepress/avatar.gif',
// 搜索设置
search: true,
searchMaxSuggestions: 10,
sidebarDepth: 2,
// 自动形成侧边导航
// sidebar: 'auto',


// 最后更新时间
lastUpdated: 'Last Updated',
// 作者
author: '会飞的小弋',
// 作者头像
authorAvatar: '/vuepress/avatar.gif',
// 如果你的文档不在仓库的根部
//docsDir: 'docs',
// 备案号
//record: 'xxxx',
// 项目开始时间
startYear: '2019',
// 简体中文
locales: {
'/': {
lang: 'zh-CN'
}
},
/**
* 密钥 (if your blog is private)
*/

// keyPage: {
// keys: ['your password'],
// color: '#42b983',
// lineColor: '#42b983'
// },

/**
* valine 设置 (if you need valine comment )
*/

// valineConfig: {
// appId: '...',// your appId
// appKey: '...', // your appKey
// }
},
// 插件
plugins,
markdown: {
lineNumbers: true
}
}

编写主页md

参考:https://vuepress-theme-reco.recoluan.com/views/1.x/home.html

这里简单说明:

  • home参数表示是否开启主页
  • heroImageheroImageStyle用于设置首页图
  • actionTextactionLink用于设置首页转跳按钮和转跳的位置
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
---
home: true
heroText: 会飞的小弋
tagline: 每个牛逼的人,都有一段苦逼的坚持!
heroImage: /vuepress/hero.png
heroImageStyle: {
maxWidth: '490px',
width: '100%',
display: block,
margin: '1rem auto 1rem',
background: '#fff',
#borderRadius: '1rem',
}
#bgImageStyle: {
# height: '450px'
#}
isShowTitleInHome: false
actionText: 巅峰之路 →
actionLink: /views/
#features:
#- title: Yesterday
# details: 开发一款看着开心、写着顺手的 vuepress 博客主题
#- title: Today
# details: 希望帮助更多的人花更多的时间在内容创作上,而不是博客搭建上
#- title: Tomorrow
# details: 希望更多的爱好者能够参与进来,帮助这个主题更好的成长
---

效果如下

侧边栏sidebar

参考:https://vuepress-theme-reco.recoluan.com/views/1.x/sidebar.html

以下我展示两种折叠侧边栏的写法,第一种就是普通的侧边栏,第二种是分组侧边栏,可嵌套

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
//侧边栏
module.exports = {
// 以下是直接显示侧边栏
'/views/': [
'',
{
title: 'python爬虫',
collapsable: true,
sidebarDepth: 0,
children: [
'webc/01.Requests使用技巧',
'webc/02.数据存入Excel',

]
},
// 以下是分组形式
{
title: 'Group 1', // 必要的
path: '/views/', // 可选的, 标题的跳转链接,应为绝对路径且必须存在
collapsable: true, // 可选的, 默认值是 true,
sidebarDepth: 1, // 可选的, 默认值是 1
children: [
'webc/01.Requests使用技巧',
'webc/02.数据存入Excel',
{
title: 'Group 2', // 必要的
path: '/views/', // 可选的, 标题的跳转链接,应为绝对路径且必须存在
collapsable: true, // 可选的, 默认值是 true,
sidebarDepth: 1, // 可选的, 默认值是 1
children: [
'webc/01.Requests使用技巧',
'webc/02.数据存入Excel',
{
title: 'Group 1', // 必要的
path: '/views/', // 可选的, 标题的跳转链接,应为绝对路径且必须存在
collapsable: true, // 可选的, 默认值是 true,
sidebarDepth: 1, // 可选的, 默认值是 1
children: [
'webc/01.Requests使用技巧',
'webc/02.数据存入Excel',
{
title: 'Group 2', // 必要的
path: '/views/', // 可选的, 标题的跳转链接,应为绝对路径且必须存在
collapsable: true, // 可选的, 默认值是 true,
sidebarDepth: 1, // 可选的, 默认值是 1
children: [
'webc/01.Requests使用技巧',
'webc/02.数据存入Excel',

]
},
]
},
]
},
]
},


],
}

效果如下

安装插件

参考:https://vuepress-theme-reco.recoluan.com/views/plugins/#插件是什么

vuepress的插件不算多,但是个个精品,什么音乐播放器,流程图,看板娘也都有。

插件的下载:如果你有一个已经发布在 npm 的喜欢的插件,你可以使用以下命令来下载并安装它

1
npm i <packageName> -D

注意: 这里的包名需要全称,并不能省略 vuepress-plugin-

使用插件,可以简写:

1
2
3
module.exports = [
'flowchart'
]

这里注意,config.js里的plugins不能写到themeConfig里,切记!!!

另外说明一下,1.5.3版本的reco主题内置了一些插件,无需重复安装

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// 返回顶部插件
"@vuepress-reco/vuepress-plugin-back-to-top": "^1.4.0",
// 评论插件,集成了 Valine 与 Vssue 两种评论系统
"@vuepress-reco/vuepress-plugin-comments": "^1.4.6",
// 页面加载时过渡动画插件
"@vuepress-reco/vuepress-plugin-loading-page": "^1.4.0",
// 分页插件,帮助你快速跳转到任意页面
"@vuepress-reco/vuepress-plugin-pagation": "^1.4.7",
// 本插件是博客系统的基础,请不要禁用或者覆盖配置
"@vuepress/plugin-blog": "1.9.2",
// 图片缩放插件
"@vuepress/plugin-medium-zoom": "1.5.0",
// 搜索
"docsearch.js": "2.6.3",
// 加密
"md5": "2.2.1",
// 加密
"vue-click-outside": "1.1.0"

编写部署脚本与部署

和mkdocs一样,执行build后,会生成一个叫dist的文件,只要把这个文件push到仓库部署就行

1
npm run build

但是如果每次生成都要手动部署太麻烦,所以编写脚本,以部署到我的gitee仓库为例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 现已通过GitHub Actions自动部署,提交只需 'git push' 即可
# 若不想使用自动部署,可以直接运行命令 'npm run deploy' 本地自动提交部署

# 确保脚本抛出遇到的错误
set -e

# 生成静态文件
npm run build

# 进入生成的文件夹
cd .vuepress/dist/

# 如果是发布到自定义域名
# echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'
git remote add origin https://gitee.com/lovelijunyi/blog.git
#git checkout -b gh-pages

# 如果发布到 https://<USERNAME>.github.io
#git push -f git@github.com:zpj80231/zpj80231.github.io.git gh-pages
#git push origin :gh-pages
git push -u origin master -f

将文件命名为deploy.sh,再修改package.json如下,调整scripts,将deploy后的内容改为:bash deploy.sh

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
"name": "my-blog",
"version": "1.0.0",
"author": "lijunyi",
"scripts": {
"dev": "vuepress dev .",
"build": "vuepress build .",
"deploy": "bash deploy.sh"
},
"devDependencies": {
"@vuepress-reco/vuepress-plugin-bgm-player": "^1.1.3",
"@vuepress/plugin-medium-zoom": "^1.5.2",
"vuepress": "1.5.2",
"vuepress-plugin-flowchart": "1.4.3",
"vuepress-theme-reco": "1.5.3"
},
"dependencies": {
"vue-class-component": "^7.2.3"
},
"description": "巅峰之路"
}

最后只要双击deploy.sh就能实现自动上传部署

指南⏰

QQ浏览器不兼容

QQ浏览器的问题已经解决:happy:,还是吃了没文化的亏,请教了大佬知道内部调用的是IE的内核,所以不能显示,需要在设置中把内核从兼容模式,调整到极速模式,OK啦!

标题添加徽章

  • Props:
    • text - string
    • type - string, 可选值: "tip"|"warning"|"error",默认值是: "tip"
    • vertical - string, 可选值: "top"|"middle",默认值是: "top"
  • Usage:

你可以在标题中,使用这个组件来为某些 API 添加一些状态:

1
### Badge <Badge text="beta" type="warning"/> <Badge text="默认主题"/>

使用默认容器和标签

输入

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
::: tip
这是一个提示
:::

::: warning
这是一个警告
:::

::: danger
这是一个危险警告
:::

::: details
这是一个详情块,在 IE / Edge 中不生效
:::

输出

你也可以自定义块中的标题:

1
2
3
4
5
6
7
8
9
::: danger STOP
危险区域,禁止通行
:::

::: details 点击查看代码
```js
console.log('你好,VuePress!')
```
:::

更多自定义修改教程点这里