没人比我更懂方便 —— 透过 Github Action 优雅生成友链数据
source link: https://blog.uiharu.top/archives/generate-links-json-via-github-action.html
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
没人比我更懂方便 —— 透过 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 typespush
N/Apull_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
"Kitcham 的归墟":
url: https://uiharu.top/
img: https://cdn.uiharu.top/blog/home/img/avatar-link.png
text: "生命洋溢亦无凭无记"
转换后的 JSON 如下:
links\links.json
{"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"站点名称": # 请置於双引号之中
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
文件为旧版本,即你无法获得最新的友链信息。
该方案只是经我个人思考后,认为普适性较高的方案。如果你有更优雅的方案,欢迎交流~
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK