Fragments
返回给定页面中片段的数据结构。
这一页解决什么问题
Fragments 把页面上的标题(片段)整理成结构化数据:有哪些锚点、层级关系如何、以及可以直接输出成目录的 HTML。做「本页目录」、校验锚点是否存在、按标题树遍历内容时用它。
什么时候用,什么时候别用
该用:
- 需要自己控制目录的起始层级与列表类型 →
.Fragments.ToHTML; - 需要判断某个
id是否存在或重复 →.Fragments.Identifiers.Contains/.Count; - 需要在链接渲染钩子里校验锚点;
- 需要遍历标题树 →
.Fragments.Headings/.HeadingsMap。
别用:
- 只想输出默认目录 → 用
TableOfContents,它按项目配置渲染; - 想拿到「与相关文章匹配的那些标题」→ 用
HeadingsFiltered; - 在短代码里用
Fragments又要用 Markdown 记法调用该短代码 → 会形成循环,见下文「说明」。
用法
在 URL 中,无论绝对路径还是相对路径,片段都指向页面上某个 HTML 元素的 id 属性。
/articles/article-1#section-2
------------------- ---------
path fragmentHugo 会为页面内容中的每个 Markdown ATX 与 setext 标题分配 id 属性。你可以按需用 Markdown 属性覆盖该 id。这就在目录(TOC)条目与页面上的标题之间建立了对应关系。
使用 Page 对象上的 Fragments 方法,可以用 Fragments.ToHTML 方法生成目录,也可以遍历 Fragments.Map 数据结构。用下面的方法来检查、校验并渲染页面片段。
方法
在 Fragments 对象上使用这些方法。
Headings- (
slice)页面上所有标题的 map 切片,每个标题是一个一级键。每个 map 包含以下键:ID、Level、Title与Headings。要查看数据结构:go-html-template<pre>{{ debug.Dump .Fragments.Headings }}</pre> HeadingsMap- (
map)页面上所有标题的嵌套 map。每个 map 包含以下键:ID、Level、Title与Headings。要查看数据结构:go-html-template<pre>{{ debug.Dump .Fragments.HeadingsMap }}</pre> Identifiers- (
slice)一个切片,包含页面上每个标题的id属性。若已做相应配置,还会包含页面上每个描述术语(即dt元素)的id属性。参见配置标记。
要查看数据结构:
go-html-template<pre>{{ debug.Dump .Fragments.Identifiers }}</pre> Identifiers.Contains ID- (
bool)报告页面上是否有一个或多个标题具有给定的id属性,可用于在链接渲染钩子中校验片段。go-html-template{{ .Fragments.Identifiers.Contains "section-2" }} → true Identifiers.Count ID- (
int)页面上具有给定id属性的标题数量,可用于检测重复。go-html-template{{ .Fragments.Identifiers.Count "section-2" }} → 1 ToHTML- (
template.HTML)以嵌套列表的形式返回 TOC,可以是有序列表也可以是无序列表,与TableOfContents方法返回的 HTML 相同。该方法接收三个参数:起始层级(int)、结束层级(int)以及一个布尔值(true返回有序列表,false返回无序列表)。当你希望独立于项目配置中的目录设置来控制起始层级、结束层级或列表类型时,就使用这个方法。
go-html-template{{ $startLevel := 2 }} {{ $endLevel := 3 }} {{ $ordered := true }} {{ .Fragments.ToHTML $startLevel $endLevel $ordered }}Hugo 会把它渲染为:
html<nav id="TableOfContents"> <ol> <li><a href="#section-1">Section 1</a> <ol> <li><a href="#section-11">Section 1.1</a></li> <li><a href="#section-12">Section 1.2</a></li> </ol> </li> <li><a href="#section-2">Section 2</a></li> </ol> </nav>
说明
完整示例:列出锚点并输出目录
最小站点:content/docs/guide/alpha.md 的正文有三个标题(## Section 1、### Section 1.1、## Section 2);beta.md 一个标题也没有。模板放在 layouts/_default/single.html:
<p>锚点:{{ delimit .Fragments.Identifiers "、" }}</p>
<p>包含 section-1:{{ .Fragments.Identifiers.Contains "section-1" }}</p>
<p>section-1 出现次数:{{ .Fragments.Identifiers.Count "section-1" }}</p>
{{ .Fragments.ToHTML 2 3 false }}hugo --source <站点目录> --ignoreCache 构建后,alpha 输出:
<p>锚点:section-1、section-11、section-2</p>
<p>包含 section-1:true</p>
<p>section-1 出现次数:1</p>
<nav id="TableOfContents">
<ul>
<li><a href="#section-1">Section 1</a>
<ul>
<li><a href="#section-11">Section 1.1</a></li>
</ul>
</li>
<li><a href="#section-2">Section 2</a></li>
</ul>
</nav>beta(没有任何标题)输出:
<p>锚点:</p>
<p>包含 section-1:false</p>
<p>section-1 出现次数:0</p>
<nav id="TableOfContents"></nav>你应当看到什么:锚点顺序就是标题在正文中出现的顺序;ToHTML 第 3 个参数传 false 得到 <ul>(传 true 得到 <ol>);页面没有标题时不会报错,只得到空切片与空的 <nav>。
.Fragments.Headings 的结构(实测,用一层 range 打印,格式为 [ID/Level(子项…)]):
[/0(section-1/2)(section-2/2)]顶层只有一个 ID 为空、Level 为 0 的根节点,它的 .Headings 才是各个 h2;h3 再挂在 h2 的 .Headings 下,需要递归遍历。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,Windows;正文标题为 ## Section 1 / ### Section 1.1 / ## Section 2。
| 情况 | 结果 | 是否报错 |
|---|---|---|
| 页面有标题 | .Fragments.Identifiers 是按出现顺序排列的 id 切片 |
否 |
| 页面没有标题 | Identifiers、Headings 均为空切片;ToHTML 返回空的 <nav> |
否 |
Identifiers.Contains "section-1" |
true;不存在的 id 为 false |
否 |
Identifiers.Count "section-1" |
1;不存在的 id 为 0 |
否 |
ToHTML 2 3 false |
2–3 级的无序列表;true 则为有序列表 |
否 |
Headings |
顶层是 ID 为空、Level 为 0 的根节点 |
否 |
| 返回类型 | tableofcontents.Fragments |
否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 目录顺序不对 | ToHTML 输出的层级与正文不一致 |
标题层级跳跃(例如从 h2 直接到 h4) |
保持标题层级连续,或用参数限定起始/结束层级 |
| 没报错但结果不对 | 中文标题的锚点看起来是中文 | Hugo 保留 CJK 字符、只去掉标点并转小写 | 需要英文字锚点时用 Markdown 属性显式指定 id |
| 什么都没输出 | 短代码里的标题没有进目录 | 用标准记法({{< >}})调用的短代码,其 .Inner 在 Markdown 之后渲染 |
这是预期行为;需要标题进目录就用 Markdown 记法,并避开循环(见「说明」) |
更多排查入口见故障排查。