Hugo 升级到 0.157.0 后 gist shortcode 报错？一行代码手动修复

最近把 Hugo 升级到了 v0.157.0+extended+withdeploy，构建时突然冒出熟悉的红色报错：

ERROR The "gist" shortcode was deprecated in v0.143.0 and removed in v0.156.0.

原来从 0.143.0 开始 gist 就被标记为弃用，0.156.0 起彻底移除。这意味着之前所有用 {{< gist user id >}} 嵌入 GitHub Gist 的旧博文都会构建失败。

官方建议很直接：想要继续用，自己写一个同名的 shortcode 补上即可。

我检查了一下当前使用的主题 rusty-typewriter，发现它本身就预留了自定义 shortcode 的位置，于是顺手把补救文件扔了进去。执行完这个“一文件修复”之后，所有页面编译通过，没任何副作用。

1 添加 gist.html 模板

在你的 Hugo 项目里找到 shortcode 存放目录。如果和我一样用 rusty-typewriter 主题，路径就是：

themes/rusty-typewriter/layouts/shortcodes/gist.html

当然更推荐直接放在项目根目录的 layouts/shortcodes/ 下，这样即使将来升级主题也不会被覆盖。文件内容只有一行：

<script src="https://gist.github.com/{{ .Get 0 }}/{{ .Get 1 }}.js"></script>

这个 shortcode 接收两个无名参数：用户名和 Gist ID，完全复刻了原内置指令的用法。保存后，你的 Markdown 里原有的：

{{< gist octocat 7d8c9e6c5b4a3f2e1d0 >}}

就会像什么都没发生过一样，继续渲染出对应的 Gist 嵌入区域。

2 为什么推荐放在项目根目录而非主题目录

我把文件放在主题 rusty-typewriter 里是因为这个主题本身就是我自己维护的一套定制主题，不担心被更新覆盖。但如果你用的是第三方主题，强烈建议把 gist.html 放到项目根路径：

你网站根目录/layouts/shortcodes/gist.html

Hugo 的查找顺序是：项目布局优先于主题布局。这样你的自定义 shortcode 永远处于最高优先级，不会受到主题升级的影响。

3 顺便解决 Raw HTML omitted 警告

如果你在最新的 Hugo 里还看到了类似这样的警告：

WARN  Raw HTML omitted while rendering ... see https://gohugo.io/getting-started/configuration-markup/#rendererunsafe

那是因为新版本默认禁止在 Markdown 中直接写 HTML 标签（出于安全考虑）。我的几篇旧文里用了一些 <div> 包裹语法，也因此触发了警告。

根本解决方法是将那些 HTML 片段也替换成 shortcode（例如 div.html），但如果你和我一样不想动历史文章，简单抑制警告也是可行的。在 hugo.toml（或 config.toml）里加一行：

ignoreLogs = ['warning-goldmark-raw-html']

这样构建日志会清爽很多。当然，如果内容安全可控，也可以直接开启 unsafe 模式让 Goldmark 放行所有 HTML，但不建议在公开站点上这样做。

4 构建成功

修复后重新运行 hugo：

hugo server --disableFastRender

所有页面顺利生成，Gist 嵌入框完美出现，再没有之前的 ERROR。整个过程花的时间比写这篇记录还短，Hugo 的 shortcode 机制在这种向后兼容的修修补补上确实很方便。

如果你也遇到了这个问题，快去创建一个 gist.html，经典 Gist 嵌入立刻复活。