没人比我更懂方便 —— 透过 Github Action 优雅生成友链数据
朋友需要多多的,奆佬更是如此了,所以我希望拥有一个方便的友链页面,並将其数据与博客分离。因此,我透过 Github Action 自动化部署友链数据,前端惟须负责获取渲染,以此优雅地展示友链
为何要分离友链与博客数据
一般而言,Hexo 中的数据基本以静态形式所存在,其随着每次的 Hexo g -d
命令的执行而变化。从这个角度看,分离友链与博客的数据似乎非常没有必要。仅需我们更新博客时顺带添加即可。但我始终有一个问题:这个做法,它完美吗?
那么,下面我将对这个问题拆分讨论,並将我的方案设想付诸实践。你可於 Kitcham的友链页面 预览效果。
数据更新频率的差异
一篇高质量的文章是需要时间的。以我为例,我的博客较为专注於计算音乐理论、计算神经科学、计算机网络及 OS 内核等方面,说不定也会夹杂些许生活记录φ(゜▽゜*)♪。当然啦,如果我哪天特别有灵感,一连发了好几篇的状况就另说了。
回到正题。正如我所说的那样,我所计划的文章虽已定下一个大方向,但具体到如何下笔、达成目的等诸多细节,都需要时间的沉淀。这样大致估算,半个月到一个月发 1-2 篇文章是非常正常的事情。与其说这样更新慢,倒不如说高产了就会不由自主地开始「疲劳水文」了。因此,我们初步将博文更新频率设为1~2 posts / month
。
至於交换友链的频率?恐怕即使你连番质问,我也没有办法给出一个准确的答案。因为这个时间的发生概率是真的无法预估啊!因为你不能保证有哪一天,被某位大佬翻了牌子,交换了友链。这种情况一旦发生,都应该尽快予以响应。这个时候,你就应该老实地在键盘敲下 Hexo g -d
以更新博客。
综上,固定的产出时间与测不准的交换频率之间存在一个矛盾。如果依照传统,於 links.md
中一个个添加友链,再进行生成及部署,还是有不少麻烦的(部署了 CI 的朋友另说)。
可移植性
早在 Hexo 发布当初,其就以 fast, simple & powerful
作为 Slogan,並以其出色的高自定义性而得到广泛称赞。一言蔽之,如果魔改的 feature 无足够的可移植性,不能方便地进行迁移的话,这个功能应该可以说是失败的。
实际上,各主题的友链页面实现亦有不同,最常见的有以下几类:
- 使用
YML
存储友链信息,並於Hexo g
生成页面时解析,其独立於普通页面的渲染(如 Material 主题) - 给出
HTML
模板,要求博主自行按照该模板添加信息,与普通页面一同渲染(常见於无友链功能的主题) - 以一个
widget
的形式存在,並於主题的_config.yml
中指定生成(ICARUS 主题即采用此种方式)
但无一例外,其均需要在本地完成更新生成,与前文提到的「更新频率差异」存在矛盾。
因此,我得到 苏卡卡的友链页面 的启发,决定采用 JSON
作为数据集。这样一来,生成的 HTML
惟须负责解析 JSON
即可,最大程度上保障了该功能的可移植性。
那么,就用 Github Action 来生成 JSON 吧
什么是 Github Action
虽然不想过多展开,但这里我还是简要介绍一下 Github Action 吧。
From idea to production…
从 Github Action 宣传页面 的这段介绍就可以看出,其本质上就是一个 CI。得益於其与 Github 的深度集成,与竞品相比较,Github Action 的启动条件可谓丰富多样。它允许以 Github 仓库的状态、分支、动作等作为变量条件,以下举些栗子。
on 条件 | Activity types |
---|---|
push | N/A |
pull_request | assigned, unassigned, labeled, opened, edited等 |
page_build | N/A |
更多的启动方法请参阅 Github Action 官方文档。同时,Github 还建立了一个 Github Action 市场 供大家自由选择及分享 Action。
更多的就不在此处展开了,以下将介绍如何透过 Github Action 生成友链数据
我的方案设想
受 苏卡卡的友链页面 的启发,我同样采用了 YML
作为记录友链信息的载体,並通过 Python
的 PYYAML
包进行 YML to JSON
的转换。
我已将该项目上传到 Kitcham/hexo-links-json-generation 这个 Github 仓库中,食用方法请参照下文。
使用者惟须依照以下格式进行填写,Github Action 即可完成转换。
src\links.yml
1 | "Kitcham 的归墟": |
转换后的 JSON 如下:
links\links.json
1 | {"Kitcham 的归墟": {"url": "https://blog.uiharu.top/", "img": "https://cdn.uiharu.top/blog/home/img/avatar-link.png", "text": "生命洋溢亦无凭无记"}} |
如何食用
申请 Token
若果你是第一次使用 Github Action,你需要参照本步骤先行申请 Token
,用於启动 Action 及 Commit Log。若果你已拥有 Token
,可跳过本步骤。
- 鼠标置於右上角头像处,进入个人设置
Settings
- 於
Settings
页面进入Developer settings
–>Personal access tokens
,並新增一个Token
- 请将新增的
Token
命名为GITHUB_TOKEN
,同时勾选repo
,admin:repo_hook
,workflow
等选项
请务必确保新增的 Token
命名为 GITHUB_TOKEN
。
Secrets 配置及运行
考虑到各人的 Hexo 並非均部署在具有 FTP 服务的 VPS 中,下列步骤将区分有无 FTP 两种情况,以供参考。
有 FTP 服务
请先 Fork 项目仓库 Kitcham/hexo-links-json-generation 到自己的 Github Repo 中。然后於 Repo 的 Settings
–> Secrets
中配置好以下 Secrets
,请务必注意名称的一致。
Secrets 名称 | 变量值描述 |
---|---|
USER_EMAIL | 你的 Email 地址(用於 Commit 信息的提交) |
USER_NAME | 你的 Github 用户名(用於 Commit 信息的提交) |
FTP_ACCOUNT | 你的服务器 FTP 用户名 |
FTP_ADDRESS | 你的服务器 FTP 地址(不指定端口时,默认为 21 端口) |
FTP_PASSWORD | 你的服务器 FTP 密码 |
请务必确保设置的 Secrets
名称与上表一致。
你可以参考下图对你的 Secrets
配置进行确认,确认完成后,你可以 Star
一下自己的 Repo 以测试 Workflow 是否正常工作。
具体的 Workflow 情况请转到 Repo 的 Action
界面瞭解,你亦可於此处查看 Workflow 的工作情况。待 Workflow 成功运行后,你可於 Repo 的 /links/links.json
中查看生成结果。此时,你即可以於你的 VPS 中发现 links.json
文件,此即友链 YML
信息文件的转换结果。
注意:该情况下具有两个 Workflow 的 YML
配置文件。其将先执行 build.yml
,待其完成后,ftp.yml
随之执行。
本项目的 FTP 服务采用 GitHub-Action/FTP-Deploy,更多高级配置可参照其项目文档。
无 FTP 服务
请先 Fork 项目仓库 Kitcham/hexo-links-json-generation 到自己的 Github Repo 中。然后於 Repo 的 Settings
–> Secrets
中配置好以下 Secrets
,请务必注意名称的一致。
Secrets 名称 | 变量值描述 |
---|---|
USER_EMAIL | 你的 Email 地址(用於 Commit 信息的提交) |
USER_NAME | 你的 Github 用户名(用於 Commit 信息的提交) |
请务必确保设置的 Secrets
名称与上表一致。
你可以参考下图对你的 Secrets
配置进行确认,确认完成后,你可以 Star
一下自己的 Repo 以测试 Workflow 是否正常工作。
具体的 Workflow 情况请转到 Repo 的 Action
界面瞭解,你亦可於此处查看 Workflow 的工作情况。待 Workflow 成功运行后,你可於 Repo 的 /links/links.json
中查看生成结果。此时,你即可以於你的 VPS 中发现 links.json
文件,此即友链 YML
信息文件的转换结果。
注意:该情况下仅有一个 Workflow 的 YML
配置文件,build.yml
将会执行。
如你需要在本情况下访问生成的 links.json
,你可能需要(三者其一):
- 在 Repo 中进入
/links/links.json
,点击文件预览界面的RAW
选项,获取其於 Github 上的 URL 以便引用访问(不推荐) - 在 Repo 的
Settings
中开启Github Pages
服务,然后即可透过http(s)://YOUR_PAGE_DOMAIN/links/links.json
访问生成的links.json
(推荐) - 你会的其他黑科技 / 黑魔法
友链信息的更新
你惟须依照以下格式进行填写相关信息,每当你进行一次 Push
或 Pull requests
操作后,即可触发 Github Action 完成转换。
src\links.yml
src\links.yml 1
2
3
4"站点名称": # 请置於双引号之中
url: https://example.com # 网站的 URL,请注意冒号后的空格
img: https://example.com/example.png # 网站 Logo 的 URL,请注意冒号后的空格
text: "Hello, World" # 网站的 Slogan,请置於双引号之中,请注意冒号后的空格
如生成过程出现问题,请查看 Action 日志瞭解详情以排查问题。如问题仍未解决,欢迎提交 Issue 交流。
前端怎么用好它呢
本项目仅用於 YML
到 JSON
的转换工作,並非前端友链页面的直接实现。相关的前端实现请参照我另一篇文章 为 ICARUS 而生的友情链接页面。
若果希望查看效果,可到本站的友链页面 Kitcham的友链页面 预览效果。
踩过的坑
请务必,务必,务必不要试图将两个 Workflow 的 YML
配置文件合并。因为以 Github Action 的工作机制,其是以所有 jobs 运行完毕后再行 Commit 与 PR。如此一来,将两个 Workflow 的 YML
配置文件合并后,可能会使得 FTP 上传的 JSON
文件为旧版本,即你无法获得最新的友链信息。
结语
该方案只是经我个人思考后,认为普适性较高的方案。如果你有更优雅的方案,欢迎交流~
参考资料
没人比我更懂方便 —— 透过 Github Action 优雅生成友链数据
https://blog.uiharu.top/archives/generate-links-json-via-github-action.html