短代码
什么是短代码
Hugo 偏爱 Markdown，因为它具有简单的内容格式，但有时 Markdown 也力不从心。内容作者常常被迫在 Markdown 内容中添加原始 HTML（例如视频 <iframe> ）。我们认为这与 Markdown 语法简洁优雅的特性相矛盾。
Hugo 创建了 短代码 来规避这些限制。
短代码是内容文件中一个简单的代码片段，Hugo 将使用预定义的模板对其进行渲染。请注意，短代码在模板文件中不起作用。如果您需要短代码提供的这种即插即用功能，但在模板中使用，则很可能需要使用 局部模板 。
除了更简洁的 Markdown 之外，还可以随时更新短代码以反映新的类、技术或标准。在站点生成时，Hugo 短代码将轻松合并您的更改。您可以避免可能很复杂的查找和替换操作。
使用短代码
在您的内容文件中，可以通过调用 {{% shortcodename arguments %}} 来调用短代码。短代码参数用空格分隔，包含内部空格的参数必须用引号括起来。
短代码声明中的第一个词始终是短代码的名称。参数在名称之后。根据短代码的定义方式，参数可以是命名的、位置的或两者兼有，尽管您不能在一个调用中混合参数类型。命名参数的格式模仿 HTML，格式为 name="value" 。
某些短代码使用或需要闭合短代码。与 HTML 一样，开头和结尾的短代码（仅名称）匹配，结尾声明前面加一个斜杠。
以下是两个配对短代码的示例：
{{% mdshortcode %}}Stuff to `process` in the *center*.{{% /mdshortcode %}}
{{< highlight go >}} A bunch of code here {{< /highlight >}}
上面的示例使用了两种不同的分隔符，区别在于第一个示例使用 % 字符，第二个示例使用 <> 字符。
带有原始字符串参数的短代码
您可以使用原始字符串文字将多行作为参数传递给短代码：
{{< myshortcode `This is some <b>HTML</b>,
and a new line with a "quoted string".` >}}
使用 Markdown 的短代码
使用 % 作为最外层分隔符的短代码将在发送到内容渲染器时完全渲染。这意味着短代码的渲染输出可以成为页面目录、脚注等的一部分。
不使用 Markdown 的短代码
< 字符表示短代码的内部内容不需要进一步渲染。通常，不使用 Markdown 的短代码包含内部 HTML：
{{< myshortcode >}}<p>Hello <strong>World!</strong></p>{{< /myshortcode >}}
嵌套短代码
您可以通过创建利用 .Parent 方法的自定义模板，在其他短代码中调用短代码。 .Parent 允许您检查调用短代码的上下文。请参阅 短代码模板 。
嵌入式短代码
根据需要使用这些嵌入式短代码。
comment
New in v0.137.1使用 comment 短代码在 Markdown 中包含注释。Hugo 在渲染站点时会排除封装的文本。
示例用法：
{{% comment %}} TODO: 重写下面的段落。 {{% /comment %}}
虽然您可以使用 {{< >}} 表示法调用此短代码，但在计算上，使用上面所示的 {{% %}} 表示法调用它效率更高。
details
New in v0.140.0使用 details 短代码创建 details HTML 元素。例如：
{{< details summary="See the details" >}}
This is a **bold** word.
{{< /details >}}
Hugo 将其渲染为：
<details>
<summary>See the details</summary>
<p>This is a <strong>bold</strong> word.</p>
</details>
details 短代码接受以下命名参数：
- summary
- (
string) 从 Markdown 渲染到 HTML 的子summary元素的内容。默认为Details。 - open
- (
bool) 是否最初显示details元素的内容。默认为false。 - class
- (
string) 元素的class属性的值。 - name
- (
string) 元素的name属性的值。 - title
- (
string) 元素的title属性的值。
figure
figure 短代码可以使用以下命名参数：
- src
- 要显示的图像的 URL。
- link
- 如果需要将图像超链接，则为目标的 URL。
- target
- 如果设置了
link参数，则为 URL 的可选target属性。 - rel
- 如果设置了
link参数，则为 URL 的可选rel属性。 - alt
- 如果无法显示图像，则为图像的替代文本。
- title
- 图像标题。
- caption
- 图像标题。
caption值中的 Markdown 将被渲染。 - class
- HTML
figure标记的class属性。 - height
- 图像的
height属性。 - width
- 图像的
width属性。 - loading
- 图像的
loading属性。 - attr
- 图像署名文本。
attr值中的 Markdown 将被渲染。 - attrlink
- 如果需要将署名文本超链接，则为目标的 URL。
示例用法：
{{< figure src="elephant.jpg" title="An elephant at sunset" >}}
渲染结果：
<figure>
<img src="elephant.jpg">
<figcaption><h4>An elephant at sunset</h4></figcaption>
</figure>
gist
要显示具有此 URL 的 GitHub gist ：
https://gist.github.com/user/50a7482715eac222e230d1e64dd9a89b
在 Markdown 中包含此内容：
{{< gist user 50a7482715eac222e230d1e64dd9a89b >}}
这将按文件名以字母顺序显示 gist 中的所有文件。
要显示 gist 中的特定文件：
{{< gist user 23932424365401ffa5e9d9810102a477 list.html >}}
渲染结果：
highlight
要显示突出显示的代码示例：
{{< highlight go-html-template >}}
{{ range .Pages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
{{< /highlight >}}
渲染结果：
{{ range .Pages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}要指定一个或多个 突出显示选项 ，请包含一个用引号括起来的、逗号分隔的列表：
{{< highlight go-html-template "lineNos=inline, lineNoStart=42" >}}
{{ range .Pages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
{{< /highlight >}}
渲染结果：
42{{ range .Pages }}
43 <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
44{{ end }}要显示具有此 URL 的 Instagram 帖子：
https://www.instagram.com/p/CxOWiQNP2MO/
在 Markdown 中包含此内容：
{{< instagram CxOWiQNP2MO >}}
渲染结果：
param
param 短代码渲染页面前题字中的参数，并回退到同名站点参数。如果参数不存在，短代码将引发错误。
示例用法：
{{< param testparam >}}
通过链接访问嵌套值：
{{< param my.nested.param >}}
ref
ref 短代码返回给定页面引用的永久链接。
示例用法：
[Post 1]({{% ref "/posts/post-1" %}})
[Post 1]({{% ref "/posts/post-1.md" %}})
[Post 1]({{% ref "/posts/post-1#foo" %}})
[Post 1]({{% ref "/posts/post-1.md#foo" %}})
渲染结果：
<a href="http://example.org/posts/post-1/">Post 1</a>
<a href="http://example.org/posts/post-1/">Post 1</a>
<a href="http://example.org/posts/post-1/#foo">Post 1</a>
<a href="http://example.org/posts/post-1/#foo">Post 1</a>
relref
relref 短代码返回给定页面引用的永久链接。
示例用法：
[Post 1]({{% relref "/posts/post-1" %}})
[Post 1]({{% relref "/posts/post-1.md" %}})
[Post 1]({{% relref "/posts/post-1#foo" %}})
[Post 1]({{% relref "/posts/post-1.md#foo" %}})
渲染结果：
<a href="/posts/post-1/">Post 1</a>
<a href="/posts/post-1/">Post 1</a>
<a href="/posts/post-1/#foo">Post 1</a>
<a href="/posts/post-1/#foo">Post 1</a>
要显示具有此 URL 的 Twitter 帖子：
https://x.com/SanDiegoZoo/status/1453110110599868418
在 Markdown 中包含此内容：
{{< twitter user="SanDiegoZoo" id="1453110110599868418" >}}
渲染结果：
Owl bet you'll lose this staring contest 🦉 pic.twitter.com/eJh4f2zncC
— San Diego Zoo Wildlife Alliance (@sandiegozoo) October 26, 2021
vimeo
要显示具有此 URL 的 Vimeo 视频：
https://vimeo.com/channels/staffpicks/55073825
在 Markdown 中包含此内容：
{{< vimeo 55073825 >}}
渲染结果：
youtube
要显示具有此 URL 的 YouTube 视频：
https://www.youtube.com/watch?v=0RKpf3rK57I
在 Markdown 中包含此内容：
{{< youtube 0RKpf3rK57I >}}
渲染结果：
youtube 短代码接受以下命名参数：
- id
- (
string) 视频id。如果像上面示例中那样以位置参数提供id，则可选。 - allowFullScreen
- New in v0.125.0
- (
bool)<iframe>元素是否可以激活全屏模式。默认为true。 - autoplay
- New in v0.125.0
- (
bool) 是否自动播放视频。强制mute为true。默认为false。 - class
- (
string) 包装div元素的class属性。指定此属性时，将从iframe元素及其包装div元素中删除style属性。 - controls
- New in v0.125.0
- (
bool) 是否显示视频控件。默认为true。 - end
- New in v0.125.0
- (
int) 播放器应停止播放视频的时间（以视频开始时的秒数计）。 - loading
- New in v0.125.0
- (
string)iframe元素的加载属性，eager或lazy。默认为eager。 - loop
- New in v0.125.0
- (
bool) 是否无限重复视频。第一次播放后忽略start和end参数。默认为false。 - mute
- New in v0.125.0
- (
bool) 是否静音视频。当autoplay为true时始终为true。默认为false。 - start
- New in v0.125.0
- (
int) 播放器应开始播放视频的时间（以视频开始时的秒数计）。 - title
- (
string)iframe元素的title属性。默认为“YouTube 视频”。
使用上述部分参数的示例：
{{< youtube id=0RKpf3rK57I start=30 end=60 loading=lazy >}}
隐私配置
要了解如何配置您的 Hugo 站点以符合新的欧盟隐私法规，请参阅 隐私保护 。
创建自定义短代码
要了解有关创建自定义短代码的更多信息，请参阅 短代码模板文档 。