文档章节
渲染钩子
用模板覆盖 Markdown 元素到 HTML 的转换:模板放在哪里、怎么命名、能输出什么,以及配错时该怎么查。
开始之前,你需要
- 站点里已经在用 Markdown 内容,并且你会看
public/里生成的 HTML——本章的验证全靠对产物。 - 知道模板放在
layouts/下、函数与上下文是什么;不确定先读模板简介。
读完之后你能
- 说清渲染钩子与短代码的分工,知道该用哪一个;
- 在项目里正确创建
layouts/_markup/,并按命名规则判断自己写的钩子为什么没生效; - 从每页的「上下文」小节查出可用字段,并分清
string、template.HTML、template.HTMLAttr三种类型的输出方式; - 用「加唯一记号 + 搜索产出 HTML」证明钩子真的生效,而不是靠肉眼判断。
这一章讲的是 Hugo 里一处不太按常理出牌的功能。多数功能配错了会立刻报错,渲染钩子(render hook)配错了往往什么都不说:构建成功、页面照常渲染,只是效果没出现。所以本章的重点不是「有哪些钩子」,而是「它在哪里生效、名字怎么取、结果对不对」。
读完本章你应该能够
- 说清渲染钩子与短代码的分工:短代码在调用点插入一段内容,渲染钩子改变某一类 Markdown 元素的渲染方式;
- 在项目里正确创建
layouts/_markup/,并判断某个元素当前走的是 Hugo 默认渲染、主题提供的钩子,还是自己写的钩子; - 按
render-<元素>[-<限定>][.<输出格式>].<后缀>的规则给钩子模板命名,知道哪种写法会「静默失效」; - 从每个钩子页面的「上下文」小节查出可用字段,并分清哪些是
string(需要safeURL)、哪些是template.HTML(直接输出)、哪些要用safeHTMLAttr; - 用「加唯一记号 + 搜索产出 HTML」的办法证明钩子真的生效,而不是靠肉眼觉得差不多;
- 遇到「没报错但结果不对」时,先怀疑结构与配置,再怀疑模板逻辑。
本章要点速览
配置位置
渲染钩子不是配置项,而是模板文件,只放在 _markup 目录里:
| 位置 | 作用范围 | 优先级 |
|---|---|---|
项目 layouts/_markup/ |
只对自己的站点生效 | 高,覆盖主题同名文件 |
主题 themes/<主题名>/layouts/_markup/ |
由主题提供 | 低 |
改主题钩子的正确做法是在项目里放同名文件覆盖它,而不是直接改 themes/。_markup 目录还可以放在任意以页面路径命名的层级下,匹配得越深越优先。
关键点:项目里没有 _markup/ 不等于站上没有钩子。 实测(Hugo 0.167,本站):本项目 layouts/ 下只有 _default/baseof.html,而站上的链接钩子与引用块钩子全部来自主题 hugo-docs-theme。
模板命名规则
render-<元素>[-<限定>][.<输出格式>].<后缀>
必填 可选 可选| 段 | 例子 |
|---|---|
| 元素类型 | render-link.html、render-image.html、render-table.html |
| 限定(语言/子类型) | render-codeblock-mermaid.html、render-blockquote-alert.html、render-passthrough-inline.html |
| 输出格式 | render-link.rss.xml |
七个元素名固定为 blockquote、codeblock、heading、image、link、passthrough、table;限定名由 Hugo 给定(代码块用语言名,引用块用 alert/regular,透传元素用 block/inline)。限定名拼错不会报错,只会永远不匹配。
钩子输出的三种值类型
| 类型 | 典型来源 | 输出时 |
|---|---|---|
template.HTML(可信 HTML) |
.Text;transform.HighlightCodeBlock 的 .Wrapped/.Inner |
直接 {{ .Text }} |
string(普通字符串) |
.Destination、.Title、.PlainText、.Type、.Anchor |
当正文会自动转义;当 URL 属性要套 safeURL |
template.HTMLAttr(属性片段) |
用 printf "%s=%q" 拼出的属性 |
必须套 safeHTMLAttr,否则引号会变成 " |
「三种类型」是本站为便于排查所做的归纳,依据是各页示例中的 safeURL/safeHTMLAttr 写法与上下文字段表里标注的类型;官方文档没有这一提法。
配错时的典型报错
| 现象 | 原因 |
|---|---|
| 没有任何报错,页面完全没变化 | 文件位置或文件名不对;限定名拼错;站点缺少依赖的配置项(如 wrapStandAloneImageWithinParagraph、Passthrough 扩展) |
| 报错带模板文件名与行号 | 模板里的 {{ if }}/{{ range }}/{{ with }} 没配平 |
can't evaluate field ... |
用了别的钩子才有的字段 |
| 一条自定义消息 | 模板里的 errorf 主动报错(例如公式渲染失败) |
建议的阅读顺序
- 简介 —— 先读这一页。配置位置、命名规则、查找顺序、输出值类型与典型报错都在这里,后面各页不再重复。
- 链接 —— 结构最简单的一个钩子,适合拿来练手;顺带讲清「自定义钩子会顶掉内建钩子」这件事。
- 图片 —— 结构与链接几乎一样,但多一个
IsBlock与一项容易漏配的站点配置。 - 标题 —— 字段最少,风险却最大:漏一个
Anchor,目录与锚点导航整体失效。 - 代码块 —— 内容最多的一页:信息字符串的两类属性、按语言拆模板、Mermaid 与
Store中转。 - 引用块 —— 唯一一个「普通元素 + 警示块」两条分支的钩子,含本站主题的实际实现。
- 表格 —— 双层循环结构,练习「自己接管 HTML 结构就不能漏标签」。
- 原样透传 —— 最特殊的一页:钩子触发的前提是站点先开启了 Goldmark 扩展,示例是在构建时渲染数学公式。
只想解决眼前问题的话,不必按顺序读:从上面挑对应的那一页即可,每页都自带「什么时候用 / 什么时候别用」「验证方法」与「常见坑」。
相关章节
- 短代码 —— 在调用点插入内容,与渲染钩子分工互补;
- 模板 —— 钩子模板也是模板,写法与查找顺序同源;
- Markdown 属性 —— 多个钩子的
Attributes字段都来自这里; - 图表 —— 代码块钩子的典型应用(GoAT 与 Mermaid);
- 数学公式 —— 透传钩子的典型应用(KaTeX)。
本章内容
- 简介 渲染钩子的共同机制:模板放在哪里、怎么命名、Hugo 按什么顺序查找、钩子输出什么,以及配错时的典型报错。 (今天)
- 链接 创建链接渲染钩子,覆盖 Markdown 链接到 HTML 的转换;含上下文变量、内建钩子的取舍,以及验证方法。 (今天)
- 图片 创建图片渲染钩子,覆盖 Markdown 图片到 HTML 的转换;含上下文变量、figure 版式、内建钩子与 IsBlock 的坑。 (今天)
- 标题 创建标题渲染钩子,覆盖 Markdown 标题到 HTML 的转换,并为标题追加锚点链接;含 Anchor 的风险与验证方法。 (今天)
- 代码块 创建代码块渲染钩子,覆盖围栏代码块的默认高亮输出、按语言定制渲染方式,并让信息字符串里的属性可控。 (今天)
- 引用块 创建引用块渲染钩子,覆盖 Markdown 引用块的渲染,并把 NOTE 等警示块变成带样式的提示框。 (今天)
- 表格 创建表格渲染钩子,遍历表头与表体单元格覆盖 Markdown 表格到 HTML 的转换;含对齐取值与结构遗漏的风险。 (今天)
- 原样透传 创建透传渲染钩子,处理 Goldmark 透传扩展捕获的文本片段,并在构建时用 KaTeX 渲染数学公式。 (今天)