Typro + PicGo 图床 + Docsify + GitHub Pages，玩转个人知识库搭建，写给小白的建站入门课

AI码上来

已于 2024-08-08 07:47:36 修改

阅读量784

点赞数 24

分类专栏：玩转云服务文章标签： python typora Docsify GitHub Pages

于 2024-08-05 10:26:43 首次发布

本文链接：https://blog.csdn.net/u010522887/article/details/140919939

版权

玩转云服务专栏收录该内容

13 篇文章 0 订阅

订阅专栏

自动开了这个号以后，陆陆续续写了很多干货文章，一方面是可以帮助自己梳理思路，另一方面也方便日后查找相关内容。

但是，我想检索某个关键词是在之前哪篇文章写过的，就有点捉急了。CSDN 还好，可以检索到相关标题，知乎的检索就太差了，连标题都无法精准。

于是，一个需求出现了：把之前所有写过的文章扒下来，做成一个自己的知识库？然后，发布出去，方便自己，也共享他人。

如何实现？经过一番调研，最终确定了如下方案：

本地搭建：Typro + PicGo + 图床；
部署上线：Docsify + GitHub Pages 等托管平台。

本次分享将记录整个实现过程，以及踩过的坑，文章略长，全程干货，希望给有类似需求的小伙伴一点帮助。

1. 本地知识库搭建

由于平时的文章都是用在线的 Markdown 工具编写，本地 Markdown 编辑器自然首推 Typora。

1.1 Typora 安装和使用

首先，前往官网上找到对应你系统的版本: typora官方中文站。

Typora 的界面简洁明了，你可以专注于你的文本而不是复杂的排版，相信你编写 Markdown 文本一定非常愉快。

关于 MarkDown 中的图片，一般都是 ![](https://url.url)，我们需要首先保存到本地，为此可以先在 Typora 中进行一番设置：依次点击文件 -> 偏好设置 -> 图像，选择 复制图片到./assets文件夹，就可以自动将图片保存到当前文件夹下的 ./assets 目录下。

右上角支持知识库检索，实时渲染生成文章目录大纲：

如果你只是需要一个本地知识库，Typora 就完全可以满足所需，下面的内容可以不用看啦。

但是，如果你还想把知识库部署上线，接下来就会遇到一个问题：图片安放在哪？

1.2 图床选择和使用

互联网上的图片一般都会存放在专属服务器上，尤其是当你的图片数量规模变大以后，你在网页上看到的任何一张图片，背后其实就是一条 url。

图床 就是专门用来存放图片的，不过目前市面上可以选择的 图床 可太多了，到底该选择哪一个呢？

网上看了很多小伙伴的解决方案，下面我将先介绍下实测用过的一些图床，以及踩过的坑，最后给出我最终的选择：

Gitee 图床：个人仓库最大支持 500M，现在不可以使用了，因为 Gitee 的图片开启了防盗链，无法在你的网页中加载进来。
GitHub 图床：除了国内访问速度是个问题外，非常完美，而且个人仓库最大支持 1G 容量。访问慢的问题可以通过镜像的方式解决。但后面遇到的一个问题是：PicGo 上自动上传时，如果是同名文件就会上传失败，难以实现自动化。这个问题的解决方案是：在 PicGo 中设置上传时自动以时间戳命名，不过这样会产生大量重复图片，1G 空间怕是很快就爆了。
七牛云等云存储平台：七牛云虽然有 10G 免费空间，但需要有在国内备案的域名，必须要买域名+服务器，否则一个月之后就无法使用它的测试域名。
个人开发者的图床：都有一些限制，没找到合适的😂
- https://tu.my/：可以手动上传，单次上传不超过100张。
- https://imgchr.com/：每小时限制 8 张。
国内云厂商的对象存储：阿里云/腾讯云等免费试用后需要付费；
国外云厂商的对象存储：
- Google 云的对象存储：免费空间 5 G，每月 1G 的出站流量；
- Oracle 云的对象存储：免费空间 20 G，每月限制 50000次 API 调用，需要把桶设置为公共的，才可以访问；而且同名文件会自动替换，上传速度很快；访问速度也还可以，部分有延时。
- Cloudflare R2对象存储：免费空间 10 G，上传等 A 类操作每月100万次，下载等 B 类操作每月1000万次，需要绑定一张外币信用卡。

对比来看，还是 Oracle 云的对象存储免费空间更大，而 Cloudflare R2 的调用次数更加慷慨，最终先选择了 Oracle 云的对象存储作为我的图床。

当然，在正式使用之前，你还需要验证下选择的图床得到的 url 是否开启了防盗链。

怎么验证？

给大家分享一个最简单的方式：如下图所示，随便找一个在线的 markdown 编辑器，然后按照图片格式输入，看看能否在右侧渲染出来：

选择好图床后，最好是配合 PicGo 来使用，接下来我们一起看下这款 Typora 排版工具的完美搭档。

1.3 PicGo 安装和使用

PicGo 是一个开源的图床工具，加上插件，可以完美适配各种图床。大家可以前往官方仓库的 Releases 中下载：https://github.com/Molunerfinn/PicGo/releases。

界面非常简单，你只需要根据你选择的图床进行适配就可以了，下面介绍几个常见图床的使用：

1.3.1 GitHub 图床

首先，需要在你的 GitHub 上新建一个仓库，分支名在 GitHub 上新建仓库时默认为 main，必要时调整为你新建的分支名。

下面的 设定 Token 在哪获取？

在你的 GitHub 主页依次选择【Settings】-最下方的【Developer settings】-【Personal access tokens】-【Generate new token】，填好名称，过期时间最长可以选择一年，然后点击【Generate token】生成一个 Token。

Token 只会显示一次，先保存下来，再配置到 PicGo 中。

最后的设置自定义域名，其作用是加速 GitHub 图片的访问，在图片上传后，PicGo 会按照(自定义域名+储存路径+图片名)的方式生成访问链接，返回给你。

我们来总结下上面几个字段的填法：

设定仓库名：按照用户名/项目名的格式填写
设定分支名：main or master
设定Token：粘贴上面生成的 Token
指定存储路径：想要储存的路径，如 imgs，会在你项目下创建一个名为 imgs 的文件夹，图片将会储存在此文件夹中。
设定自定义域名：有两种方式可以实现加速。
- 使用 jsDelivr 加速：设置为 https://cdn.jsdelivr.net/gh/用户名/项目名，上传完毕后，通过 https://cdn.jsdelivr.net/gh/用户名/项目名/图片名 访问上传的图片。
- 使用镜像加速：设置为 https://mirror.ghproxy.com/https://raw.githubusercontent.com/用户名/项目名/master/。

1.3.1 Gitee 图床（不推荐）

PicGo 本身不支持 Gitee 图床，因此需要在 PicGo 中安装插件。搜索框中搜一下 gitee，然后任选一个即可。

**要注意的是：**插件安装需要依赖 node.js 环境，这个需要前往 node.js 官网，下载对应操作系统的进行安装。Windows 的比较简单，下载完成之后双击安装包，即可进行安装。安装完成之后，打开 cmd 输入 node -v 验证一下，输出版本号就是安装成功。

安装完成后，在图床设置中就可以看到 gitee 的选项，配置和上面的 GitHub 图床类似，不再赘述了。

不过，因为 Gitee 的图片开启了防盗链，所以 Gitee 图床还是放弃使用吧。

1.3.3 自定义图床

如果你的图床不在 PicGo 官方支持之列，那么就需要安装另外一个插件。

什么插件？

插件设置那里搜索 web-uploader 进行安装即可，安装完成后，在图床设置中就可以看到 自定义Web图床 的选项，根据你图床提供的 API 进行填写即可。

1.3.4 图床测试

最后，设定好之后，来到上传区，选择你的图床，上传一张图片，测试一下是否能上传成功。

1.3.5 PicGo 集成到 Typora

PicGo 的图床准备好之后，我们需要在 Typora 中进行一番设置：依次点击文件 -> 偏好设置 -> 图像，找到最下面的 上传服务，选择 PicGo(app)，路径选择你的安装地址，最后点击验证图片上传选项，验证一下能否上传正常。

如果上传失败了怎么办？

PicGo 的上传日志一般保存在：C:\Users\12243\AppData\Roaming\picgo\picgo.log，可以前往查看具体的报错信息。

然后，我们到上面的 插入图片时...，选择 上传图片，这样你每次在文档中插入图片，它会自动给上传到图床，然后返回一个 url 插入到文档中，非常方便。

当然，也可以在你的文档中，依次选择格式 -> 图像 -> 上传所有本地图片，就会把文档中所有图片一键上传到图床。

至此，你的本地知识库基本就搭建完成了，后续往里增加内容将会变得 so easy~

2. 在线知识库部署

如何把本地的知识库部署上线，和你的小伙伴分享？

前几天，我们一起盘点了：小白搭建静态网站，都有哪些建站工具？

今天这个需求不就用上了。

那么多建站工具，我该选哪个呢？

对于知识库这样一个简单需求，当然首选 docsify。为啥?

和 GitBook 以及 Hexo 等建站工具不同的是，它会智能地加载和解析 Markdown 文件，而无需生成 html 文件，所有转换工作都在运行时。此外，我认为 Docsify 最大的优点有以下几个方面：

无需安装任何依赖，无需编译，完全运行时驱动。
界面清新，看着就很爽，多个主题可供选择
插件生态丰富

2.1 docsify 安装和使用

官方文档：https://docsify.js.org/#/zh-cn/

2.1.1 docsify 安装

docsify 安装需要依赖 node.js，相信你在上一步按照 PicGo 插件时已经装好了 node.js。

准备好 node.js 环境后，在终端中采用 npm 一键安装：

npm install -g docsify-cli

上述指令中，-g 代表全局安装，因为我们需要用到 docsify 的场景还挺多，所以就选择全局安装了。

怎么知道这个全局安装的包放在哪了？

npm root -g

这会返回全局安装目录的路径。默认情况下会放在你的 C 盘：C:\Users\<YourUsername>\AppData\Roaming\npm。

如果不想你的 C 盘很快爆满的话，最好给它挪个位置~

这时，你可以修改 npm 的全局安装位置。首先新建一个目录，然后在终端中配置 npm 使用新的目录：

npm config set prefix D:\npm-global

可以看到文件夹下多了一个 node_moudules，可执行文件也在当前目录下：

为了系统自动识别到 docsify 命令，你还需要添加新的路径到系统环境变量中。具体步骤如下：

右键点击“此电脑”或“计算机”，选择“属性”。
点击“高级系统设置”。
在“系统属性”窗口中，点击“环境变量”。
在“系统变量”中找到 Path，然后点击“编辑”。
添加新的路径 D:\npm-global。

对于新手小白来说，还会遇到一个问题：npm 下载太慢啦~

这是因为 npm 默认从国外的 https:/registry.npmjs.org/ 服务器进行下载，不信你试试看下面这个指令：

// 查看当前下载地址
npm config get registry

所以你需要给它换个国内的镜像。

// 设置淘宝镜像的地址
npm config set registry https://registry.npmmirror.com/

再次安装 docsify，有没有快到飞起？

2.1.2 docsify 启动

docsify 安装好之后，启动知识库只需要一个命令（在你的当前知识库文件夹下执行）：

docify init

如果文件夹下已经有文件，也没关系，选择 yes，会初始化3个文件，其中 index.html 就是最终渲染的初始网页：

接下来，还是一键命令完成部署：

docsify serve

# 输出如下
Serving D:\data\projects\knowledgebase now.
Listening at http://localhost:3000

打开上述链接，你会看下如下页面：

这些文字内容是哪来的呢？

还记得刚才生成的三个文件中的 README.md，打开看看吧。

所以，你只需要编辑这个 README.md，就可以实现你的内容展示了。

你不需要杀掉 serve 指令，docisfy 支持修改 README.md 时，网页端实时更新。

接下来我们来说说这个 index.html 中的一些具体设置，将你的网页打造的更加酷炫、高级一些。

2.1.3 docsify 基础操作

网站主题修改:

在 index.html 中：

<!--这个链接就是主题的选择-->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">

官网支持的主题在：https://cdn.jsdelivr.net/npm/docsify@4/lib/themes/，都去试试吧，看看自己更喜欢哪个~

封面设置:

只需在 window.$docsify 中加入一行:

window.$docsify = {
    coverpage: true,
  }

然后，创建一个 _coverpage.md 文件，编写 markdown 内容并保存：

![logo](media/logo_thumbnail.png)
# 猴哥的AI知识库 <small>2024</small>

> 用心做内容，不辜负每一份关注。

适合人群：

- AI 爱好者
- AI 小白

[GitHub](https://github.com/hougeai/knowledgebase)
[Get Started](README.md)

顶部导航栏设置:

只需在 window.$docsify 中加入:

window.$docsify = {
    repo: 'https://github.com/hougeai/knowledgebase', // 仓库链接，会显示在右上角GitHub图标
    loadNavbar: true,
  }

docsify 会默认加载 _navbar.md，所以需要新建一个 _navbar.md，然后填入你想要在导航栏要展示的内容：

- [1.Linux笔记](docs/1.Linux笔记/README.md)
- [2.玩转云服务](docs/2.玩转云服务/README.md)
- [3.AI笔记](docs/3.AI笔记/README.md)
- [4.Python笔记](docs/4.Python笔记/README.md)
- [5.效率工具](docs/5.效率工具/README.md)
- [6.少儿编程](docs/6.少儿编程/README.md)

这样你在网站上就会看到：

侧边栏设置:

只需在 window.$docsify 中加入一行:

window.$docsify = {
    loadSidebar: true
  }

然后，创建一个 _sidebar.md 文件，编写你想要展现的目录内容并保存。

2.1.4 docsify 插件配置

docsify 的生态非常丰富，开发者搞了很多插件，为你的知识库插上三头六臂，变得更为智能，而这些插件就是一个个 javascript 脚本，你只需要在 index.html 中插入即可。

这里给大家推荐几个最常用到的。

1. 搜索插件

随着文章的增多，搜索功能就显得尤其必要，你只需要在 index.html 的如下位置填入：

window.$docsify = {
    search: {
        paths: 'auto',
        placeholder: 'Type to search',
        noData: '找不到结果',
        depth: 3,
      },
  }

然后在最下方引入插件脚本：

<!-- 搜索插件 -->
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>

此时，在你的网站左上角就可以看到搜索栏：

2. 右侧目录插件

我的文章很多偏实操，所以内容比较长，如果能够在右侧显示文章目录，支持滚动高亮，点击跳转等，显然更符合当下流行的文档网站布局，类似下面这样。

这时你只需要一个插件，叫 toc (Table of Content)。不过社区中有两种实现：

<script src="https://cdn.jsdelivr.net/npm/docsify-plugin-toc@1.3.1/dist/docsify-plugin-toc.min.js"></script>
<!-- <script src="https://unpkg.com/docsify-toc@1.0.0/dist/toc.js"></script> -->

一开始我是采用的第二行的插件，后来发现它和 sidebar(也就是左侧目录) 会出现冲突，看了下报错应该是插件内部的 bug。所以又找到了第一行的插件，再配置下 window.$docsify，完美实现上图中的效果！

window.$docsify = {
  toc: {
        tocMaxLevel: 5,
        target: 'h1, h2, h3, h4, h5, h6',
        ignoreHeaders: ['<!-- {docsify-ignore} -->', '<!-- {docsify-ignore-all} -->']
        },
      }

3. 代码复制和高亮插件

技术文章很多都有代码，为了实现代码一键复制和高亮，类似如下效果：

你只需要插入如下插件：

<!-- 代码复制 -->
<script src="//cdn.jsdelivr.net/npm/docsify-copy-code"></script>
<!-- 代码高亮 --> 
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-c.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-json.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-shell-session.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-python.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-java.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-http.min.js"></script>

2.2 远程仓库建立

本地测试没什么问题后，接下来我们就需要把它托送到云端了。

因为知识库一定是会不断更新的，所以最好用 git 来维护一个远程仓库。

2.2.1 本地 git 初始化

这里值得注意的是，如果你在本地存了很多图片，最好不要把他们推送上去。

拿我的来举例：项目中每个子文件夹都有存放图片的 assets 文件夹，现在需要
要在 .gitignore 中忽略所有子文件夹中的 assets 文件夹，可以项目根目录下创建 .gitignore ，然后填入以下规则：

**/assets/

**/ 表示匹配任意层级的目录。
assets/ 确保只忽略名为 assets 的文件夹。

这样，所有子文件夹中的 assets 文件夹都会被 Git 忽略。

然后一键三连，完成项目初始化：

git init
git add .
git commit -m 'first commit'

这样本地仓库就建好了，接下来你需要的是一个远程仓库。

2.2.2 关联远程仓库

这里我们选择在 GitHub 上新建远程仓库，因为各大网页部署平台对 GitHub 的支持最为友好。

注意：上面的 Private 要改为 Public，需要是公开仓库才可以部署到 GitHub Pages。

接下来，在本地终端中进行账户设置，填入你的 GitHub 的注册名称和邮箱：

# git 全局设置
git config --global user.name "your_user_name"
git config --global user.email "xxx@xx.com"
# 如果只需要设置当前项目
git config user.name "your_user_name"
git config user.email "xxx@xx.com"

将本地仓库推送到远程仓库：

git remote add origin https://github.com/xxx/xxx.git
git push -u origin "master"

上面的 origin 是你在本地给远程仓库取的名字，一般用不到它。如果将来需要删除和它的关联，才会用到它：

git remote -v
git remote remove origin

2.3 部署工具选择

GitHub 远程仓库有了之后，我们就要选择一个工具将网站部署上线。都有哪些选择呢？

公有云主机 / VPS：买域名，买服务器，需要一笔不菲的开销；
Github/Gitee/Gitlab Pages 等静态网站生成器：完全免费，支持持续集成
Netlify/Zeabur 等托管平台：有一定免费额度，支持自定义二级域名。

综合来看，对于简单的知识库网站而言，后面两种方案完全可以满足需求。

下面我们就一起实操下，分别将网站部署到：

Gitee Pages + Github Pages
Netlify + Zeabur

2.4 网站部署

2.4.1 Gitee Pages

如果你需要部署在 Gitee Pages 上，首先需要在 Gitee 新建一个远程仓库并和本地仓库进行关联，当然如果已经有了 GitHub 远程仓库，也可以选择 fork 过来。然后在项目首页如下位置找到 Gitee Pages ：

遗憾的是：
因服务维护调整，Gitee Pages 暂停提供服务，给您带来不便深感抱歉，感谢对 Gitee Pages 服务的支持。

看来国内审核压力也给到 Gitee 了~

2.4.2 GitHub Pages

进入你的远程仓库首页，在 Settings -> Pages 中，选择你的分支 master，选择在根目录部署，这个主要根据你的 index.html 所在的位置进行选择。

到这里，一个拥有 github.io 二级域名的 page 就已经建好了：

访问地址：https://hougeai.github.io/knowledgebase

是不是很简单？

如果您想拥有一个个性化的域名怎么办？

你得掏腰包去域名服务商买一个心仪的域名。如果你只是想拿来玩玩，当然也有免费域名可以注册，可以参考这篇：【保姆级教程】免费域名注册 & Cloudflare 域名解析。

拿到域名之后，还需要进行域名解析。

具体而言，在域名解析服务器中添加一条 DNS 记录，参考官方文档，github 可以用的 IP 地址如下：

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

以我的举例：参考上篇教程进行域名解析，前往 cloudfare 官网，添加一条 DNS 记录：

再前往 github pages 配置页，填入你的域名，等待 DNS 解析成功。

最后，回到 github pages 配置页上方，打开你的专属链接看看吧~

访问地址：https://kb.houge.us.kg/#/：

如果您希望 GitHub Pages 在仓库代码更新后能够自动更新？

GitHub Actions 来了解下：通过设置自动化流程，在依赖仓库代码更新后自动触发 GitHub Pages 的更新。GitHub Actions 就是 GitHub 推出的持续集成服务。

首先，需要配置下项目的 Actions：

其中

Actions permissions：一定要选择 Allow all actions and reusable workflows，否则你将无法使用别人的 Action。
最下面的 Workflow permissions，如果你的项目需要 build，则要给读写权限，如果只是静态网页，保持默认的读权限即可。

然后，开始配置 Actions 工作流。

官方的 actions 都放在 https://github.com/actions 里面。

我们这个项目只需要简单的自动更新页面，点击 set up a workflow yourself。

在其中填入：

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - master  # 或者你使用的其他分支

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        id: deployment
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./  # 使用根目录，或替换为你的 HTML 文件所在目录

其中，根据 peaceiris/actions-gh-pages@v3 官方使用指南：
secrets.GITHUB_TOKEN 不需要手动生成，runner 会自动生成。

最后，点击右上角 Commit Changes，提交至仓库。仓库根目录下会生成一个 .github/workflows 文件夹。