在Hugo中使用短代码

什么是 Hugo 短代码？

短代码是基于 Go 模板语法的代码片段，存储在 Hugo 的 layouts/_shortcodes 目录中，可直接在 Markdown 中调用。可嵌入复杂内容（视频、图表、表单），无需在 Markdown 中写 HTML/JS

文件结构

核心目录配置

Hugo 会自动识别 layouts/_shortcodes 目录下的短代码（若不存在可手动创建）

命名规范

  • 短代码文件后缀为 .html（本质是 Go 模板文件）
  • 文件名（不含后缀）即为短代码名称（例：alert.html 对应 alert 短代码）
  • 子目录中的短代码，调用时需指定相对路径（例：layouts/_shortcodes/ui/alert.html 对应 ui/alert 短代码）

自定义短代码

方法快速查找

短代码通过 Hugo 内置方法获取参数、内容和页面上下文：

方法说明
Get "参数名"获取命名参数（例：{{ .Get "title" }} 对应调用时的 title="标题"）；用 {{ .Get 0 }} 获取第 1 个位置参数
Inner获取短代码开始标签与结束标签之间的内容（例：{{% alert %}}正文{{% /alert %}} 中的“正文”）
InnerDeindent与 Inner 功能一致，但会自动去除多余缩进（适合格式化文本，避免 HTML 结构错乱）
Params返回所有参数的集合（适合循环处理多个参数）
Page访问调用短代码的页面对象（例：{{ .Page.Title }} 获取当前页面标题）
RelRef/Ref生成内部页面的相对/绝对 URL（避免手动写链接导致的失效， Hugo 自动解析路径）

方法详细

  1. .Get

作用：获取短代码传入的参数值

  • 获取命名参数：{{ .Get "参数名" }}

  • 获取位置参数：{{ .Get 0 }}、{{ .Get 1 }}(从 0 开始)

go
1
2

{{ .Get "title" }}
{{ .Get 0 }}

用途：用来读取用户传入的参数，比如颜色、标题、链接

  1. .Inner

作用：获取短代码开始标签与结束标签之间的内容，保留原始缩进

适用场景：当使用闭合标签时

markdown
1
2
3

{{% myshortcode %}}
这里是内容
{{% /myshortcode %}}

.Inner 就会返回中间那一段“这里是内容”。

  1. .InnerDeindent

作用：和 .Inner 一样获取闭合标签之间的内容，但会自动去除多余缩进。

Markdown 里经常会缩进写内容，.InnerDeindent 能把这些缩进去掉，让输出 HTML 更干净，不会出现多余空格。

go
1

{{ .InnerDeindent | markdownify }}
  1. .IsNamedParams

作用：判断当前短代码调用是否使用了命名参数。

返回值：布尔值 true / false。

go
1
2
3
4
5

{{ if .IsNamedParams }}
  使用了命名参数
{{ else }}
  使用了位置参数
{{ end }}

用途：让短代码同时支持命名参数和位置参数，提高兼容性。

  1. .Name

作用：返回当前短代码的文件名（不含扩展名）。

例如短代码文件是 alert.html，则 .Name 返回 alert。

用途：动态生成类名、ID、日志信息等。

  1. .Ordinal

作用：返回当前短代码在父元素中的零基序号。

比如同一页面多次调用同一个短代码，序号会从 0 开始递增。

用途：给重复元素生成唯一 ID，例如 tab、collapse、accordion 等组件。

  1. .Page

作用：返回调用短代码的页面对象。

通过它你可以访问当前页面的所有信息：

go
1
2
3
4

{{ .Page.Title }}
{{ .Page.Permalink }}
{{ .Page.Date }}
{{ .Page.Params.tags }}

用途：在短代码里读取页面标题、日期、自定义 Front Matter 等

  1. .Params

作用：返回所有参数的集合（map）。

可以直接遍历：

go
1
2
3

{{ range $key, $value := .Params }}
  {{ $key }}: {{ $value }}
{{ end }}

用途：批量处理参数，或动态生成属性。

  1. .Parent

作用：在嵌套短代码中，获取父短代码的上下文

例如：

markdown
1
2
3

{{% parent %}}
  {{% child %}}
{{% /parent %}}

在 child 短代码里可以用：

go
1

{{ .Parent.Get "title" }}

用途：实现组件嵌套(tabs → tab、grid → item)

  1. .Position

作用：返回短代码被调用的文件名 + 行号位置

示例输出：

plaintext
1

post.md:12:1

用途：调试、错误提示

  1. .Ref

作用：根据页面路径生成绝对 URL

go
1

{{ .Ref "posts/hugo.md" }}

用途：生成完整链接，适合需要绝对路径的场景（如 SEO、Open Graph）

  1. .RelRef

作用：根据页面路径生成相对 URL。

go
1

{{ .RelRef "posts/hugo.md" }}

用途：最推荐的内部链接方式，不会因为域名变化而失效，Hugo 自动处理路径。

  1. .Scratch

作用：返回一个当前短代码范围内的“临时数据存储” 可以存值、改值、累加，只在当前短代码生命周期内有效

go
1
2
3

{{ .Scratch.Set "count" 1 }}
{{ .Scratch.Add "count" 1 }}
{{ .Scratch.Get "count" }} → 2

用途：在短代码里做计数、拼接字符串、临时缓存、传递数据等

  1. .Store

作用：和 .Scratch 功能完全一样，也是当前短代码范围内的临时存储 Hugo 文档里两者是同义词，用法一致

  1. .Site

作用：返回整个站点的全局对象。

go
1
2
3
4

{{ .Site.Title }}
{{ .Site.BaseURL }}
{{ .Site.Data }}
{{ .Site.Menus }}

用途：在短代码中读取全局配置、数据文件、菜单等