没人比我更懂方便 —— 透过 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

src\links.yml

"Kitcham 的归墟":
  url: https://uiharu.top/
  img: https://cdn.uiharu.top/blog/home/img/avatar-link.png
  text: "生命洋溢亦无凭无记"

转换后的 JSON 如下：

• links\links.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，可跳过本步骤。

1. 鼠标置於右上角头像处，进入个人设置 Settings

2. 於 Settings 页面进入 Developer settings –> Personal access tokens，並新增一个 Token

3. 请将新增的 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 文件为旧版本，即你无法获得最新的友链信息。

结语

该方案只是经我个人思考后，认为普适性较高的方案。如果你有更优雅的方案，欢迎交流~

参考资料

1. 苏卡卡的友链页面
2. GitHub-Action/FTP-Deploy
3. Github Action 官方文档