渲染钩子

标题

创建标题渲染钩子,覆盖 Markdown 标题到 HTML 的转换,并为标题追加锚点链接;含 Anchor 的风险与验证方法。

难度
参考
预计用时
10–15 分钟

开始之前,你需要

  • 读过简介,知道钩子模板要放在 layouts/_markup/、文件名怎么取。
  • 站点已经能生成目录(TOC),改完标题钩子后能立刻看到锚点是否还有效。

读完之后你能

  • 写出一个给每个标题追加锚点链接的 render-heading.html;
  • 说清 Anchor 是怎么来的、改标题文字为什么会弄坏旧链接;
  • 知道标题钩子漏掉哪个字段会让目录与锚点导航整体失效。

接着读:代码块 · 简介 · 故障排查

上下文

标题渲染钩子模板接收以下上下文:

Anchor
(string)标题元素的 id 属性。
Attributes
(map)Markdown 属性,需要按下面的方式配置站点后才可用:
toml
[markup.goldmark.parser.attribute]
title = true
Level
(int)标题层级,取值为 1 到 6。
Ordinal
(0.160.0 新增)
(int)标题在页面中的序号,从 0 开始。
Page
(page)当前页面的引用。
PageInner
(page)通过 RenderShortcodes 方法嵌套的页面的引用。详见下文 PageInner details。
PlainText
(string)标题文本的纯文本形式。
Position
(0.160.0 新增)
(string)标题在页面内容中的位置。
Text
(template.HTML)标题文本。

实测(Hugo 0.167,本站):本站 hugo.toml 里 [markup.goldmark.parser.attribute] 同时设了 block = true 与 title = true,所以标题上的 {.class} 之类属性在本站是能拿到的。若你的站点只开了 block,标题钩子里的 .Attributes 会是空的。

示例

默认配置下,Hugo 按 CommonMark 规范渲染 Markdown 标题,并额外加入自动生成的 id 属性。要写出行为一致的渲染钩子:

layouts/_markup/render-heading.htmlgo-html-template
<h{{ .Level }} id="{{ .Anchor }}" {{- with .Attributes.class }} class="{{ . }}" {{- end }}>
  {{- .Text -}}
</h{{ .Level }}>

要为每个标题右侧追加一个锚点链接:

layouts/_markup/render-heading.htmlgo-html-template
<h{{ .Level }} id="{{ .Anchor }}" {{- with .Attributes.class }} class="{{ . }}" {{- end }}>
  {{ .Text }}
  <a href="#{{ .Anchor }}">#</a>
</h{{ .Level }}>

边界情况

  • .Level 的取值范围是 1 到 6。正文里写 #######(七个井号)不会被当作标题,钩子也就不会触发——它是普通段落。
  • .Attributes.class 没写时是空字符串,{{ with }} 判假,不会输出空的 class=""。这是期望行为。
  • .Anchor 是普通字符串,直接放进 id="{{ .Anchor }}" 即可;CJK 标题的锚点会保留汉字本身,实测本站 ## 警示块 生成的 id 就是 警示块,## 使用要点 生成 使用要点。
  • .Text 是已经渲染过的 template.HTML,直接输出;不要对它做转义。

本站实际渲染效果

下面两个标题是真的写在正文里的 Markdown 标题,不是代码块里的示意——它们就在这一页上被渲染成了 HTML 标题元素。本站的渲染钩子只有 render-link.html、render-codeblock.html、render-blockquote.html 三个(themes/hugo-docs-theme/layouts/_markup/ 是本站唯一的 _markup 目录),没有 render-heading.html,所以下面这两个标题的标签名、层级和 id 全是 Hugo 默认行为。

演示刻意写成 ####:本站右栏目录只收 h2–h3([markup.tableOfContents] startLevel = 2 endLevel = 3),用 #### 不会把读者目录搅乱。

实测标题:中文、标点与空格

Heading with ASCII Punctuation!

实测(Hugo 0.167.0 extended,本站:站点构建(hugo --ignoreCache)后读 public/render-hooks/headings/index.html)产物里这几个标题的标签是:

html
<h3 id="本站实际渲染效果">本站实际渲染效果</h3>
<h4 id="实测标题中文标点与空格">实测标题:中文、标点与空格</h4>
<h4 id="heading-with-ascii-punctuation">Heading with ASCII Punctuation!</h4>

对照点:

  • 层级来自井号个数:两个 #### 输出 <h4>;本页上面那些 ## 输出的是 <h2 id="示例">、<h2 id="使用要点">(同样从产物里核对到)。
  • id 由 Goldmark 从标题文字推导,且不等于标题原文:全角冒号 :、顿号 、、叹号 ! 都被去掉,ASCII 大写转小写、空格转连字符;中文本身原样保留,没有转成拼音或十六进制编码。
  • 没有钩子,就没有任何模板能改它:Anchor、Level、Text 这些字段只是钩子模板的上下文;本站没有标题钩子,所以标题的 id、层级都没人经手。你在产物里看到的这段 HTML,正是自己写 render-heading.html 之后要负责重新生成的东西。
  • 右上角的 # 与渲染钩子无关:它是前端脚本注入的,HTML 里本来没有。themes/hugo-docs-theme/assets/js/site.js 里的 initHeadingAnchors() 选取 .doc-body h2[id], .doc-body h3[id], .doc-body h4[id],再给每个元素 appendChild 一个 <a href="#那个id">#</a>。上面两个默认渲染的 #### 标题同样带 # 按钮——这恰好证明按钮跟钩子没有关系,因为本页根本没有标题钩子。 两者的区别在于:脚本注入的锚点只存在于浏览器里,看源码或抓取 HTML 都看不到;而本页「示例」模板里的 <a href="#{{ .Anchor }}">#</a> 是构建时写进 HTML 的,产物里就有。

使用要点

Anchor 通常由标题文本推导而来,因此标题文本一改动,旧锚点就会失效,指向旧链接的读者会落到错误的位置。示例用 id="{{ .Anchor }}" 把锚点原样输出到标题元素上,标题钩子因此也是统一改写锚点命名规则的地方。

Attributes 中的 class 是标题钩子最常用的字段,上面的示例已经把它传递到输出的 <h*> 元素;其他属性可以按同样方式取用。只要提供了标题钩子,标题的整个 HTML 输出就由模板决定,因此 Level、Anchor 与 Text 都应保留在输出中,否则目录与锚点导航会失效。

标题钩子还可以按页面类型(type)、语言与输出格式分别提供,例如只为某个内容分区或 RSS 输出使用不同的标题结构,具体查找方式见简介。

什么时候用,什么时候别用

该用:

  • 给每个标题右侧加一个可点击的锚点链接(#),方便读者复制链接;
  • 统一锚点的命名规则,例如把中文标题的 id 改成拼音或英文,便于分享;
  • 给标题补 class,供 CSS 或页内脚本使用;
  • 为 RSS 等输出格式准备不同结构的标题(render-heading.rss.xml)。

别用:

  • 只想改变标题的字号、字体、颜色——那是 CSS 的事;
  • 只想给某一篇文章的某个标题加锚点——直接在 Markdown 里写 HTML 标题更直接;
  • 想用标题钩子来插入目录本身——目录是布局模板(如 partials/toc.html)的职责,标题钩子只负责输出标题元素。

验证与常见坑

验证方法:构建后到产出的 HTML 里确认两点——标题上有 id,且页面目录里的链接与这些 id 一一对应。

bash
hugo --ignoreCache --destination tmp-out
bash
# Linux / macOS:看某个页面里所有 h2/h3 的 id
grep -o '<h[23] id="[^"]*"' tmp-out/posts/example/index.html | head
powershell
# Windows PowerShell:同样的检查
Select-String -Path tmp-out\posts\example\index.html -Pattern '<h[23] id="[^"]*"' -AllMatches |
  ForEach-Object { $_.Matches.Value } | Select-Object -First 10

你应当看到什么:每个正文标题都带 id,id 的值与目录链接里 # 后面的片段完全一致。如果目录里有链接、页面上却没有对应的 id,就是钩子漏输出了 Anchor。

三类典型问题:

类别 现象 原因与修法
钩子没生效 没有报错,标题和以前一模一样 文件名或位置不对;到简介的排查表逐条核对
没报错但结果不对 目录点进去不跳转,或跳到文章开头 钩子漏了 id="{{ .Anchor }}";见上面的警示框
没报错但结果不对 标题里出现了 {.class} 这样的字面文本 站点没开 [markup.goldmark.parser.attribute] title = true,属性没被解析成 Attributes
报错看不懂 报错带模板文件名与行号 模板里少写 {{ end }};注意 <h{{ .Level }}> 与 </h{{ .Level }}> 要成对,且 {{ .Level }} 不能写错大小写

更多相关问题见故障排查。

PageInner details

PageInner 的主要用途是相对于被包含的页面来解析链接与页面资源。例如可以创建一个「包含」短代码,用多个内容文件拼装一个页面,同时为脚注与目录保留全局上下文:先用位置参数取出要包含的页面逻辑路径,再调用该页面的 RenderShortcodes 方法,取不到页面时用 errorf 报错。

layouts/_shortcodes/include.htmlgo-html-template
{{ 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 记法调用这个短代码,被包含页面的路径写在位置参数里。

content/posts/post-1.mdmd
{{% include "/posts/post-2" %}}

渲染 /posts/post-2 时触发的任何渲染钩子,调用 Page 会得到 /posts/post-1,调用 PageInner 则会得到 /posts/post-2。

PageInner 在不适用时会回退为 Page 的值,并且始终有返回值。它只对调用 RenderShortcodes 方法的短代码有意义,并且必须以 Markdown 记法调用该短代码。