现在换到了 HUGO


现在换到了 HUGO

距离上次更新博客也有个一阵子了,这次更新博客的契机是把静态博客方案从 Jekyll 换到了 HUGO。这正好也是 2025 年的第一篇博客,就借此机会漫无目的的瞎扯一篇吧。

换到 HUGO

首先是为什么要换。原因其实很简单,我有一些打算把这个博客站点做一些改造,让它能更方便的罗列一些我在做的事情或者说按新的方式展示一些我想展示的东西,而事实上我已经不能在本地正常的重新跑起来我的原有的 Jekyll 静态生成环境了。导致这个的原因可能是我不熟悉 Ruby 的生态,折腾起来会麻烦很多,而即便折腾后,做出后续调整可能需要花费更多的精力。另一方面原因是,原站点站在我目前的视角而言,实在是太粗糙了,并且涉及到的一些懒人方案,例如 iconfont 对应的平台甚至把我长久没登录过的账号消掉了,导致重新调整相关内容也会变得非常费劲…

于是接下来要决定的就是换到什么方案了,那自然需要知道我在意的点有哪些:

  1. 能方便的把环境跑起来,哪怕是放上几年后不去动它
  2. 整体迁移的方便程度,不希望浪费太长时间,所以越省事越好
  3. 有相对多一些的资料可参照,减少踩坑概率,复用现有生态

HUGO 是第一个想到的方案,也是最终选择的方案。由于它提供的是单一可执行,所以条件①可以很方便的满足,只需要知道对应版本即可。条件②最初考虑是之前用过所以相对熟悉一些,可能省点事。至于③则是因为看 KDE 社区目前的方案如此,也确实资料相对多一些。当然,②实际要做的事情具体有多少也是后来才知道的。如此迁移的话,大概有这些目标:

  1. 保留旧静态博客的数据
  2. 文章现有写法(不常见的 Markdown 语法或者额外的标记语法)的兼容性,迁移不兼容的部分
  3. 对原有 URL 的兼容(有几个文章页面应该是被搜索引擎索引到了,希望能至少重定向到新的页面)
  4. 现有主题的迁移
  5. 迁移 Action,自动部署页面

查阅资料发现 HUGO 甚至提供了 hugo import jekyll 这种命令,以为能直接搞定前三点,不过实际执行才发现这个命令事实上只拷贝了文章本身以及静态资源目录,并未做额外的处理,于是事实上和自己手动复制没太大差异。于是后续的几点还是得自己上。开始第二点之前需要做的事情则是先至少跑起来一个架子站点,而由于 HUGO 自身并未提供一个最小可用的架子站点,则最终选了 GitHub: Vimux/blank 作为起点,于是终于可以真正的开始迁移本身了。

尽管把“现有主题的迁移”列在了最后,而它实际是把空白主题放上去后先做的事情。迁移现有主题并不是因为旧主题哪里好(相反,现在觉得其实很差),而是因为原本主题事实上也没太多东西,迁移后也方便查看文章的排版情况,也方便检查标记语法的兼容情况。好在主题的迁移相对确实也比较轻松,于是主题大致迁移完成后,就是检查文章和 URL 的兼容了。

文章的标记语法兼容性这点,最初是查看了 HUGO 对 GFM 的支持情况。我在乎的大体上是这些:

  1. 脚注[^1]支持
  2. 站内文章链接支持
  3. 额外的,> [!NOTE] 支持?

脚注是我大部分文章都会用的特性,第二点虽说实际不太算是 GFM 的一部分,但也可以说是来自 Wikilink。前两者在试水 HUGO 之前就查对应资料确认支持了,最后一点也意外的发现确实支持,而最终则遇到问题的反而是我完全没觉得会是问题的地方——在 Markdown 内编写基本的 HTML 标注。

HUGO 默认不允许在 Markdown 中混写任何 HTML 标签,并认为这是 unsafe 的。于是一些原本便于使用的特性反而成了问题,包括…

  1. <kbd>快捷键</kbd>
  2. <mark>高亮文本</mark>
  3. <details><summary>概要</summary>详情</details>

之类。导致我实际遇到问题的是“概要详情”,而快捷键和高亮文本则是非常可预见的用法了。至于“概要详情”。HUGO 实际提供了 details shortcode,但我觉得 HUGO 的 shortcode 在便于编写与便于阅读这两点上都没有占到任何优势…当然,unsafe 是可以打开的,尽管我目前选择了暂时保持 unsafe 关闭的凑合方案,我感觉说不定后续我会把它打开1,至少说实话我是不知道这个 unsafe 渲染保护到底是能保护得了什么…

然后则是站内文章链接。我原以为会是类似 Wikilink 的语法,而最终则发现则是 {{< ref "page-link" >}}2,又是这种非常蛋疼的标记。查询一番后发现 HUGO 拒绝了对 Wikilink 的支持,于是只能摊手作罢。不过好在,至此,对文章内的标记支持就差不多都确认完毕了。

于是剩下的最后一点则是对原有 URL 的兼容,这点原本我并没有太高的预期,但事实上这点支持起来意外的简单。frontmatter 中只需要提供一个 aliases 字段即可,并且可以提供一个列表表示页面的多个 alias,对应的别名页面的实际行为即为跳转到实际位置,于是只需要手动把 aliases 字段加上就可以了——当然,自动加上也行,只是批量加的脚本写完估计我也手动加完了,没这个必要…

完毕后,最后一步则是把现有的 GitHub 提供的 Jekyll 自动部署改成走 GitHub Action 部署页面了。本篇写到这里这也是唯一我还没做的事情,当然,当你看到这篇文章的时候,我就已经做完这最后的步骤了 ;)

最后剩下的则是大战 CI 了!尽管最烦和 CI 打乒乓,但好在部署 HUGO 站点这点上是有经验可复用的,所以估计会很顺利。无论如何,希望一切顺利 :)

2025年2月22日20点03分


  1. 根据一个投票人数不算特别多的投票,还是有相当多的人选择了打开 unsafe 的… ↩︎

  2. 额…我没想到让文章把 shortcode as-is 的显示出来需要特别的 escaping 方式,写完这段才发现的,然后反过来修改了这里。具体的 escaping 方式可见这里。简而言之需要这样写: {{</* myshortcode */>}}。 ↩︎