转换函数 on Hugo 中文文档

transform.CanHighlight

Fri, 02 Oct 2026 00:00:00 +0800

{{ transform.CanHighlight "go" }} → true
{{ transform.CanHighlight "klingon" }} → false

transform.Emojify

Fri, 02 Oct 2026 00:00:00 +0800

可用的表情符号见 emoji 短代码清单。

emojify 函数可以在模板中调用，但默认不能直接用在内容文件里。要在内容文件中使用 emoji，请在项目配置中把 enableEmoji 设为 true；此后就可以把 emoji 简写直接写进内容文件：

transform.Highlight

Fri, 02 Oct 2026 00:00:00 +0800

transform.Highlight 函数使用 alecthomas/chroma 包，根据传入的代码、语言与选项生成带语法高亮的 HTML。

参数

CODE: （string）要高亮的代码。
LANG: （string）要高亮的代码的语言。该值大小写不敏感。可选；也可以用 OPTIONS 中的 type 键设置语言。（0.162.0 新增）
OPTIONS: （map 或 string）一个映射，或包在引号里的逗号分隔键值对。参见下文选项；可以为每个选项在项目配置中设置默认值。键名大小写不敏感。

示例

{{ $input := `fmt.Println("Hello World!")` }}
{{ transform.Highlight $input "go" }}

{{ $input := `console.log('Hello World!');` }}
{{ $lang := "js" }}
{{ transform.Highlight $input $lang "lineNos=table, style=api" }}

{{ $input := `echo "Hello World!"` }}
{{ $lang := "bash" }}
{{ $opts := dict "lineNos" "table" "style" "dracula" }}
{{ transform.Highlight $input $lang $opts }}

{{ $input := `print("Hello World!")` }}
{{ $opts := dict "type" "python" "style" "dracula" }}
{{ transform.Highlight $input $opts }}

选项

transform.Highlight 函数接受一个选项映射。

transform.HighlightCodeBlock

Fri, 02 Oct 2026 00:00:00 +0800

transform.HighlightCodeBlock 函数使用 alecthomas/chroma 包，为代码块渲染钩子（render hook）上下文中收到的代码生成带语法高亮的 HTML。该函数只在代码块渲染钩子内有意义。

参数

CONTEXT: 传入代码块渲染钩子的上下文。
OPTIONS: （map）键值对映射。参见下文选项。键名大小写不敏感。

返回值

transform.HighlightCodeBlock 返回一个 HighlightResult 对象，它有两个方法。

transform.HTMLEscape

Fri, 02 Oct 2026 00:00:00 +0800

transform.HTMLEscape 函数通过把五个特殊字符替换为 HTML 实体来转义它们：

& → &
< → <
> → >
' → '
" → "

例如：

{{ htmlEscape "Lilo & Stitch" }} → Lilo &amp; Stitch
{{ htmlEscape "7 > 6" }} → 7 &gt; 6

transform.HTMLToMarkdown

Fri, 02 Oct 2026 00:00:00 +0800

（0.151.0 新增）

transform.HTMLToMarkdown 函数借助 html-to-markdown Go 包把 HTML 转换为 Markdown。

用法

{{ .Content | transform.HTMLToMarkdown | safeHTML }}

插件

转换过程由以下 html-to-markdown 插件实现：

插件	说明
Base	实现基本的共享功能
CommonMark	按 CommonMark 规范实现 Markdown
Table	按 GitHub 风格 Markdown 规范实现表格

transform.HTMLUnescape

Fri, 02 Oct 2026 00:00:00 +0800

transform.HTMLUnescape 函数把 HTML 实体替换为对应的字符。

{{ htmlUnescape "Lilo &amp; Stitch" }} → Lilo & Stitch
{{ htmlUnescape "7 &gt; 6" }} → 7 > 6

在多数场景下，Go 的 html/template 包会转义特殊字符。要绕过这一行为，请把未转义的字符串交给 safe.HTML 函数。

transform.Markdownify

Fri, 02 Oct 2026 00:00:00 +0800

<h2>{{ .Title | markdownify }}</h2>

如果生成的 HTML 只有一个段落，Hugo 会去掉包裹的 p 标签，按上面示例的需要输出行内 HTML。

要为单个段落保留包裹的 p 标签，请使用 Page 对象上的 RenderString 方法，并把 display 选项设为 block。

transform.Plainify

Fri, 02 Oct 2026 00:00:00 +0800

{{ "<b>BatMan</b>" | plainify }} → BatMan

transform.PortableText

Fri, 02 Oct 2026 00:00:00 +0800

（0.145.0 新增）

用法

Portable Text 是一种 JSON 结构，用于表示 Sanity CMS 中的富文本内容。在 Hugo 中，该函数通常用在内容适配器里，由 Sanity 数据创建页面。

支持的类型：

block 与 span
image。注意目前对图像的处理比较基础：我们用 asset.url 作为链接，用 asset.altText 作为图像替代文本，用 asset.title 作为标题。如果需要更精细的控制，可以在图像渲染钩子中处理图像。
code（参见 code-input 插件）。代码会渲染为围栏代码块，其中提供的文件名会作为 Markdown 属性传入。

transform.Remarshal

Fri, 02 Oct 2026 00:00:00 +0800

用法

格式必须是 json、toml、yaml 或 xml 之一。如果输入是一串序列化数据，它必须是合法的 JSON、TOML、YAML 或 XML。

transform.ToMath

Fri, 02 Oct 2026 00:00:00 +0800

Hugo 使用 KaTeX 显示引擎的内嵌实例把数学标记渲染为 HTML。你不需要安装 KaTeX 显示引擎。

{{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" }}

Hugo 把结果缓存到磁盘上的 misc 文件缓存中，因此用相同参数多次调用该函数不会带来额外开销。

transform.Unmarshal

Fri, 02 Oct 2026 00:00:00 +0800

输入可以是字符串或资源。

选项

transform.Unmarshal 函数接受一个选项映射。

delimiter: （string）适用于 CSV 文件。使用的分隔符。默认 ,。
comment: （string）适用于 CSV 文件。CSV 中使用的注释字符。设置之后，以该注释字符开头且前面没有空白的行会被忽略。
format: （0.149.0 新增）; （string）输入的序列化格式，取 csv、json、org、toml、xml 或 yaml 之一。留空或不指定时，Hugo 从输入推断格式。对于资源，只有文件缺少扩展名，或需要覆盖推断出的格式时，才需要该选项。对于字符串，只有当格式存在歧义时才需要。
lazyQuotes: （bool）适用于 CSV 文件。是否允许在未加引号的字段中出现引号，或允许在加引号的字段中出现未成对的引号。默认 false。
targetType: （0.146.7 新增）; （string）适用于 CSV 文件。目标数据类型，取 slice 或 map。默认 slice。

解析字符串

{{ $string := `
title: Les Misérables
author: Victor Hugo
`}}

{{ $book := transform.Unmarshal $string }}
{{ $book.title }} → Les Misérables
{{ $book.author }} → Victor Hugo

解析资源

transform.Unmarshal 函数可用于全局资源、页面资源与远程资源。Hugo 会缓存结果，因此用同一个资源多次调用该函数不会带来额外开销。

transform.XMLEscape

Fri, 02 Oct 2026 00:00:00 +0800

transform.XMLEscape 函数先删除 XML 规范中定义的不允许的字符，再把结果中的以下字符替换为 HTML 实体来完成转义：

" → "
' → '
& → &
< → <
> → >
\t → 	
\n → 

\r →

例如：

{{ transform.XMLEscape "<p>abc</p>" }} → &lt;p&gt;abc&lt;/p&gt;

在由 Go 的 html/template 包渲染的模板中使用 transform.XMLEscape 时，请把该字符串声明为安全 HTML，以免二次转义。例如在 RSS 模板中：