前言
在这个信息爆炸的时代,拥有一个个人知识库无疑是一个巨大的优势。今天,我将分享如何利用 VuePress、GitHub Pages、PicGo 和腾讯云对象存储来搭建一个高效、美观且易于维护的个人知识库。
技术架构
VuePresss+GitHub Pages+picgo+腾讯云对象存储+任意Markdown编辑器 (个人推荐Typora,Obsidian,Yank Note)+git
利用 VuePresss 组件可以将 Markdown 语法转换成静态网页的优点配合 GitHub Pages 免费存放静态网页的有点可以做到 0 成本构建一个个人知识库,缺点是访问速度可能比较慢,而 picgo 和腾讯云对象存储二者合一做到图床的效果可以使知识库的图片传输速度达到一个提升正好弥补了访问速度的缺点。而我推荐的三款 Markdown 编辑器又正好支持将图片自动上传到图床并且转换链接,配合 git 简单的推送机制,这样一个属于自己的个人知识库就搭建完成了。并且插入的图片因为是使用图床的原因使用可以直接复制 md 文件进意见多平台发布。
前期准备
-
node
-
git
-
GitHub 账号
-
腾讯云对象存储
一、PicGo 图床搭建
安装 PicGo
PicGo 是一个用于快速上传图片并获取图片 URL 链接的工具,支持腾讯云 COS、七牛图床、Github 图床、又拍云图床、SM.SM 等。
我们以 Windows 为例,首先访问 Github 仓库去下载(点击跳转)客户端安装包,找到自己最新版自己看着顺眼的版本,找到对应平台的安装包,点击下载:
下载之后正常安装即可
安装 webp 插件
PicGo 有一系列好用的插件,帮助扩展功能,比如压缩图片、添加水印等等。本文将以 webp 插件为例,演示如何在 PicGo 中使用插件。
webp 插件会在图片上传前将图片转为 .webp
格式,它相比于传统的 .jpg
、.png
等格式,同等体积质量更高,同等质量体积更小。图片经过压缩之后再上传至 COS,对于节省存储空间,节省流量都很有帮助。如果对图片格式有特殊要求,不希望转换格式,可以省略这一步。
打开 PicGo,进入插件设置,在搜索栏输入插件名字即可搜索并安装,非常方便:
COS 对象存储
COS(Cloud Object Storage,对象存储)是由腾讯云推出的一种分布式存储服务。它的特点是无目录层次结构、无数据格式限制,可容纳海量数据,支持 HTTP/HTTPS 协议访问。腾讯云 COS 的存储桶空间无容量上限,无需分区管理,适用于 CDN 数据分发、数据万象处理或大数据计算与分析的数据湖等多种场景。
创建存储桶
按需要填写各项即可,需要注意的地方是访问权限的选择,默认是私有读写,适合存储隐私机密文件;本文选择了公有读私有写,是因为这个存储桶主要是做图床服务,用来存储图片,并能对外提供公开访问。
然后一直点下一步,创建即可。
创建成功后,来到存储桶列表,记录下存储桶的名称,和所属地域的代号,如图示例,也就是 ap-shanghai
。
创建 API 秘钥
进入【访问管理】 - 【访问秘钥】 - 【API 秘钥管理】(点此访问),会提示是否使用子账号管理,可根据实际需要进行选择,这里我们直接使用主账号进行创建。
创建成功,将 APPID,SecretId,SecretKey 保存下来,非常重要,谨防外泄。
配置 PicGo 图床服务
打开安装好的 PicGo 客户端,进入【图床设置】 - 【腾讯云 COS】,将上面保存的内容填写到配置中:
- COS 版本:选择 COS v5。
- 设定 Secretld:开发者拥有的项目身份识别 ID,用于身份认证,可在 API 密钥管理 页面中创建和获取。
- 设定 SecretKey:开发者拥有的项目身份密钥,可在 API 密钥管理 页面获取。
- 设定 Bucket:存储桶,COS 中用于存储数据的容器。有关存储桶的进一步说明,请参见 存储桶概述 文档。
- 设定 AppId:开发者访问 COS 服务时拥有的用户维度唯一资源标识,用以标识资源,可在 API 密钥管理 页面获取。
- 设定存储区域:存储桶所属地域信息,枚举值可参见 可用地域 文档,例如 ap-beijing、ap-hongkong、eu-frankfurt 等。
- 设定存储路径:图片存放到 COS 存储桶中的路径。
- 设定自定义域名:可选,若您为上方的存储空间配置了自定义源站域名,则可填写。相关介绍可参见 开启自定义源站域名。
- 设定网址后缀:通过在网址后缀添加 COS 数据处理参数实现图片压缩、裁剪、格式转换等操作,相关介绍可参见 图片处理。
其中,Bucketm,是存储桶名称
存储路径,也就是图片上传后在存储桶内的目录结构,可根据需要填写。如果填写,存储桶会自动创建出对应的目录结构。注意要以 /
结尾表示是一个目录。
自定义域名,COS 对应存储桶内的文件会有一个默认的 url,域名非常长不容易记,比如我的就是 https://kunwu-1251820157.cos.ap-beijing.myqcloud.com
,所以 COS 支持自定义域名。如果 COS 中绑定了自定义域名(这是前提),然后再填写该项,则 PicGo 会拿到改写后的文件 url。如果没有绑定自定义域名,可以忽略该项。
然后点击确定,并设为默认图床。
然后,进入【PicGo 设置】,将【上传前重命名】、【时间戳重命名】打开,这样可以防止图片重名
测试
打开 PicGo 上传区,选择本地的一张图片,然后上传。上传前会自动根据时间戳进行重命名,也可以自己修改:
点击确定,图片就会进行上传了。
PicGo 的相册功能,会展示已经上传的图片,并提供了复制图片 url,编辑图片 url 和移除相册的基础操作。需要注意的是,仅仅是删除本地的数据,云端的图片不会受影响。
来到腾讯云 COS 控制台,进入对应的存储桶中,可以发现图片已经上传成功了:
存储桶内的每个文件都会有一个唯一的访问地址,点击【详情】查看:
使用图床:在 Typora 粘贴图片时自动上传
打开 Typora,进入【文件】- 【偏好设置】- 【图像设置】,进行三个设置:
- 插入图片时,执行上传图片操作
- 上传服务采用 PicGo(app)
- 设置 PicGo 程序的安装路径
之后,当我们使用 typora 编写 md 文档,在插入图片时,会自动唤起 PicGo 客户端,并上传图片到目标平台。
使用图床:在 YankNote 粘贴图片时自动上传
打开 YankNote 左下角齿轮图标 -【图片】勾选上
使用图床:在 Obsidian 粘贴图片时自动上传
安装一款一款名为“Image auto upload plugin”的 Obsidian 插件,安装后,直接使用默认设置,无需做任何更改。
之后,你可以将图片粘贴,或拖动到 Obsidian 中,插件和 Picgo 会自动上传图片,并在对应的位置自动插入图片链接予以展示。
小结
到此,一个基于腾讯云 COS + PicGo 搭建的图床服务就完成了。总结一下整个流程:
- 实名注册腾讯云账号,并开通 COS
- 创建存储桶,创建 API 密钥
- 本地安装 PicGo 客户端工具,并根据需要配置插件
- 在图床设置中,将各项配置都填写正确
- 结合自己常用的其他工具,比如 Typora 等使用图床服务
二、本地搭建 VuePress
1. 安装 Node.js
下载并安装 Node.js (opens new window).
2. 安装 Yarn
使用命令行程序全局安装包管理器 Yarn.
npm install -g yarn
3. 安装 VuePress
新建一个文件夹可以是任意名字,使用命令行程序访问到创建的项目目录。以本地依赖形式安装。后创建 /docs 目录用来后续存放需要编写的文章。
# 将 VuePress 作为一个本地依赖安装
yarn add -D vuepress
# 新建一个 docs 目录
mkdir docs
# 写入内容
echo '# Hello VuePress' > docs/README.md
4. 配置 VuePress
编写脚本 修改 package.json 文件,添加一些脚本:
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
值得注意的是因为是追加内容,所以需要在本原来的最后一项后加上逗号。例如:
{
"devDependencies": {
"vuepress": "^1.3.1"
},
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
5. 在本地启动服务器
yarn docs:dev # npm run docs:dev
VuePress 会在 http://localhost:8080 (opens new window) 启动一个热重载的开发服务器。
基础配置
在文档目录下创建一个 .vuepress
目录,所有 VuePress 相关的文件都会被放在这里。此时你的项目结构可能是这样:
.
├─ docs
│ ├─ README.md
│ └─ .vuepress
│ └─ config.js
└─ package.json
在 .vuepress
文件夹下添加 config.js
,配置网站的标题和描述,方便 SEO:
module.exports = {
title: '菜鸡林某の blog',
description: '菜鸡林某の blog'
}
此时界面类似于:
添加导航栏
我们现在在页首的右上角添加导航栏,修改 config.js
:
module.exports = {
title: '菜鸡林某の blog',
description: '菜鸡林某の blog',
themeConfig: {
nav: [
{ text: '首页', link: '/' },
{
text: '菜鸡林某の blog',
items: [
{ text: 'Github', link: 'https://github.com/adrian803' },
]
}
]
}
}
效果如下:
更多的配置参考 VuePress 导航栏。
添加侧边栏
现在我们添加一些 md 文档,目前文档的目录如下:
.
├─ docs
│ ├─ README.md
│ └─ .vuepress
│ └─ config.js
| └─ handbook
| └─ 1.md
| └─ 2.md
└─ package.json
我们在 config.js
配置如下:
module.exports = {
themeConfig: {
nav: [...],
sidebar: [
{
title: '欢迎学习',
path: '/',
collapsable: false, // 是否折叠
children: [
{ title: "博客介绍", path: "/" }
]
},
{
title: "基础学习",
path: '/handbook/1',
collapsable: false, // 是否折叠
children: [
{ title: "博客搭建", path: "/handbook/1" },
{ title: "博客搭建", path: "/handbook/2" }
],
}
]
}
}
对应的效果如下:
更换主题
现在基本的目录和导航功能已经实现,如果还想要 loading
效果、切换动画、模式切换(暗黑模式)、返回顶部、评论等功能呢,为了简化开发成本,我们可以直接使用主题,我使用的主题是 vuepress-theme-reco:
现在我们安装 vuepress-theme-reco:
npm install vuepress-theme-reco --save-dev
# or
yarn add vuepress-theme-reco
部署到 GitHub
到这里,我们的博客网站基本搭建好了,接下来我们将它部署到 Github Pages 上。我们首先在 Github 上新建一个仓库,这里我取名为:blog。
完善 Repository
-
完善
README.md
在 Repository 页面完善项目信息,点击README.md
文件的编辑按钮进入编辑界面,使用 Markdown 语法编写对该项目更详细的描述。完成后点击Commit changes
按钮来提交本次修改。
-
编写
.gitignore
很多文件我们不需要同步到 GitHub 仓库里,使用.gitignore
文件来标识出哪些文件或目录不需要同步。
在仓库首页点击Creat new file
按钮进入编辑界面。输入新建的文件名:.gitignore
,并填写内容:“node_modules”。(根据你使用的 IDE 不同,也许你需要添加".vs" 或者 “.idea” 等内容来避免同步 IDE 独特的项目信息,请根据需求自行添加。)
完成后点击Commit changes
按钮来提交本次修改。
安装和配置 Git
- 安装并部署你的 Git
下载并安装相关的程序,运行并配置你的账户。你可以根据廖雪峰老师的这个教程来安装。廖雪峰的官方网站 - 安装 Git(opens new window) - 建立本地和远程仓库的连接
生成本地 SSH Key,并提交 GitHub。使用命令关联远程仓库。
具体请参考:廖雪峰的官方网站 - 远程仓库 (opens new window) - 本地仓库初始化
在本地仓库的根目录下,使用命令初始化本地仓库。git init git remote add origin <repo> # 这里的 repo 是你的仓库地址 git add . git commit -m "init"
利用 GitHub Actions 自动部署
生成 token
进入 Github 后,点击我们的头像,然后依次进入 Settings -> Developer settings -> Personal access tokens,对应地址就是 Token 生成:
配置 secrets
进入你存放你博客源码的项目,然后以此点击 Settings -> Secrets,接着点击右上角的 New repository secret,新建一个 Secret。这里的名字要命名为 ACCESS_TOKEN,然后 Value 就是我们上一步中所生成的 Token。
设置好之后效果:
编写 action
进入项目的的 Actions 选项,然后新建一个 workflow,默认新建的 workflow 名字是 main.yml 这个自定义。内容参考下面
# name 可以自定义
name: Deploy GitHub Pages
# 触发条件:在 push 到 main/master 分支后,新的 Github 项目 应该都是 main,而之前的项目一般都是 master
on:
push:
branches:
- master
# 任务
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 docs:build
# 部署到 GitHub Pages
- name: Deploy
uses: JamesIves/github-pages-deploy-action@4.1.3 #
with:
ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }} # 也就是我们刚才生成的 secret
BRANCH: gh-pages # 部署到 gh-pages 分支,因为 main 分支存放的一般是源码,而 gh-pages 分支则用来存放生成的静态文件
FOLDER: docs/.vuepress/dist # vuepress 生成的静态文件存放的地方
填写完毕点击 Add secret,如果填写没有问题的话,点击之后就会提示添加成功。
每次当你将 Vuepress
项目提交到 Github
上的时候,Github
就会自动帮你部署项目。
小结
通过上述步骤,你可以轻松搭建一个个人知识库。这个知识库不仅可以帮助你更好地组织和分享你的知识,还可以通过 GitHub Pages 免费托管,实现全球访问。
参考资料
关注我们
剑芸信息安全团队:
剑芸安全团队于 2022 年 9 月正式成立,以互联网攻防技术研究为目标的安全团队,目前聚集了十多位专业的安全攻防技术研究人员,重点关注网络攻防、Web 安全、移动终端、安全开发、IoT/ 物联网 / 工控安全等方向。