表格
创建表格渲染钩子,遍历表头与表体单元格覆盖 Markdown 表格到 HTML 的转换;含对齐取值与结构遗漏的风险。
开始之前,你需要
- 读过简介,知道钩子模板要放在
layouts/_markup/、文件名怎么取。 - 能看懂 Go 模板里的双层
range循环(外层行、内层单元格)。
读完之后你能
- 写出一个与 Hugo 默认行为一致的
render-table.html,并会按需要加class、scope等结构; - 说清
THead/TBody的「切片的切片」结构,以及Alignment为空字符串时该怎么处理; - 知道表格钩子只要漏掉表头或表体,页面结构就会不完整——而且不会有任何报错。
接着读:原样透传 · 简介 · Markdown 属性
上下文
表格渲染钩子模板接收以下上下文:
Attributes- (
map)Markdown 属性,需要按下面的方式配置站点后才可用:toml[markup.goldmark.parser.attribute] block = true Ordinal- (
int)表格在页面中的序号,从 0 开始。 Page- (
page)当前页面的引用。 PageInner- (
page)通过RenderShortcodes方法嵌套的页面的引用。详见下文 PageInner details。 Position- (
string)表格在页面内容中的位置。 THead- (
slice)表头行的切片,其中每个元素是一行单元格的切片。 TBody- (
slice)表体行的切片,其中每个元素是一行单元格的切片。
实测(Hugo 0.167,本站):本站 hugo.toml 里 [markup.goldmark.parser.attribute] block = true,因此表格下方独立一行的 {.no-wrap-first-col} 这类块级属性在表格钩子里可以通过 .Attributes 取到。不开这项时,那一行会被当成表格的数据行渲染成垃圾文本——这也是本站必须打开它的原因。
表格单元格
THead 与 TBody 返回的是「切片的切片」,其中每个表格单元格具有以下字段:
Alignment- (
string)单元格内文本的对齐方式,取值为left、center或right。 Text- (
template.HTML)单元格内的文本。
示例
默认配置下,Hugo 按 GitHub 风格 Markdown 规范渲染 Markdown 表格。要写出行为一致的渲染钩子:
<table
{{- range $k, $v := .Attributes }}
{{- if $v }}
{{- printf " %s=%q" $k $v | safeHTMLAttr }}
{{- end }}
{{- end }}>
<thead>
{{- range .THead }}
<tr>
{{- range . }}
<th
{{- with .Alignment }}
{{- printf " style=%q" (printf "text-align: %s" .) | safeHTMLAttr }}
{{- end -}}
>
{{- .Text -}}
</th>
{{- end }}
</tr>
{{- end }}
</thead>
<tbody>
{{- range .TBody }}
<tr>
{{- range . }}
<td
{{- with .Alignment }}
{{- printf " style=%q" (printf "text-align: %s" .) | safeHTMLAttr }}
{{- end -}}
>
{{- .Text -}}
</td>
{{- end }}
</tr>
{{- end }}
</tbody>
</table>边界情况
.Alignment是空字符串表示这一列没有显式对齐要求(Markdown 分隔行里写的是---而不是:---)。示例用with判断后再输出style,正是为了避免产生多余的style=""。.Attributes里值为空字符串的键会被跳过(示例里的{{- if $v }})。这是必要的:否则会输出class=""这样的空属性。.Text已经是template.HTML,直接输出即可,不要再套htmlEscape——那会把单元格里的<code>、<a>变成可见的标签文本。- 表体为空时,
range .TBody什么都不输出,但模板仍然会写出<tbody></tbody>;这在 HTML 里是合法的,目录与样式不受影响。 - 确有必要拼接属性时,必须像示例那样通过
safeHTMLAttr处理,否则引号会被转义成"(见简介的三种值类型)。
本站实际渲染效果
下面这张表是真的用 Markdown 表格语法写在正文里的,不是代码块里的示意;本站没有表格渲染钩子(themes/hugo-docs-theme/layouts/_markup/ 下只有 render-link.html、render-codeblock.html、render-blockquote.html),所以它是 Goldmark 默认渲染的结果:
| 钩子文件 | 本站是否存在 | layouts/_markup/ 里已有的同类 |
|---|---|---|
render-heading.html |
否 | render-link.html |
render-image.html |
否 | render-codeblock.html |
render-table.html |
否 | render-blockquote.html |
实测(Hugo 0.167.0 extended,本站:站点构建(hugo --ignoreCache)后读 public/render-hooks/tables/index.html)产物里这张表的开头几行是(为便于阅读,缩进简化为两个空格;标签、属性与产物逐字一致):
<table>
<thead>
<tr>
<th style="text-align: left">钩子文件</th>
<th style="text-align: center">本站是否存在</th>
<th style="text-align: right"><code>layouts/_markup/</code> 里已有的同类</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left"><code>render-heading.html</code></td>
...对照点:
- 结构是
<table>→<thead>→<tr>→<th>,再接<tbody>→<tr>→<td>:没有class、没有外层容器,表头与表体各成一段——与本页「示例」模板要复现的结构一一对应。 - 对齐标记落在单元格的内联样式上:
:---/:---:/---:分别输出style="text-align: left"/style="text-align: center"/style="text-align: right",加在对应的<th>/<td>上,而不是加在<table>上。这与本页「示例」模板里printf " style=%q" (printf "text-align: %s" .)的写法完全一致——模板里那一句就是在复现默认行为。 Alignment只在有钩子时才有人读:本站没有钩子,这些对齐样式是 Goldmark 自己按分隔行算出来的,任何模板都没有参与。- 行内代码照常渲染:单元格里写成行内代码的
render-heading.html输出为<code>render-heading.html</code>。也就是说单元格内容是已经渲染过的 HTML,这正是上面「表格单元格」里.Text的类型是template.HTML、不该再转义的原因。 - 「单元格级别」的钩子还谈不上:上面「表格单元格」讲的
Alignment/Text是render-table.html的上下文;本站没有这个文件,所以不存在单元格级别的渲染,单元格内容全部按默认行为渲染。
使用要点
模板对 THead 与 TBody 各做一次外层遍历得到行,再对每一行做一次内层遍历得到单元格,因此表头与表体的结构完全由模板决定:可以给表头行加 scope 属性、给表格外层加 class,或者按列拆分渲染。
Alignment 为空字符串时表示该列没有显式对齐要求,上例用 with 判断后再输出 style,避免产生多余的空属性。单元格内容已经是 template.HTML,直接输出即可;确有必要拼接属性时,应像上例那样通过 safeHTMLAttr 处理,以免属性被转义。
只要提供了表格钩子,输出的 <table> 结构就由模板负责,表头、表体与单元格都不能遗漏,否则页面结构会不完整。
「不能遗漏」具体指什么:默认渲染会输出 <thead>、<tbody> 以及每个单元格的 <th>/<td>。一旦自己接管,模板少写哪个标签,页面上就少哪一段结构——例如只写了 range .TBody,表头整个消失,表格的第一行被当成数据行。Hugo 不会校验你的 HTML 是否完整,构建照样成功。
给表头单元格补 scope="col" 是一个低成本、收益明确的做法:屏幕阅读器据此知道该单元格是列标题,表格的可访问性会明显变好。把 THead 里输出的 <th> 改成:
<th scope="col"
{{- with .Alignment }}
{{- printf " style=%q" (printf "text-align: %s" .) | safeHTMLAttr }}
{{- end -}}
>
{{- .Text -}}
</th>什么时候用,什么时候别用
该用:
- 给全站表格统一套一层可横向滚动的容器,或统一的
class; - 给表头单元格补
scope="col",改善可访问性; - 让内容侧可以用
{.no-wrap-first-col}这样的属性开关控制某张表格的呈现; - 按列渲染不同结构(例如首列输出为行标题
<th scope="row">)。
别用:
- 只想改表格的边框、斑马纹、字号——CSS 就够了;
- 只想改某一章里的表格——用分区级的
_markup目录,或直接写 HTML; - 想给表格加排序、筛选——那是前端脚本的事,钩子只输出静态 HTML。
验证与常见坑
验证方法:写一个与默认行为一致的钩子,构建后确认结构完整。
hugo --ignoreCache --destination tmp-out# Linux / macOS
grep -c '<thead>\|<tbody>' tmp-out/posts/example/index.html# Windows PowerShell
(Select-String -Path tmp-out\posts\example\index.html -Pattern '<thead>|<tbody>' -AllMatches).Matches.Count你应当看到什么:每个 Markdown 表格都同时有 <thead> 与 <tbody>;表头里的单元格是 <th>,表体里的是 <td>;有 .Attributes 时属性出现在 <table> 上而不是单元格上。三者缺一,就是模板漏了结构。
三类典型问题:
| 类别 | 现象 | 原因与修法 |
|---|---|---|
| 钩子没生效 | 没有报错,表格和以前一样 | 文件名或位置不对;到简介的排查表逐条核对 |
| 没报错但结果不对 | 表头整行消失,或表格只剩表头没有数据 | 模板漏了 range .THead 或 range .TBody;注意 THead、TBody 的大小写不能写错 |
| 没报错但结果不对 | 单元格里出现 ",或 <code> 变成了可见文本 |
属性没套 safeHTMLAttr,或把 template.HTML 的 .Text 又转义了一遍 |
| 没报错但结果不对 | 表格下方多出一行 {.no-wrap-first-col} 文本 |
站点没开 [markup.goldmark.parser.attribute] block = true,块级属性没被解析 |
| 报错看不懂 | 报错带模板文件名与行号 | 模板里双层 range 少写了 {{ end }};每个 range 都要有自己的 {{ end }} |
更多相关问题见故障排查;表格属性的写法见 Markdown 属性。
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 记法调用该短代码。