Hugo 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 生成音頻播放器：

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

然後在 markup 中調用 shortcode：

{{< 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。

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。

在 shortcode templates 部分了解更多關於創建 shortcodes 的信息。

調用

Shortcode 調用涉及三個語法元素：標簽、參數和表示法。

標簽

一些 shortcodes 期望在開始和結束標簽之間有內容。例如，嵌入式 details shortcode 需要開始和結束標簽：

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

一些 shortcodes 不接受內容。例如，嵌入式 instagram shortcode 需要單個 positional 參數：

{{< instagram CxOWiQNP2MO >}}

一些 shortcodes 可選地接受內容。例如，你可以使用內容調用嵌入式 qr shortcode：

{{< qr >}}
https://www.hugodoc.com
{{< /qr >}}

或使用帶尾隨斜槓的自關閉語法將文本作為參數傳遞：

{{< qr text=https://www.hugodoc.com />}}

請參閱每個 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 可以使用兩種不同的表示法調用，通過它們的標簽分隔符區分。

Markdown 表示法

Hugo 在頁面內容由 Markdown 渲染器渲染之前處理 shortcode。這意味著，例如，Markdown-notation shortcode 內部的 Markdown 標題將在 Page 對象上調用 TableOfContents 方法時包含在內。

標准表示法

使用標准表示法，Hugo 單獨處理 shortcode，在 Markdown 渲染後將輸出合並到頁面內容中。這意味著，例如，標准表示法 shortcode 內部的 Markdown 標題將在 Page 對象上調用 TableOfContents 方法時排除。

舉例來說，使用此 shortcode 模板：

{{ .Inner }}

以及此 markdown：

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

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

Hugo 渲染此 HTML：

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

## Section 2

在上面，“Section 1” 將在調用 TableOfContents 方法時包含在內，而 “Section 2” 將不包含。

嵌套

Shortcodes（不包括 inline shortcodes）可以嵌套，創建父子關系。例如，gallery shortcode 可能包含幾個 image shortcodes：

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

shortcode templates 部分提供了詳細的解釋和示例。