Hugo blog 主题模板重构

• 本文约 1316 字，阅读大致需要 3 分钟 | Development | #Hugo | #KaTeX | #Web Development | #Theme | #CSS | #Markdown | #Refactoring | #重构 | #Web Design

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

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

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

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

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

義訓

💡 友情提示

适合写作「某甲」读作「某乙」的场合。

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

公式

⚠️ 小心

小学生有时会忘记或混淆在此处应该用直径dd还是半径rr。

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

🚨 警告

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

泊松分布的PMFPMF：P(X=k)=e−λλkk!{\displaystyle P(X=k)={\frac {e^{-\lambda }\lambda ^{k}}{k!}}}

📓 注意

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

方程组

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

系数矩阵

A=[21212131−1],B=[1082] 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)=[212∣10121∣831−1∣2] (A|B)=\left[\begin{array}{ccccc} 2 & 1 & 2 & | & 10 \\ 1 & 2 & 1 & | & 8 \\ 3 & 1 & -1 & | & 2 \end{array}\right] \nonumber

结语

正所谓

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

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