Hugo

共8篇文章。

给代码块加上可填写的示例参数:Chaos主题的code_vars和其他一些近期更新

• Development

我平时会写不少技术文档。其中的示范代码,特别是涉及命令行操作的部分,往往包含一些需要临时填写并在后文重复使用的参数,读者不能直接照搬例子去运行,而是需要先做一些修改才能使用。

前几天在写生成SSHFP和TLSA记录这篇作弊条的时候,我顺手给本站使用的Chaos主题加上了一个可交互的示例参数功能,并把之前合并BIND 9子域等几篇旧文也一并改了过来。

从减少重复手工操作、避免忙中出错的角度来说,许多时候(尤其是对于「作弊条」这类题材的内容),比较理想的文档形式应该是一个可以填写、填完就能直接复制的模板。这是因为在这些操作里,变量(或者说需要读者填写的内容)通常是主机名、IP地址,或是本地某条命令的输出结果(例如公钥的hash值),而其余参数则应与原文保持严格一致,且同一组参数往往会贯穿全文。

例如在TLSA和SSHFP那篇里,域名example.net、邮件服务器mx1、SSH主机beastie,以及前一步刚用OpenSSL算出来的公钥SHA-256和SHA-512散列值,会在后面的命令行和BIND区域文件模板里反复出现。假如完全靠手工在各个代码块之间来回查找替换,不仅繁琐,而且漏改或是贴错一段,还很容易导致一些其他问题。

在一些文档系统的DSL中,有一种用 <var> 标签标记的可编辑占位符:在渲染出来的页面上填入新值之后,整篇文档里的示例命令就会跟着一起变,点复制按钮拿到的也是替换好的命令。我认为这种交互非常适合类似作弊条这样的内容,于是用Antigravity给Chaos主题也做了一套类似的实现。这里记录一下它在实际文章中的写法,以及在迭代过程中考虑的一些细节。

阅读全文…(本文约6625字,阅读大致需要14分钟)

给博客做个站内全文搜索:纯前端离线倒排索引的设计与取舍

• Development

最近给本站正在使用的Chaos主题增加并逐步完善了一套在客户端进行的全文检索功能。

早年本站使用的是Google站内搜索,不过换成Hugo以后模板中的这个搜索框也就去掉了,毕竟现在也没什么人看blog了,写下去除了给自己留点记录之外,或多或少其实是一种行为艺术,而本站的读者基本上也都知道如何使用搜索引擎。

不过,有时我自己也会希望在blog里找一些以前的文章,虽然本站在Google搜索中的覆盖率还相当高,但有些时候新的文章会搜索不到,或是其实内容已经过时但仍然被索引。虽然在大语言模型的帮助下我整体重建了分类和标签的标注,但这些对于定位有时还是不太方便。

Hugo作为一个静态站点生成器,其实已经有了不少成熟的本地搜索方案。不过,今年都已经2026年了,vibe一个本地搜索并不困难。这里记录一下这个本地搜索的演化过程,以及在这个过程中的一些工程取舍。

阅读全文…(本文约4456字,阅读大致需要9分钟)

作弊条:在Nginx中正确配置自定义404页面

• Cheatsheets

最近给blog增加了一个自定义的404错误页面。像Hugo这样的静态网站生成器在构建时,默认会把渲染好的404页面直接输出在网站根目录下,即 /404.html。

针对这类页面,我们通常希望:

  1. 当访客访问不存在的网址时,服务器呈现该页面的内容,并且HTTP状态码必须是404。
  2. 当有人(或爬虫)直接在浏览器中访问 /404.html时,同样呈现其内容,但返回的HTTP状态码依然必须是404,而不是200 OK。
阅读全文…(本文约1490字,阅读大致需要3分钟)

写给未来的blog:关于引用、结构、导航与AI

• Blogging

早年,车东提出过一个愿景:「让互联网:良好引用,良好结构,良好导航」,这句话一直让我印象深刻。一直以来,对互联网内容的彼此可以有效引用、结构清晰、可以被(人类和机器)理解和持续访问而不是被时间与系统更新湮灭,是我和许多blog作者的理想。在我自己的blog中,我也一直在尝试实现这三个目标。

阅读全文…(本文约1522字,阅读大致需要4分钟)

Hugo blog主题模板重构

• Development

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

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

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

阅读全文…(本文约1477字,阅读大致需要3分钟)

采用了基于 isso 的评论系统

• Cheatsheets

📜 历史文件已不具备现实意义

2022年12月更新:本文内容已过时,本站目前已经不再使用isso,换成了Remark42。

上回书说到从Movable Type搬到Hugo上之后,就彻底失去了评论和pingback的功能。因为现时正经写blog的人已经越来越少,因此pingback似乎意义不太大了,但是能够收集评论反馈还是有一些意义的。

早前,Movable Type实现的评论系统与其自身的账户系统有集成,并且还支持包括Facebook、Google在内的一系列其他OpenID的系统。这个功能的一个好处是对于经常访问的人来说比较友好,例如站主可以将某个ID设置为受信任的ID,从而避免先审后发。

阅读全文…(本文约1289字,阅读大致需要3分钟)

把blog从Movable Type迁移到了Hugo

• Blogging

花了些时间把blog从Movable Type迁移到了Hugo。

说起来Movable Type已经用了有十七年之久了,不过Movable Type商业化以后便基本没有更新了,由于它是Perl写的,因此我也没什么动力去持续维护。

阅读全文…(本文约1321字,阅读大致需要3分钟)