Hugo Shortcodes

使用嵌入式、自定义或内联 shortcodes 将视频、图像和社交媒体嵌入等元素插入到内容中。

介绍

shortcode（短代码）是在标记内调用�?template（模板），接受任意数量的 arguments（参数）。它们可以与任何 content format（内容格式）一起使用，将视频、图像和社交媒体嵌入等元素插入到您的内容中�

有三种类型的 shortcodes：嵌入式、自定义和内联。

嵌入式

Hugo 的嵌入式 shortcodes 是应用程序中预定义的模板。请参阅每个 shortcode 的文档以获取具体的使用说明和可用参数。

Details: 使用 details 短代码在你的内容中插入 HTML details 元素。
Figure: 使用 figure 短代码在你的内容中插入 HTML figure 元素。
Gist: 使用 gist 短代码在你的内容中嵌入 GitHub Gist。
Highlight: 使用 highlight 短代码在你的内容中插入语法高亮代码。
Instagram: 使用 instagram 短代码在你的内容中嵌入 Instagram 帖子。
Param: 使用 param 短代码将参数从 front matter 或站点配置插入到你的内容中。
QR: 使用 qr 短代码在你的内容中插入 QR 码。
Ref: 使用 ref 短代码插入给定页面引用的永久链接。
Relref: 使用 relref 短代码插入给定页面引用的相对永久链接。
Vimeo: 使用 vimeo 短代码在你的内容中嵌入 Vimeo 视频。
X: 使用 x 短代码在你的内容中嵌入 X 帖子。
YouTube: 使用 youtube 短代码在你的内容中嵌入 YouTube 视频。

自定义

创建自定义 shortcodes 以简化和标准化内容创建。例如，以下 shortcode 模板使用 global resource 生成音频播放器：

layouts/_shortcodes/audio.html

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

然后在 markup 中调用 shortcode：

content/example.md

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

在 shortcode templates 部分了解更多关于创建 shortcodes 的信息。

内联

内联 shortcode 是在内容中定义的 shortcode 模板。

Hugo 的安全模型基于模板和配置作者是受信任的，但内容作者不受信任的前提。此模型支持生成对代码注入安全的 HTML 输出。

为了符合此安全模型，默认情况下在内容中创建 shortcode 模板被禁用。如果你信任内容作者，可以在站点配置中启用此功能：

security:
  enableInlineShortcodes: true

[security]
  enableInlineShortcodes = true

{
   "security": {
      "enableInlineShortcodes": true
   }
}

有关更多信息，请参阅 configure security。

以下示例演示了一个内联 shortcode date.inline，它接受单个位置参数：日期/时间 layout string。

content/example.md

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

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

在上面的示例中，内联 shortcode 执行两次：一次在定义时，另一次在随后调用时。Hugo 将其渲染为：

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

内联 shortcodes 在与常规 shortcode 模板相同的上下文中处理其内部内容，允许你使用任何可用的 shortcode method。

你不能 nest 内联 shortcodes。

在 shortcode templates 部分了解更多关于创建 shortcodes 的信息。

调用

Shortcode 调用涉及三个语法元素：标签、参数和表示法。

参数

Shortcode 参数可以是 named 或 positional。

命名参数作为区分大小写的键值对传递，如此示例中使用嵌入式 figure shortcode。例如，src 参数是必需的。

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

另一方面，位置参数由其位置确定。例如，嵌入式 instagram shortcode 期望第一个参数是 Instagram 帖子 ID。

{{< instagram CxOWiQNP2MO >}}

Shortcode 参数以空格分隔，包含内部空格的参数必须加引号。

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

Shortcodes 接受 scalar 参数，即 string、integer、floating point 或 boolean 之一。

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

当向 shortcode 提供多个参数以提高可读性时，你可以选择使用多行：

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

如果你需要传递多行字符串，使用 raw string literal：

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

Shortcodes 可以接受命名参数、位置参数或两者，但你必须在单个 shortcode 调用中专门使用命名或位置参数；不允许混合使用。

请参阅每个 shortcode 的文档以获取具体的使用说明和可用参数。

表示法

Shortcodes 可以使用两种不同的表示法调用，通过它们的标签分隔符区分。

Notation	Example
Markdown	`{{% foo %}} ## Section 1 {{% /foo %}}`
Standard	`{{< foo >}} ## Section 2 {{< /foo >}}`

Markdown 表示法

Hugo 在页面内容由 Markdown 渲染器渲染之前处理 shortcode。这意味着，例如，Markdown-notation shortcode 内部的 Markdown 标题将在 Page 对象上调用 TableOfContents 方法时包含在内。

标准表示法

使用标准表示法，Hugo 单独处理 shortcode，在 Markdown 渲染后将输出合并到页面内容中。这意味着，例如，标准表示法 shortcode 内部的 Markdown 标题将在 Page 对象上调用 TableOfContents 方法时排除。

举例来说，使用此 shortcode 模板：

layouts/_shortcodes/foo.html

{{ .Inner }}

以及此 markdown：

content/example.md

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

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

Hugo 渲染此 HTML：

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

## Section 2

在上面，“Section 1” 将在调用 TableOfContents 方法时包含在内，而 “Section 2” 将不包含。

Shortcode 作者决定使用哪种表示法。请咨询每个 shortcode 的文档以获取具体的使用说明和可用参数。

嵌套

Shortcodes（不包括 inline shortcodes）可以嵌套，创建父子关系。例如，gallery shortcode 可能包含几个 image shortcodes：

content/example.md

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

shortcode templates 部分提供了详细的解释和示例。

Last updated: January 1, 0001

Improve this page