CONTENT MANAGEMENT

Shortcodes

什麼是短代碼

Hugo 喜歡 Markdown，因為它簡單的內容格式，但有時候 Markdown 無法完全滿足需求。通常，內容創作者不得不將原始 HTML（例如，視頻的 <iframe>）添加到 Markdown 內容中。我們認為這會違背 Markdown 語法的簡單美。

Hugo 創建了 短代碼 來繞過這些限制。

短代碼是一個簡單的片段，位於內容檔案中，Hugo 會使用預定義模板來渲染它。請注意，短代碼無法在模板文件中使用。如果您需要短代碼提供的那種即插即用的功能，但在模板中，您很可能需要使用 部分模板。

除了讓 Markdown 更加乾淨外，短代碼還可以隨時更新，以反映新的類別、技術或標準。在網站生成時，Hugo 的短代碼會輕鬆合併您的更改，避免了可能麻煩的搜索和替換操作。

使用短代碼

在您的內容檔案中，可以透過 {{% shortcodename arguments %}} 來呼叫短代碼。短代碼的參數是由空格分隔的，含有內部空格的參數必須加上引號。

短代碼宣告中的第一個字是短代碼的名稱，參數跟隨在名稱之後。根據短代碼的定義，參數可以是命名的、位置的或兩者，但無法在單次呼叫中混合不同類型的參數。命名參數的格式模仿 HTML，即 name="value"。

一些短代碼需要或要求使用閉合的短代碼。就像 HTML 一樣，開啟和閉合的短代碼必須匹配（只有名稱），並且閉合宣告前面會加上斜線。

以下是兩個配對短代碼的範例：

{{% mdshortcode %}}處理中的東西 `center`。{{% /mdshortcode %}}

{{< highlight go >}} 這裡有一堆代碼 {{< /highlight >}}

上述範例使用了兩種不同的定界符，第一種使用 % 字符，第二種使用 <> 字符。

帶有原始字串參數的短代碼

您可以使用原始字串字面量來傳遞多行參數給短代碼：

{{<  myshortcode `這是一些 <b>HTML</b>， 
還有一個帶有 "引號字串" 的新行。` >}}

帶有 Markdown 的短代碼

使用 % 作為外圍定界符的短代碼會在傳送至內容渲染器時完全渲染。這意味著短代碼的渲染輸出可以成為頁面的目錄、註解等的一部分。

不帶 Markdown 的短代碼

< 字符表示短代碼的內部內容 不需要 進一步渲染。通常，這些不帶 Markdown 的短代碼包含內部 HTML：

{{< myshortcode >}}<p>你好 <strong>世界！</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="查看細節" >}}
這是一個 **粗體** 字。
{{< /details >}}

Hugo 會將其渲染為：

<details>
  <summary>查看細節</summary>
  <p>這是一個 <strong>粗體</strong> 字。</p>
</details>

details 短代碼接受以下命名參數：

summary
(string) 子 summary 元素的內容，從 Markdown 渲染為 HTML。預設為 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="日落中的大象" >}}

渲染結果：

<figure>
  <img src="elephant.jpg">
  <figcaption><h4>日落中的大象</h4></figcaption>
</figure>

gist

要顯示 GitHub 上的 gist，使用此 URL：

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 }}

instagram

要顯示 Instagram 帖子，使用此 URL：

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>

twitter

要顯示 Twitter 帖子，使用此 URL：

https://x.com/SanDiegoZoo/status/1453110110599868418

在您的 Markdown 中包含：

{{< twitter user="SanDiegoZoo" id="1453110110599868418" >}}

渲染結果：

vimeo

要顯示 Vimeo 視頻，使用此 URL：

https://vimeo.com/channels/staffpicks/55073825

在您的 Markdown 中包含：

{{< vimeo 55073825 >}}

渲染結果：

youtube

要顯示 YouTube 視頻，使用此 URL：

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 元素的 loading 屬性，可以是 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 video”。

使用範例，包含上述一些參數：

{{< youtube id=0RKpf3rK57I start=30 end=60 loading=lazy >}}

隱私配置

要了解如何配置您的 Hugo 站點以符合新的歐盟隱私法規，請參見 隱私保護。

創建自定義短代碼

要了解如何創建自定義短代碼，請參見 短代碼模板文檔。

延伸閱讀

Term templates Hugo 官方技術文件