代码块
创建代码块渲染钩子,覆盖围栏代码块的默认高亮输出、按语言定制渲染方式,并让信息字符串里的属性可控。
开始之前,你需要
- 读过简介,知道钩子模板要放在
layouts/_markup/、文件名怎么取。 - 能看懂 Go 模板里的
with、merge、管道与变量赋值(:=)。 - 站点里至少有一个围栏代码块,改完能立刻比对输出。
读完之后你能
- 写出一个与 Hugo 默认行为一致的
render-codeblock.html,并知道它和「不写钩子」的差别; - 按语言拆分模板(例如只给
mermaid单独渲染),并说清信息字符串里通用属性与高亮选项的区别; - 把「这段代码来自哪个文件」显示在代码块上方;
- 在构建时渲染 Mermaid 图表,并知道为什么脚本要放在基础模板末尾。
接着读:图表 · 引用块 · HighlightCodeBlock
Markdown 中的代码块
下面这段 Markdown 含有一个围栏代码块:
```sh {class="my-class" id="my-codeblock" lineNos=inline tabWidth=2}
declare a=1
echo "$a"
exit
```一个围栏代码块由以下部分组成:
- 起始代码围栏
- 可选的信息字符串
- 代码样例
- 结束代码围栏
在上面的例子中,信息字符串包含:
- 代码样例的语言(第一个词)
- 可选的属性列表,用空格或逗号分隔,写在花括号内
信息字符串中的属性可以是通用属性,也可以是高亮选项。
上例中的通用属性是 class 与 id。如果代码块渲染钩子没有做特殊处理,Hugo 会把每个通用属性加到包裹代码块输出的 HTML 元素上。按照自身的内容安全模型,Hugo 会移除 onclick、onmouseover 这类 HTML 事件属性。通用属性通常是全局 HTML 属性,也可以包含自定义属性。
上例中的高亮选项是 lineNos 与 tabWidth。Hugo 使用内建语法高亮器渲染代码样例,可以通过指定一个或多个高亮选项来控制渲染结果的外观。
两者的区别值得记牢:通用属性最终会出现在输出 HTML 的外层元素上(由钩子决定加到哪个元素),高亮选项则交给语法高亮器去影响代码本身的渲染。在钩子的上下文里,它们分别对应 Attributes 与 Options 两个映射——这是本页最容易混淆的一对字段。
实测(Hugo 0.167,本站):本站 hugo.toml 设了 [markup.highlight] noClasses = false,因此高亮输出使用 CSS 类名而不是内联样式,配色由主题的 assets/css/syntax.css 提供(由主题的 partials/head.html 引入)。这属于高亮配置,与钩子无关;但如果你看到代码块「没有颜色」,先分清是高亮配置问题(样式表没加载)还是钩子把输出弄丢了。
上下文
代码块渲染钩子模板接收以下上下文:
Attributes- (
map)信息字符串中的通用属性。 Inner- (
string)起始与结束代码围栏之间的内容,不含信息字符串。 Options- (
map)信息字符串中的高亮选项。 Ordinal- (
int)代码块在页面中的序号,从 0 开始。 Page- (
page)当前页面的引用。 PageInner- (
page)通过RenderShortcodes方法嵌套的页面的引用。详见下文 PageInner details。 Position- (
text.Position)代码块在页面内容中的位置。 Type- (
string)信息字符串的第一个词,通常是代码语言。
注意 .Position 的类型是 text.Position,与其他钩子里的 string 不同;直接当字符串输出会得到可读的位置信息,用于错误消息最合适(下面的 Mermaid 与公式示例都这么用)。
.Inner 是未经处理的原始字符串:它不会被自动转义,也不会被自动当成 HTML。要输出到页面时必须自己决定怎么处理——如果内容是纯文本(多数情况),要先 htmlEscape;如果确实是 HTML,才用 safeHTML。
示例
默认情况下,Hugo 使用内建语法高亮器渲染围栏代码块,并包裹渲染结果。要写出行为一致的渲染钩子:
{{ $result := transform.HighlightCodeBlock . }}
{{ $result.Wrapped }}当语言未指定或高亮器不支持该语言时回退为纯文本:
{{- $opts := dict }}
{{- if not (transform.CanHighlight .Type) }}
{{- $opts = dict "type" "text" }}
{{- end }}
{{- $result := transform.HighlightCodeBlock . $opts }}
{{- $result.Wrapped }}transform.HighlightCodeBlock 返回一个结果对象,它有两个方法:.Wrapped 输出带 <div>/<pre>/<code> 包裹的高亮代码,.Inner 输出不带包裹元素的高亮代码(便于你自行包裹)。上面的例子用 .Wrapped,因此与默认输出一致。
想覆盖信息字符串里的某个高亮选项,用 merge 把新的取值并进 .Options 再传进去:
{{ $opts := merge .Options (dict "lineNos" true) }}
{{ $result := transform.HighlightCodeBlock . $opts }}
{{ $result.Wrapped }}尽管可以用一个模板加条件逻辑来按语言区分行为,也可以为不同语言创建单独的模板:
layouts/
└── _markup/
├── render-codeblock-mermaid.html
├── render-codeblock-python.html
└── render-codeblock.html例如,创建一个渲染 Mermaid 图表的代码块渲染钩子:
<pre class="mermaid">
{{ .Inner | htmlEscape | safeHTML }}
</pre>
{{ .Page.Store.Set "hasMermaid" true }}然后在基础模板的末尾、body 结束标签之前加入这段代码:
{{ if .Store.Get "hasMermaid" }}
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>
{{ end }}这段示例里有三处值得停下来想清楚的地方:
- 为什么要
Store中转。 钩子在渲染页面内容的过程中执行,而基础模板运行在更外层,那时还不知道页面里有没有 mermaid 代码块。所以钩子先用.Page.Store.Set记一个标记,基础模板再用.Store.Get读它——这正是「页面的 Store 里为什么缺少某个值」那一节讲的问题。 - 为什么要放在
body结束标签之前。 脚本需要页面里的<pre class="mermaid">已经存在。放在head里虽然也能跑,但依赖模块加载时机,放在末尾更稳。 htmlEscape | safeHTML是成对的。.Inner是原始字符串,先用htmlEscape把尖括号转义掉,再用safeHTML告诉 Hugo「这段已经处理好了,别二次转义」。只写safeHTML会把用户写的<当成标签注入页面。
图表页面的完整做法见图表。
本站主题的实际实现
本站每个代码块顶部的文件名(例如本文里那些 layouts/_markup/render-codeblock.html)就是钩子渲染出来的。主题 hugo-docs-theme 的实现如下,它同时演示了「高亮选项透传」「不支持的语言回退纯文本」「信息字符串里的自定义属性 file 变成题注」三件事:
{{- $opts := .Options -}}
{{- if not (transform.CanHighlight .Type) -}}
{{- $opts = merge $opts (dict "type" "text") -}}
{{- end -}}
{{- $result := transform.HighlightCodeBlock . $opts -}}
{{- $file := .Attributes.file -}}
{{- $lang := .Type -}}
<div class="code-block{{ with $file }} has-file{{ end }}">
<div class="code-block-head">
{{- with $file }}<span class="code-block-file">{{ . }}</span>{{ end }}
{{- if and $lang (ne $lang "text") }}<span class="code-lang">{{ $lang }}</span>{{ end }}
</div>
{{ $result.Wrapped }}
</div>对照默认实现可以看出:钩子的自由度就在于「谁来包裹、包裹成什么」。不写钩子时输出的是高亮器自己的包裹元素,这里在它外面再套一层 .code-block 容器与头部(文件名 + 语言标签 + 复制按钮位),代码本身仍然交给同一个高亮器渲染。
本站实际渲染效果
下面三个代码块是在本文正文里真的构建出来的,不是把构建产物再贴一遍;你看到的外框、文件名、右上角语言标签和悬停才出现的复制按钮,都是本站代码块渲染钩子的输出。写法在上、产物在下,对照着看。
带语言标记的围栏(```go):
package main
import "fmt"
func main() {
fmt.Println("hello")
}你看到的结构:最外层是 <div class="code-block">(模板里那层容器;有文件名时还会追加 has-file 类),里面先是一个 <div class="code-block-head">,头部里放了 <span class="code-lang">go</span>(模板里的判断是 {{ if and $lang (ne $lang "text") }}),再是 $result.Wrapped 输出的 <div class="highlight"><pre …><code …>。复制按钮不在这一层 HTML 里:按钮由 themes/hugo-docs-theme/assets/js/site.js 的 initCodeCopy() 在浏览器里注入,文案是「复制」(复制成功后短暂变成「已复制」),所以关掉 JavaScript 时它不存在,代码本身照常可读。
带 {file="…"} 属性的围栏:
<div class="code-block">{{ .Title }}</div>文件名从哪来:{file="layouts/example.html"} 写在信息字符串的花括号里,属于通用属性(不是高亮选项),因此进的是钩子上下文里的 .Attributes,不是 .Options。模板里 {{ $file := .Attributes.file }} 把它取出来,容器据此加上 has-file 类,头部用 {{ with $file }}<span class="code-block-file">{{ . }}</span>{{ end }} 输出文件名。注意语言标签仍然在:本例代码语言是 html,模板对 $lang 的判断并不因为文件名而跳过,所以照样输出 html——文件名靠左、语言标签靠右(.code-block-head .code-lang { margin-left: auto },assets/css/ui.css)。
不带语言标记的围栏:
这一块没有语言标记(起始围栏后面什么都没有)。
本站钩子把它的 Type 当成空处理,
于是头部里既没有文件名,也没有语言标签。差别在哪,一行行说:
- 头部是空的。
$file不存在、$lang是空串,模板里{{ with $file }}与{{ if and $lang … }}两个判断都不成立,<div class="code-block-head">里什么都没有; - 空头部不占位置:
assets/css/ui.css里.code-block-head:empty { display: none },所以你看不到多余的一条空白; - 代码没有语法着色,按纯文本输出。实测(Hugo 0.167.0):三种围栏的产物分别读自
public/render-hooks/code-blocks/index.html,不带语言那一块的输出是<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text">…——没有 Chroma 的kn、nx之类的记号类名(对比上面go那一块的<span class="kn">package</span>)。 - 模板里
{{ if not (transform.CanHighlight .Type) }}正是为「高亮器不认识这个语言」准备的兜底:判真时把选项并成dict "type" "text"(拿不准某个语言名是否被支持,可以在模板里先用transform.CanHighlight问一声)。空Type具体走哪一支属于实现细节,本页不把「它一定命中兜底」写成结论:上面的产物只证明最终输出是language-text、没有记号类名,兜底与否用上面的纯文本结果核对即可。
和 Hugo 默认输出的差别:不写钩子时,Hugo 直接输出高亮结果本身,外层是 transform.HighlightCodeBlock 的默认包裹元素 <div class="highlight"><pre …><code …>,通用属性(如 file)会被加到那个外层元素上,没有文件名标题、没有语言标签、没有复制按钮。本站钩子做的事就是在原先的包裹外面再套一层 .code-block:多出头部(文件名 + 语言标签)与复制按钮位,代码部分仍然是同一个高亮器、同一份选项——模板开头就把 .Options 原样接过去,所以 lineNos、tabWidth 这类高亮选项在本站与默认输出里的作用完全一致。实测(Hugo 0.167.0):本站产物里 file 既出现在头部(<span class="code-block-file">),也同时保留了默认行为——它仍作为属性留在内层 <div class="highlight" file="layouts/example.html"> 上;这两件事并不冲突,一处是钩子自己加的题注,一处是高亮器对通用属性的默认处理。
什么时候用,什么时候别用
该用:
- 给代码块加文件名标题、行号开关、复制按钮等统一的包装;
- 为特定语言(Mermaid、PlantUML、Python 运行演示等)提供专门的渲染方式;
- 不支持的语言想回退成纯文本,避免出现半截高亮的乱码;
- 想自己包裹高亮结果(用
.Inner而不是.Wrapped)。
别用:
- 只想换代码配色——那是
markup.highlight配置与 Chroma 样式表的事,见语法高亮; - 只想给某一个代码块特殊处理——直接在 Markdown 的信息字符串里加属性更简单;
- 想用钩子去执行代码或做语法检查——钩子只负责输出 HTML。
内建钩子
Hugo 自带一个内建代码块渲染钩子,用于渲染 GoAT 图表(ASCII 图),详见图表与 diagrams.Goat。
与链接、图片不同,代码块没有 useEmbedded 这类开关:Hugo 只有 GoAT 这一个内建代码块钩子。
验证与常见坑
验证方法:先只放一个「与默认行为一致」的钩子(就是 {{ $result := transform.HighlightCodeBlock . }} 两行),构建后对比改动前后的 HTML——两者应该完全一致。这是最省事的基线检查:如果连基线都不一致,问题出在钩子本身,而不是你后面加的逻辑。
hugo --ignoreCache --destination tmp-out你应当看到什么:
- 代码块仍有高亮颜色(说明没把
$result.Wrapped丢掉); - 信息字符串里的
class、id出现在输出的外层元素上; - 信息字符串里的
lineNos、tabWidth只影响代码内部,不会变成 HTML 属性。
三类典型问题:
| 类别 | 现象 | 原因与修法 |
|---|---|---|
| 钩子没生效 | 没有报错,代码块与以前一样 | 文件名或位置不对;限定名拼错(render-codeblock-mermiad.html)会静默回退到通用模板 |
| 没报错但结果不对 | 代码块变成空白,或只剩一个空框 | 忘了输出 $result.Wrapped/$result.Inner;高亮结果算出来了却没写出来 |
| 没报错但结果不对 | 代码里的 < 变成可见的 <,或者标签被当成 HTML 执行了 |
.Inner 的转义处理写反了:纯文本要 htmlEscape,确实是 HTML 才用 safeHTML |
| 没报错但结果不对 | Mermaid 代码块显示成一大段文字,图没出来 | 语言限定模板没被匹配到,或基础模板末尾那段脚本没加 |
| 报错看不懂 | 报错带模板文件名与行号,或出现 can't evaluate field Anchor 之类 |
用了非代码块钩子的字段;代码块钩子没有 .Anchor、.Text、.Destination,请对照本页「上下文」 |
PageInner details
PageInner 的主要用途是相对于被包含的页面来解析链接与页面资源。例如可以创建一个「包含」短代码,用多个内容文件拼装一个页面,同时为脚注与目录保留全局上下文:先用位置参数取出要包含的页面逻辑路径,再调用该页面的 RenderShortcodes 方法,取不到页面时用 errorf 报错。
{{ with .Get 0 }}
{{ with $.Page.GetPage . }}
{{- .RenderShortcodes }}
{{ else }}
{{ errorf "The %q shortcode was unable to find %q. See %s" $.Name . $.Position }}
{{ end }}
{{ else }}
{{ errorf "The %q shortcode requires a positional parameter indicating the logical path of the file to include. See %s" .Name .Position }}
{{ end }}然后在 Markdown 中用 Markdown 记法调用这个短代码,被包含页面的路径写在位置参数里。
{{% include "/posts/post-2" %}}渲染 /posts/post-2 时触发的任何渲染钩子,调用 Page 会得到 /posts/post-1,调用 PageInner 则会得到 /posts/post-2。
PageInner 在不适用时会回退为 Page 的值,并且始终有返回值。它只对调用 RenderShortcodes 方法的短代码有意义,并且必须以 Markdown 记法调用该短代码。