展示

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: 配置文件的入口文件，也可以是 YML 或 toml。
  • docs/.vuepress/enhanceApp.js: 客户端应用的增强。

注意：当你想要去自定义 templates/ssr.html 或 templates/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参数表示是否开启主页
  • heroImage和heroImageStyle用于设置首页图
  • actionText和actionLink用于设置首页转跳按钮和转跳的位置
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！')
```
:::

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