表格是博客中常用的信息展示方式，而表题能够帮助读者理解表格内容并方便文内引用，但 Hugo 默认的 Markdown 表格语法不包含表题功能。
下面介绍渲染钩子和属性块的配置步骤，以及如何在 Markdown 中为表格添加表题，以实现如上效果。
开启 Hugo 属性块支持
Hugo 默认使用 Goldmark 作为 Markdown 渲染器，它支持为块级元素（如表格）添加自定义属性。
修改主题配置文件：
1
2
| [markup.goldmark.parser.attribute]
block = true
|
启用此配置后，Goldmark 将解析表格下方的 { caption="..." } 属性块，并渲染为表格标题。
创建表格渲染钩子
创建以下文件：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
| {{- /* 覆盖来源：FixIt/layouts/_markup/render-table.html */ -}}
{{- /*
Add a table wrapper to better style overflow tables
The reset of the template is the same as the default render-table.html
See https://gohugo.io/render-hooks/tables/
*/ -}}
<div class="table-wrapper">
<table
{{- range $k, $v := .Attributes }}
{{- if $v }}
{{- printf " %s=%q" $k $v | safeHTMLAttr }}
{{- end }}
{{- end }}>
{{- /* ======================== 修改点 1：开始 ======================== */ -}}
{{- /* 支持 `caption` 属性，渲染表格表题，样式由 SCSS 控制 */ -}}
{{- with .Attributes.caption }}
<caption>{{ . | $.Page.RenderString }}</caption>
{{- end }}
{{- /* ======================== 修改点 1：结束 ======================== */ -}}
<thead>
{{- range .THead }}
<tr>
{{- range . }}
<th
{{- /* ======================== 修改点 2：开始 ======================== */ -}}
{{- /* 修改对齐方式，便于 SCSS 统一样式 */ -}}
{{- with .Alignment }}
{{- printf " class=%q" (printf "text-align-%s" .) | safeHTMLAttr }}
{{- end -}}
{{- /* ======================== 修改点 2：结束 ======================== */ -}}
>
{{- .Text -}}
</th>
{{- end }}
</tr>
{{- end }}
</thead>
<tbody>
{{- range .TBody }}
<tr>
{{- range . }}
<td
{{- /* ======================== 修改点 3：开始 ======================== */ -}}
{{- /* 修改对齐方式，便于 SCSS 统一样式 */ -}}
{{- with .Alignment }}
{{- printf " class=%q" (printf "text-align-%s" .) | safeHTMLAttr }}
{{- end -}}
{{- /* ======================== 修改点 3：结束 ======================== */ -}}
>
{{- .Text -}}
</td>
{{- end }}
</tr>
{{- end }}
</tbody>
</table>
</div>
|
- 模板保留了 FixIt 主题的
table-wrapper 滚动容器，并新增对 <caption> 标签的支持。 - 通过
{{- with .Attributes.caption }} 判断是否存在 caption 属性，如果存在则渲染。 - 其余部分与默认的表格渲染钩子保持一致，确保表格能够正确显示。
添加 CSS 样式
创建以下文件：
1
2
3
4
5
6
7
| :root {
--c-meta: #8b949e;
}
[data-theme="dark"] {
--c-meta: #7d8792;
}
|
创建以下文件：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
| :root {
// 字号
--c-font-base: clamp(0.96875rem, 0.85rem + 0.2vw, 1rem);
--c-font-xxs: calc(0.625 * var(--c-font-base));
--c-font-xs: calc(0.75 * var(--c-font-base));
--c-font-s: calc(0.875 * var(--c-font-base));
--c-font-m: var(--c-font-base);
--c-font-l: calc(1.125 * var(--c-font-base));
--c-font-xl: calc(1.25 * var(--c-font-base));
--c-font-xxl: calc(1.5 * var(--c-font-base));
--c-font-xxxl: calc(1.75 * var(--c-font-base));
// 边距
--c-space-1: 0.25rem; /* 1 unit = 4px */
--c-space-2: calc(var(--c-space-1) * 2); /* 0.5rem */
--c-space-4: calc(var(--c-space-1) * 4); /* 1rem */
--c-space-6: calc(var(--c-space-1) * 6); /* 1.5rem */
--c-space-8: calc(var(--c-space-1) * 8); /* 2rem */
--c-space-10: calc(var(--c-space-1) * 10); /* 2.5rem */
--c-space-12: calc(var(--c-space-1) * 12); /* 3rem */
@media (max-width: 680px) { --c-space-1: 0.22rem; }
@media (min-width: 681px) and (max-width: 1200px) { --c-space-1: 0.23rem; }
// 颜色
--c-meta: #8b949e;
}
[data-theme="dark"] {
// 颜色
--c-meta: #7d8792;
}
|
创建以下文件：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
| // ========= 全局 =========
// 全局字体
body { font-size: var(--c-font-m); }
h1 { font-size: var(--c-font-xxl); }
h2 { font-size: var(--c-font-xl); }
h3, h4 { font-size: var(--c-font-l); }
// ========= 文章页 =========
.single {
.content {
.table-wrapper {
text-align: left;
overflow-x: auto;
font-size: var(--c-font-s);
> table {
width: 100%;
max-width: none;
white-space: nowrap;
min-width: max-content;
-webkit-overflow-scrolling: touch;
}
caption {
caption-side: top;
text-align: center;
color: var(--c-meta);
font-size: var(--c-font-s);
margin-bottom: var(--c-space-2);
}
}
}
}
|
表题显示在表格下方：caption-side: top 改为 bottom，margin-bottom 改为 margin-top。
在 Markdown 中使用
表格下方紧贴一行添加属性块即可添加表题，例如：
1
2
3
4
5
| | 姓名 | 角色 |
| :--- | :--- |
| 张三 | 作者 |
| 李四 | 编辑 |
{ caption="**表 1**：核心团队成员" }
|
注意事项：
- 属性块
{ caption="..." } 必须紧贴表格的最后一行，否则 Goldmark 将无法识别。 - 表题支持 Markdown 语法（如
**加粗**），渲染后会居中显示在表格的上方。
编辑器兼容提示
- Typora：普通编辑视图中的属性块会显示在表格内部，需切换至源代码模式（
Ctrl+/），确保属性块紧贴表格下方，以便正确渲染。 - VSCode + Prettier：启用 Prettier 后，保存 Markdown 文件可能会插入空行，导致 Goldmark 无法渲染表题，可在项目根目录创建
.prettierignore 文件并添加 *.md，忽略其格式化。
Aria
