短代码

本节目的是什么

短代码（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 了解如何把参数值写进正文。需要从头了解短代码本身（内置、自定义与内联三类，以及模板中可用的上下文）的读者，可先阅读短代码；短代码负责在调用点插入片段，若要改变 Markdown 元素本身的渲染方式，请参阅渲染钩子。