Shortcodes 短代码

Use embedded, custom, or inline shortcodes to insert elements such as videos, images, and social media embeds into your content.使用嵌入的、自定义的或内联的短代码，将视频、图像和社交媒体嵌入内容等元素插入到你的内容中。

Introduction 简介

A shortcode is a template invoked within markup, accepting any number of arguments. They can be used with any content format to insert elements such as videos, images, and social media embeds into your content.短代码是在标记中调用的模板，可接受任意数量的参数。它们可与任何内容格式配合使用，向内容中插入视频、图像和社交媒体嵌入内容等元素。

There are three types of shortcodes: embedded, custom, and inline.短代码有三种类型：嵌入式、自定义和内联式。

Embedded 嵌入的

Hugo’s embedded shortcodes are pre-defined templates within the application. Refer to each shortcode’s documentation for specific usage instructions and available arguments.Hugo 的嵌入式短代码是应用程序中预定义的模板。有关具体使用说明和可用参数，请参考每个短代码的文档。

Details 详情

Insert an HTML details element into your content using the details shortcode.使用details短代码在您的内容中插入一个HTML详情元素。

Figure 图

Insert an HTML figure element into your content using the figure shortcode.使用 figure 短代码在您的内容中插入一个 HTML figure 元素。

Gist 要点

Embed a GitHub Gist in your content using the gist shortcode.使用gist短代码在您的内容中嵌入GitHub Gist。

Highlight 高亮

Insert syntax-highlighted code into your content using the highlight shortcode.使用highlight短代码在您的内容中插入带语法高亮的代码。

Instagram

Embed an Instagram post in your content using the instagram shortcode.使用instagram短代码在你的内容中嵌入Instagram帖子。

Param 参数

Insert a parameter from front matter or site configuration into your content using the param shortcode.使用param短代码将前端内容或网站配置中的参数插入到你的内容中。

QR 二维码

Insert a QR code into your content using the qr shortcode.使用qr短代码在您的内容中插入二维码。

Ref 引用

Insert a permalink to the given page reference using the ref shortcode.使用ref短代码插入指向给定页面引用的永久链接。

Relref 雷雷夫

Insert a relative permalink to the given page reference using the relref shortcode.使用relref短代码插入指向给定页面引用的相对永久链接。

Vimeo 维imeo

Embed a Vimeo video in your content using the vimeo shortcode.使用vimeo短代码在您的内容中嵌入Vimeo视频。

X

Embed an X post in your content using the x shortcode.使用x短代码在您的内容中嵌入一条X帖子。

YouTube

Embed a YouTube video in your content using the youtube shortcode.使用youtube短代码在你的内容中嵌入YouTube视频。

Custom 自定义

Create custom shortcodes to simplify and standardize content creation. For example, the following shortcode template generates an audio player using a global resource:创建自定义短代码，以简化和标准化内容创作。例如，以下_短代码_模板使用全局资源生成音频播放器：

layouts/_shortcodes/audio.html

1
2
3

{{ with resources.Get (.Get "src") }}
  <audio controls preload="auto" src="{{ .RelPermalink }}"></audio>
{{ end }}

Then call the shortcode from within markup:然后在标记中调用短代码：

content/example.md

1

\{\{< audio src=/audio/test.mp3 >}}

Learn more about creating shortcodes in the shortcode templates section.了解更多关于在短代码模板部分创建短代码的信息。

Inline 内联

An inline shortcode is a shortcode template defined within content.内联短代码是在内容中定义的_短代码_模板。

Hugo’s security model is based on the premise that template and configuration authors are trusted, but content authors are not. This model enables generation of HTML output safe against code injection.Hugo 的安全模型基于这样一个前提：模板和配置的编写者是受信任的，但内容的编写者则不受信任。这种模型能够生成可防止代码注入的安全 HTML 输出。

To conform with this security model, creating shortcode templates within content is disabled by default. If you trust your content authors, you can enable this functionality in your site’s configuration:为了符合此安全模型，默认情况下禁止在内容中创建_短代码_模板。如果您信任您的内容作者，可以在网站的配置中启用此功能：

hugo. 雨果。

yamltomljson

1
2

[security]
  enableInlineShortcodes = true

For more information see configure security.有关更多信息，请参见配置安全性。

The following example demonstrates an inline shortcode, date.inline, that accepts a single positional argument: a date/time layout string.以下示例展示了一个内联短代码date.inline，它接受一个位置参数：一个日期/时间布局字符串。

content/example.md

1
2
3
4
5
6

Today is
\{\{< date.inline ":date_medium" >}}
  {{- now | time.Format (.Get 0) -}}
\{\{< /date.inline >}}.

Today is \{\{< date.inline ":date_full" />}}.

In the example above, the inline shortcode is executed twice: once upon definition and again when subsequently called. Hugo renders this to:在上面的示例中，内联短代码会执行两次：一次是在定义时，另一次是在后续调用时。Hugo 会将其渲染为：

1
2

<p>Today is Jan 30, 2025.</p>
<p>Today is Thursday, January 30, 2025</p>

Inline shortcodes process their inner content within the same context as regular shortcode templates, allowing you to use any available shortcode method.内联短代码在与常规短代码模板相同的上下文中处理其内部内容，允许您使用任何可用的短代码方法。

You cannot nest inline shortcodes. 你不能嵌套内联短代码。

Learn more about creating shortcodes in the shortcode templates section.了解更多关于在短代码模板部分创建短代码的信息。

Calling 调用

Shortcode calls involve three syntactical elements: tags, arguments, and notation.短代码调用包含三个语法元素：标签、参数和符号。

Tags 标签

Some shortcodes expect content between opening and closing tags. For example, the embedded details shortcode requires an opening and closing tag:一些短代码需要在开始标签和结束标签之间包含内容。例如，嵌入式的 details 短代码需要开始标签和结束标签：

1
2
3

\{\{< details summary="See the details" >}}
This is a **bold** word.
\{\{< /details >}}

Some shortcodes do not accept content. For example, the embedded instagram shortcode requires a single positional argument:有些短代码不接受内容。例如，嵌入的instagram短代码需要一个单一的_位置_参数：

1

\{\{< instagram CxOWiQNP2MO >}}

Some shortcodes optionally accept content. For example, you can call the embedded qr shortcode with content:一些短代码可以选择性地接受内容。例如，你可以使用内容调用嵌入的qr短代码：

1
2
3

\{\{< qr >}}
https://gohugo.io
\{\{< /qr >}}

Or use the self-closing syntax with a trailing slash to pass the text as an argument:或者使用带有尾部斜杠的自闭合语法，将文本作为参数传递：

1

\{\{< qr text=https://gohugo.io />}}

Refer to each shortcode’s documentation for specific usage instructions and available arguments.请参考每个短代码的文档，以获取具体的使用说明和可用参数。

Arguments 参数

Shortcode arguments can be either named or positional.短代码参数可以是_命名的_或_位置的_。

Named arguments are passed as case-sensitive key-value pairs, as seen in this example with the embedded figure shortcode. The src argument, for instance, is required.命名参数以区分大小写的键值对形式传递，如在嵌入了figure短代码的此示例中所见。例如，src参数是必需的。

1

\{\{< figure src=/images/kitten.jpg >}}

Positional arguments, on the other hand, are determined by their position. The embedded instagram shortcode, for example, expects the first argument to be the Instagram post ID.另一方面，位置参数由其位置决定。例如，嵌入的instagram短代码要求第一个参数是Instagram帖子ID。

1

\{\{< instagram CxOWiQNP2MO >}}

Shortcode arguments are space-delimited, and arguments with internal spaces must be quoted.短代码参数以空格分隔，内部包含空格的参数必须用引号括起来。

1

\{\{< figure src=/images/kitten.jpg alt="A white kitten" >}}

Shortcodes accept scalar arguments, one of string, integer, floating point, or boolean.短代码接受标量参数，类型可以是字符串、整数、浮点数或布尔值中的一种。

1

\{\{< my-shortcode name="John Smith" age=24 married=false >}}

You can optionally use multiple lines when providing several arguments to a shortcode for better readability:为了提高可读性，在向短代码提供多个参数时，你可以选择使用多行：

1
2
3
4
5
6

\{\{< figure
  src=/images/kitten.jpg
  alt="A white kitten"
  caption="This is a white kitten"
  loading=lazy
>}}

Use a raw string literal if you need to pass a multiline string:如果需要传递多行字符串，请使用原始字符串字面量：

1
2

\{\{< myshortcode `This is some <b>HTML</b>,
and a new line with a "quoted string".` >}}

Shortcodes can accept named arguments, positional arguments, or both, but you must use either named or positional arguments exclusively within a single shortcode call; mixing them is not allowed.短代码可以接受命名参数、位置参数，或两者皆可，但在单个短代码调用中，你必须只使用命名参数或位置参数中的一种，不允许混合使用。

Refer to each shortcode’s documentation for specific usage instructions and available arguments.请参考每个短代码的文档，以获取具体的使用说明和可用参数。

Notation 符号

Shortcodes can be called using two different notations, distinguished by their tag delimiters.短代码可以使用两种不同的表示法来调用，这两种表示法通过其标签分隔符来区分。

Markdown notation Markdown标记法

Hugo processes the shortcode before the page content is rendered by the Markdown renderer. This means, for instance, that Markdown headings inside a Markdown-notation shortcode will be included when invoking the TableOfContents method on the Page object.Hugo会在Markdown渲染器渲染页面内容之前处理短代码。这意味着，例如，当对Page对象调用TableOfContents方法时，Markdown标记短代码中的Markdown标题将会被包含在内。

Standard notation 标准表示法

With standard notation, Hugo processes the shortcode separately, merging the output into the page content after Markdown rendering. This means, for instance, that Markdown headings inside a standard-notation shortcode will be excluded when invoking the TableOfContents method on the Page object.使用标准标记法时，Hugo 会单独处理短代码，在 Markdown 渲染后将输出合并到页面内容中。这意味着，例如，当对 Page 对象调用 TableOfContents 方法时，标准标记法短代码内的 Markdown 标题会被排除在外。

By way of example, with this shortcode template:举个例子，使用这个_短代码_模板：

layouts/_shortcodes/foo.html

1

{{ .Inner }}

And this markdown: 而这段markdown：

content/example.md

1
2
3

\{\{% foo %}} ## Section 1 \{\{% /foo %}}

\{\{< foo >}} ## Section 2 \{\{< /foo >}}

Hugo renders this HTML: Hugo 会渲染此 HTML：

1
2
3

<h2 id="heading">Section 1</h2>

## Section 2

In the above, “Section 1” will be included when invoking the TableOfContents method, while “Section 2” will not.在上述内容中，调用TableOfContents方法时将包含“第1节”，而“第2节”则不会包含在内。

The shortcode author determines which notation to use. Consult each shortcode’s documentation for specific usage instructions and available arguments.短代码作者决定使用哪种符号。请查阅每个短代码的文档，以获取具体的使用说明和可用参数。

Nesting 嵌套

Shortcodes (excluding inline shortcodes) can be nested, creating parent-child relationships. For example, a gallery shortcode might contain several image shortcodes:短代码（不包括内联短代码）可以嵌套，形成父子关系。例如，一个图库短代码可能包含多个图像短代码：

content/example.md

1
2
3
4
5

\{\{< gallery class="content-gallery" >}}
  \{\{< image src="/images/a.jpg" >}}
  \{\{< image src="/images/b.jpg" >}}
  \{\{< image src="/images/c.jpg" >}}
\{\{< /gallery >}}

The shortcode templates section provides a detailed explanation and examples.短代码模板部分提供了详细的解释和示例

来源： https://gohugo.io/content-management/shortcodes/