一天时间,搭了个专属知识库,部署上线了,手把手教,不信你学不会(下)
话接上篇:搜索标题一天时间,搭了个专属知识库,部署上线了,手把手教,不信你学不会(上) 本篇将介绍将知识库部署上线的部分,希望给有类似需求的小伙伴一点帮助。 如果你的本地知识库,已经搭建完成。我们一起把它部署上线吧~ 如何把本地的知识库部署上线,和你的小伙伴分享? 前几天,我们一起盘点了:小白搭建静态网站,都有哪些建站工具? 今天这个需求不就用上了。 那么多建站工具,我该选哪个呢? 对于知识库这样一个简单需求,当然首选 docsify。为啥? 和 GitBook 以及 Hexo 等建站工具不同的是,它会智能地加载和解析 Markdown 文件,而无需生成 html 文件,所有转换工作都在运行时。此外,我认为 Docsify 最大的优点有以下几个方面: ❝ 官方文档:https://docsify.js.org/#/zh-cn/ docsify 安装需要依赖 node.js,相信你在上一步按照 PicGo 插件时已经装好了 node.js。 准备好 node.js 环境后,在终端中采用 npm 一键安装: 上述指令中, 怎么知道这个全局安装的包放在哪了? 这会返回全局安装目录的路径。默认情况下会放在你的 C 盘: 如果不想你的 C 盘很快爆满的话,最好给它挪个位置~ 这时,你可以修改 npm 的全局安装位置。首先新建一个目录,然后在终端中配置 npm 使用新的目录: 可以看到文件夹下多了一个 为了系统自动识别到 对于新手小白来说,还会遇到一个问题:npm 下载太慢啦~ 这是因为 npm 默认从国外的 https:/registry.npmjs.org/ 服务器进行下载,不信你试试看下面这个指令: 所以你需要给它换个国内的镜像。 再次安装 docsify,有没有快到飞起? docsify 安装好之后,启动知识库只需要一个命令(在你的当前知识库文件夹下执行): 如果文件夹下已经有文件,也没关系,选择 yes,会初始化3个文件,其中 接下来,还是一键命令完成部署: 打开上述链接,你会看下如下页面: 这些文字内容是哪来的呢? 还记得刚才生成的三个文件中的 README.md,打开看看吧。 所以,你只需要编辑这个 README.md,就可以实现你的内容展示了。 你不需要杀掉 serve 指令,docisfy 支持修改 README.md 时,网页端实时更新。 接下来我们来说说这个 网站主题修改: 在 index.html 中: 官网支持的主题在:https://cdn.jsdelivr.net/npm/docsify@4/lib/themes/,都去试试吧,看看自己更喜欢哪个~ 封面设置: 只需在 然后,创建一个 顶部导航栏设置: 只需在 docsify 会默认加载 这样你在网站上就会看到: 侧边栏设置: 只需在 然后,创建一个 docsify 的生态非常丰富,开发者搞了很多插件,为你的知识库插上三头六臂,变得更为智能,而这些插件就是一个个 javascript 脚本,你只需要在 index.html 中插入即可。 这里给大家推荐几个最常用到的。 1. 搜索插件 随着文章的增多,搜索功能就显得尤其必要,你只需要在 index.html 的如下位置填入: 然后在最下方引入插件脚本: 此时,在你的网站左上角就可以看到搜索栏: 2. 右侧目录插件 我的文章很多偏实操,所以内容比较长,如果能够在右侧显示文章目录,支持滚动高亮,点击跳转等,显然更符合当下流行的文档网站布局,类似下面这样。 这时你只需要一个插件,叫 toc (Table of Content)。不过社区中有两种实现: 一开始我是采用的第二行的插件,后来发现它和 sidebar(也就是左侧目录) 会出现冲突,看了下报错应该是插件内部的 bug。所以又找到了第一行的插件,再配置下 3. 代码复制和高亮插件 技术文章很多都有代码,为了实现代码一键复制和高亮,类似如下效果: 你只需要插入如下插件: 本地测试没什么问题后,接下来我们就需要把它托送到云端了。 因为知识库一定是会不断更新的,所以最好用 git 来维护一个远程仓库。 这里值得注意的是,如果你在本地存了很多图片,最好不要把他们推送上去。 拿我的来举例:项目中每个子文件夹都有存放图片的 assets 文件夹,现在需要 要在 这样,所有子文件夹中的 assets 文件夹都会被 Git 忽略。 然后一键三连,完成项目初始化: 这样本地仓库就建好了,接下来你需要的是一个远程仓库。 这里我们选择在 GitHub 上新建远程仓库,因为各大网页部署平台对 GitHub 的支持最为友好。 注意:上面的 Private 要改为 Public,需要是公开仓库才可以部署到 GitHub Pages。 接下来,在本地终端中进行账户设置,填入你的 GitHub 的注册名称和邮箱: 将本地仓库推送到远程仓库: 上面的 GitHub 远程仓库有了之后,我们就要选择一个工具将网站部署上线。都有哪些选择呢? 综合来看,对于简单的知识库网站而言,后面两种方案完全可以满足需求。 下面我们就一起实操下,分别将网站部署到: 如果你需要部署在 Gitee Pages 上,首先需要在 Gitee 新建一个远程仓库并和本地仓库进行关联,当然如果已经有了 GitHub 远程仓库,也可以选择 fork 过来。然后在项目首页如下位置找到 Gitee Pages : 遗憾的是: 看来国内审核压力也给到 Gitee 了~ 进入你的远程仓库首页,在 Settings -> Pages 中,选择你的分支 master,选择在根目录部署,这个主要根据你的 index.html 所在的位置进行选择。 到这里,一个拥有 github.io 二级域名的 page 就已经建好了: 访问地址:https://hougeai.github.io/knowledgebase 是不是很简单? 如果您想拥有一个个性化的域名怎么办? 你得掏腰包去域名服务商买一个心仪的域名。如果你只是想拿来玩玩,当然也有免费域名可以注册,可以参考这篇:【保姆级教程】免费域名注册 & Cloudflare 域名解析。 拿到域名之后,还需要进行域名解析。 具体而言,在域名解析服务器中添加一条 DNS 记录,参考官方文档,github 可以用的 IP 地址如下: 以我的举例:参考上篇教程进行域名解析,前往 cloudfare 官网,添加一条 DNS 记录: 再前往 github pages 配置页,填入你的域名,等待 DNS 解析成功。 最后,回到 github pages 配置页上方,打开你的专属链接看看吧~ 访问地址:https://kb.houge.us.kg/#/: 如果您希望 GitHub Pages 在仓库代码更新后能够自动更新? GitHub Actions 来了解下:通过设置自动化流程,在依赖仓库代码更新后自动触发 GitHub Pages 的更新。GitHub Actions 就是 GitHub 推出的持续集成服务。 首先,需要配置下项目的 Actions: 然后,开始配置 Actions 工作流。 官方的 actions 都放在 https://github.com/actions 里面。 我们这个项目只需要简单的自动更新页面,点击 在其中填入: 其中,根据 最后,点击右上角 Commit Changes,提交至仓库。仓库根目录下会生成一个 .github/workflows 文件夹。 但是,这个 workflow 却失败了,是第二个 job 执行出了问题。 无奈之下,只能把这个 workflow 关掉了。 后来发现,pages 默认就有一个 workflow,叫 ❝ 传送门:https://vercel.com/ 当前免费额度:300 分钟每月的计算时长和 100 GB 每月的流量。因为我们这个项目只是一个静态网页,无需计算,所以应该只要不超过 100 GB 的访问流量就是 OK 的。 注册账号后,新建一个项目,选择从 GitHub 引入: 然后,输入一个你想要的域名,检查下是否可用: 点击最下方的部署,稍等片刻,出现下面界面,说明已经部署成功: 访问地址(国内 IP 可访问):https://hougeai.netlify.app/ 搞定! ❝ 传送门:https://zeabur.com/ Zeabur 目前的限制是: zeabur 只能基于 Github 进行部署。注意如果你不想升级为付费用户的话,只能选择 Developer Plan 和 Team Plan 以外的地区的机器进行部署,如果长时间无法构建成功,可以换一个地区试试。 构建成功后,在下面的网络中点击生成一个域名。 回到上方,查看部署状态: 访问地址(国内 IP 可访问):https://hougeai.zeabur.app/ 注意:Zeabur 会根据你的代码结构自动检测代码用的框架,所以如果只是一个静态网站的话,不要在根目录下放 xx.py 文件,否则它会识别为一个 python 项目,导致你的 index.html 部署失败。 至此,这篇长文终于写完了。相信看到这里的你,一定也遇到过下面这些问题: 从本地知识库到在线部署,从 Typora 到 Docsify,从 GitHub Pages 到 Netlify,终于把知识库搞上线了。2. 在线知识库部署
2.1 docsify 安装和使用
2.1.1 docsify 安装
npm install -g docsify-cli
-g
代表全局安装,因为我们需要用到 docsify 的场景还挺多,所以就选择全局安装了。npm root -g
C:Users<YourUsername>AppDataRoamingnpm
。npm config set prefix D:npm-global
node_moudules
,可执行文件也在当前目录下:docsify
命令,你还需要添加新的路径到系统环境变量中。具体步骤如下:
// 查看当前下载地址
npm config get registry
// 设置淘宝镜像的地址
npm config set registry https://registry.npmmirror.com/
2.1.2 docsify 启动
docify init
index.html
就是最终渲染的初始网页:docsify serve
# 输出如下
Serving D:dataprojectsknowledgebase now.
Listening at http://localhost:3000
index.html
中的一些具体设置,将你的网页打造的更加酷炫、高级一些。2.1.3 docsify 基础操作
<!--这个链接就是主题的选择-->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
window.$docsify
中加入一行:window.$docsify = {
coverpage: true,
}
_coverpage.md
文件,编写 markdown 内容并保存:
# 猴哥的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,
}
_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 插件配置
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>
<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> -->
window.$docsify
,完美实现上图中的效果!window.$docsify = {
toc: {
tocMaxLevel: 5,
target: 'h1, h2, h3, h4, h5, h6',
ignoreHeaders: ['<!-- {docsify-ignore} -->', '<!-- {docsify-ignore-all} -->']
},
}
<!-- 代码复制 -->
<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 远程仓库建立
2.2.1 本地 git 初始化
.gitignore
中忽略所有子文件夹中的 assets 文件夹,可以项目根目录下创建 .gitignore
,然后填入以下规则:**/assets/
git init
git add .
git commit -m 'first commit'
2.2.2 关联远程仓库
# 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 部署工具选择
2.4 网站部署
2.4.1 Gitee Pages
因服务维护调整,Gitee Pages 暂停提供服务,给您带来不便深感抱歉,感谢对 Gitee Pages 服务的支持。
2.4.2 GitHub Pages
185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153
其中
Allow all actions and reusable workflows
, 否则你将无法使用别人的 Action。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 会自动生成。pages-build-deployment
,会根据你的 push 进行重新部署,无需新建 workflow。不得不说,GitHub 真的很良心,你想到的它都已经给做到了。2.4.3 Netlify
2.4.4 Zeabur
写在最后