# 短代码
> 介绍 Hugo 内置与自定义短代码的机制、定界符、参数规则与模板位置。
- 本页规范地址：https://hugozh.cn/shortcodes/
- 最近更新：2026-10-02
- 站点：Hugo 中文文档（https://hugozh.cn/）· 社区维护的非官方中文翻译

## 本章页面
- [figure](https://hugozh.cn/shortcodes/figure/)：用 figure 短代码在内容中插入 HTML figure 元素与图注。（Markdown：https://hugozh.cn/shortcodes/figure/index.md）
- [highlight](https://hugozh.cn/shortcodes/highlight/)：用 highlight 短代码插入带语法高亮的代码片段，并给出全部选项。（Markdown：https://hugozh.cn/shortcodes/highlight/index.md）
- [ref](https://hugozh.cn/shortcodes/ref/)：用 ref 短代码插入指向指定页面的永久链接，并说明参数与报错处理。（Markdown：https://hugozh.cn/shortcodes/ref/index.md）
- [relref](https://hugozh.cn/shortcodes/relref/)：用 relref 短代码插入相对永久链接，并说明参数与报错处理。（Markdown：https://hugozh.cn/shortcodes/relref/index.md）
- [param](https://hugozh.cn/shortcodes/param/)：用 param 短代码把站点参数或前置元数据中的参数值写进内容。（Markdown：https://hugozh.cn/shortcodes/param/index.md）
- [details](https://hugozh.cn/shortcodes/details/)：用 details 短代码在正文中插入 HTML details 折叠元素。（Markdown：https://hugozh.cn/shortcodes/details/index.md）
- [qr](https://hugozh.cn/shortcodes/qr/)：用 qr 短代码把文本编码为二维码图片并插入正文。（Markdown：https://hugozh.cn/shortcodes/qr/index.md）
- [instagram](https://hugozh.cn/shortcodes/instagram/)：用 instagram 短代码在正文中嵌入 Instagram 帖子。（Markdown：https://hugozh.cn/shortcodes/instagram/index.md）
- [vimeo](https://hugozh.cn/shortcodes/vimeo/)：用 vimeo 短代码在正文中嵌入 Vimeo 视频。（Markdown：https://hugozh.cn/shortcodes/vimeo/index.md）
- [x](https://hugozh.cn/shortcodes/x/)：用 x 短代码在正文中嵌入 X 帖子。（Markdown：https://hugozh.cn/shortcodes/x/index.md）
- [youtube](https://hugozh.cn/shortcodes/youtube/)：用 youtube 短代码在正文中嵌入 YouTube 视频。（Markdown：https://hugozh.cn/shortcodes/youtube/index.md）

---
## 本节目的是什么

短代码（shortcode）是内容文件中可以调用的模板片段，用来把需要逻辑处理的片段插进正文，例如图片与图注、带高亮的代码、站内页面链接。本节的各页分别介绍 Hugo 内置短代码中较常用的几个：`figure`、`highlight`、`ref`、`relref` 与 `param`。

## 短代码从哪来

短代码分三类。内置短代码（embedded shortcode）随 Hugo 一同发布，无需任何文件即可调用；自定义短代码由站点作者编写模板；内联短代码把模板直接写在内容文件里，短代码名以 `.inline` 结尾。三类短代码的调用写法完全一致。

自定义模板放在 `layouts/_shortcodes/` 目录，文件名（去掉扩展名）就是短代码名。模板即普通模板，可以读取参数、访问页面与站点数据，也可以调用局部模板（partial）。

## 两种定界符

调用短代码时用一对定界符包裹短代码名，定界符决定了短代码展开与 Markdown 渲染的先后顺序：

| 写法 | 示例 | 处理时机 |
| --- | --- | --- |
| 标准写法 | `{{</* name */>}}` | 输出并入 Markdown 渲染结果，内部内容不被 Markdown 处理 |
| Markdown 写法 | `{{%/* name */%}}` | 内部内容先交给 Markdown 渲染，再交给模板 |

这一差别有实际后果：Markdown 写法下，内部内容里的标题会进入页面的目录（table of contents），标准写法下则原样输出。不带内部内容时用自闭合写法；成对短代码以相同标记闭合，写作 `{{</* /name */>}}`。

## 参数规则

参数分为命名参数与位置参数：命名参数写作 `key=value`，键名大小写敏感；位置参数按书写顺序传入。值里含空格时必须加引号，可接受的类型是字符串、整数、浮点数与布尔值。同一次调用中两类参数不得混用。在模板中通过 `.Get` 按序号或名称读取参数，用 `.IsNamedParams` 判断本次调用用的是哪一类，用 `.Params` 取得全部参数；成对短代码的内部内容由 `.Inner` 取得。

## 模板中可用的上下文

编写自定义或内联短代码模板时，可通过短代码上下文读取调用信息：`.Get` 按序号或名称读取参数，`.GetMatch` 按模式匹配参数名，`.Params` 给出全部参数，`.Inner` 与 `.InnerDeindent` 取得成对短代码的内部内容（后者去掉共有的前导缩进），`.IsNamedParams` 判断参数类型，`.Page` 是调用该短代码的页面，`.Parent` 是外层短代码，`.Name` 与 `.Ordinal` 是名称与调用序号，`.Position` 给出调用位置以便排查报错。除此之外，模板中同样能访问站点与页面数据、站点参数以及各类模板函数。

## 阅读顺序

先看 `figure` 与 `highlight` 了解最常调用的两个短代码，再看 `ref` 与 `relref` 了解站内链接，最后看 `param` 了解如何把参数值写进正文。需要从头了解短代码本身（内置、自定义与内联三类，以及模板中可用的上下文）的读者，可先阅读[短代码](/shortcodes/)；短代码负责在调用点插入片段，若要改变 Markdown 元素本身的渲染方式，请参阅[渲染钩子](/render-hooks/)。