渲染钩子 on Hugo 中文文档

简介

Thu, 01 Oct 2026 00:00:00 +0800

默认渲染与自定义渲染

把 Markdown 渲染为 HTML 时，渲染钩子会覆盖这一转换过程。每个钩子都是一个模板，受支持的元素类型各对应一个模板：

链接

Thu, 01 Oct 2026 00:00:00 +0800

Markdown 中的链接

一个 Markdown 链接由三部分组成：链接文本、链接目标地址，以及可选的链接标题。

[Post 1](/posts/post-1 "My first post")
 ------  -------------  -------------
  文本      目标地址        标题

这三部分会按下文所列的字段传入渲染钩子的上下文。

图片

Thu, 01 Oct 2026 00:00:00 +0800

Markdown 中的图片

一个 Markdown 图片由三部分组成：图片描述、图片目标地址，以及可选的图片标题。

![white kitten](/images/kitten.jpg "A kitten!")
  ------------  ------------------  ---------
     描述            目标地址          标题

这三部分会按下文所列的字段传入渲染钩子的上下文。

标题

Thu, 01 Oct 2026 00:00:00 +0800

上下文

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

Anchor

（string）标题元素的 id 属性。

Attributes

（map）Markdown 属性，需要按下面的方式配置站点后才可用：

[markup.goldmark.parser.attribute]
title = true

Level

（int）标题层级，取值为 1 到 6。

Ordinal

（int）标题在页面中的序号，从 0 开始。

Page

（page）当前页面的引用。

PageInner

（page）通过 RenderShortcodes 方法嵌套的页面的引用。详见下文 PageInner details。

PlainText

（string）标题文本的纯文本形式。

Position

（string）标题在页面内容中的位置。

Text

（template.HTML）标题文本。

示例

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

代码块

Thu, 01 Oct 2026 00:00:00 +0800

Markdown 中的代码块

下面这段 Markdown 含有一个围栏代码块：

```sh {class="my-class" id="my-codeblock" lineNos=inline tabWidth=2}
declare a=1
echo "$a"
exit
```

一个围栏代码块由以下部分组成：

起始代码围栏
可选的信息字符串
代码样例
结束代码围栏

在上面的例子中，信息字符串包含：

代码样例的语言（第一个词）
可选的属性列表，用空格或逗号分隔，写在花括号内

信息字符串中的属性可以是通用属性，也可以是高亮选项。

引用块

Thu, 01 Oct 2026 00:00:00 +0800

上下文

引用块渲染钩子模板接收以下上下文：

AlertType

（string）当 Type 为 alert 时适用，取警示块类型的小写形式。参见下文警示块。

AlertTitle

（template.HTML）当 Type 为 alert 时适用，取警示块标题。参见下文警示块。

AlertSign

（string）当 Type 为 alert 时适用，取警示块标记。通常用于表示警示块是否可在界面上折叠，取值为 +、- 或空字符串。参见下文警示块。

Attributes

（map）Markdown 属性，需要按下面的方式配置站点后才可用：

[markup.goldmark.parser.attribute]
block = true

Ordinal

（int）引用块在页面中的序号，从 0 开始。

Page

（page）当前页面的引用。

PageInner

（page）通过 RenderShortcodes 方法嵌套的页面的引用。详见下文 PageInner details。

Position

（string）引用块在页面内容中的位置。

Text

（template.HTML）引用块的文本；当 Type 为 alert 时不含第一行。参见下文警示块。

Type

（string）引用块类型。带警示块标记时返回 alert，否则返回 regular。参见下文警示块。

示例

默认配置下，Hugo 按 CommonMark 规范渲染 Markdown 引用块。要写出行为一致的渲染钩子：

表格

Thu, 01 Oct 2026 00:00:00 +0800

上下文

表格渲染钩子模板接收以下上下文：

Attributes

（map）Markdown 属性，需要按下面的方式配置站点后才可用：

[markup.goldmark.parser.attribute]
block = true

Ordinal

（int）表格在页面中的序号，从 0 开始。

Page

（page）当前页面的引用。

PageInner

（page）通过 RenderShortcodes 方法嵌套的页面的引用。详见下文 PageInner details。

Position

（string）表格在页面内容中的位置。

THead

（slice）表头行的切片，其中每个元素是一行单元格的切片。

TBody

（slice）表体行的切片，其中每个元素是一行单元格的切片。

表格单元格

THead 与 TBody 返回的是「切片的切片」，其中每个表格单元格具有以下字段：

原样透传

Thu, 01 Oct 2026 00:00:00 +0800

概述

Hugo 使用 Goldmark 把 Markdown 渲染为 HTML。Goldmark 支持通过自定义扩展来扩展核心功能。Passthrough 扩展会捕获并保留被定界符包围的原始 Markdown 文本片段，连定界符本身也一并保留。这类片段称为透传元素（passthrough element）。