Hugo blog 主题模板重构

2025-10-08 20:14 • 本文约 1305 字，阅读大致需要 3 分钟 | Development | #Hugo | #KaTeX

借着 Vibe Coding 的东风，我为 blog 重新设计了一套模板，希望解决一些此前用的基于 ink 模板中存在的一些问题，并彻底清理掉一些历史包袱。

这件事还要从 Search Console 的 Core Web Vitals 报告说起。报告显示，旧主题使用的 Noto Serif SC 网页字体加载缓慢，并在渲染过程中导致了显著的累积布局偏移（CLS）问题。

在调整网站 CSS 的过程中，我逐渐意识到原有主题模板存在不少结构性问题；与其零碎修补，倒不如直接推倒重来。我的想法是，首先用 Hugo 新建一个最新版的最小模板，然后逐渐在上面添加我需要的功能，于是我列了一个需求 wishlist 清单：

采用无衬线字体：这比较符合当前最新的审美习惯。我个人其实还是比较倾向于使用有衬线的字体，但在 2025 年的大环境下，还是顺应无衬线的主流审美更为合适。
改善无障碍设计：使用较少的颜色，为交互元素增加除颜色以外的辅助视觉提示，从而为视觉残障人士的阅读提供便利。
改进数学公式的性能：之前我使用的是 MathJax 在客户端渲染，经过对性能的评估，改为由 Hugo 事先将公式渲染成 HTML 代码，再配合 KaTeX CSS 完成显示，以减少客户端 JavaScript 的开销。
增加对于 Hugo Alert 的支持：这个事情多少有些我自己的恶趣味，因为最近在写技术文档时，我很喜欢用其他 Markdown 实现中的类似功能来做一些注解，虽然最终语法略有不同，但由于和 GitHub、Obsidian 等主流实现语法一致，我觉得可以接受。
改进图片处理：我之前使用的图片尺寸在窗口最大时会出现图片溢出等问题，新的实现需要避免这些问题，同时不放大原本分辨率较低的图片。
减少外部依赖：（例如 webfont）。这其实是有些无奈的做法，在找到更优方案之前，暂时以此作为折中。
支持「義訓」：（用来表达写作「某甲」读作「某乙」的注音方式）。

以下展示了一部分新增或改进的 Markdown 特性，这些内容很大程度上是为了展示而写的 Lorem Ipsum。

義訓

💡 友情提示
适合写作「某甲」读作「某乙」的场合。

您可真是个绅biàn士tài啊。

公式

⚠️ 小心
小学生有时会忘记或混淆在此处应该用直径 $d$ 还是半径 $r$ 。

圆面积公式： $A = \pi r^2$

🚨 警告
想不起来的时候就回去再学一遍。

泊松分布的 $PMF$ ： $P(X=k)={\frac {e^{-\lambda }\lambda ^{k}}{k!}}$

📓 注意
高斯-若当消元法在 RAID 重建时相当常用。

方程组

$\begin{aligned} 2 x+y+2 z &=10 \\ x+2 y+z &=8 \\ 3 x+y-z &=2 \end{aligned}$

系数矩阵

$A=\left[\begin{array}{ccccc} 2 & 1 & 2 \\ 1 & 2 & 1 \\ 3 & 1 & -1 \end{array}\right], \quad B=\left[\begin{array}{c} 10 \\ 8 \\ 2 \end{array}\right]$

对应的增广矩阵

$(A|B)=\left[\begin{array}{ccccc} 2 & 1 & 2 & | & 10 \\ 1 & 2 & 1 & | & 8 \\ 3 & 1 & -1 & | & 2 \end{array}\right] \nonumber$

结语

正所谓

「学而时习之，不亦乐乎？」

主题模板的设计也是不断实践、不断改进的过程。前端的许多最新进展，我之前只是听说过，但有了 AI 工具的辅助之后，探索和实践的效率提高了很多。接下来，我还会继续为这个主题增加更多细节功能，比如更完善的 i18n 支持等，敬请期待。