Hugo ショートコード活用ガイド
Hugoのショートコードは、コンテンツ内に動画、画像、SNS埋め込みなどの要素を簡単に追加するためのテンプレート機能です。使い方を理解してコンテンツ作成を効率化しましょう。
ショートコードとは？
ショートコードは、マークアップ内で呼び出されるテンプレートです。任意の数の引数を受け付け、様々なコンテンツ形式で使用できます。主な目的は、複雑なHTML要素（ビデオ、画像、SNS埋め込みなど）の挿入を簡略化することです。
キーポイント: テンプレート呼び出し、引数利用可能、コンテンツへの要素埋め込みショートコードの種類
ショートコードには主に3つのタイプがあります。
1. 組み込み (Embedded) ショートコード
Hugoに標準で用意されている定義済みのショートコードです。利用可能な引数や使い方は各ドキュメントを参照してください。
主な組み込みショートコードの例:
利点: 設定不要ですぐに使える2. カスタム (Custom) ショートコード
開発者が独自に定義できるショートコードです。layouts/shortcodes/ ディレクトリにテンプレートファイルを作成します。
例: audio.html というカスタムショートコード (layouts/shortcodes/audio.html)
{{ with resources.Get (.Get "src") }}
<audio controls preload="auto" src="{{ .RelPermalink }}"></audio>
{{ end }}呼び出し方 (content/example.md):
{{< audio src="/audio/test.mp3" >}}3. インライン (Inline) ショートコード
コンテンツファイル内で直接定義するショートコードです。セキュリティ上の理由からデフォルトでは無効になっており、設定で有効化する必要があります (hugo.toml 等で security.enableInlineShortcodes = true)。
設定例 (hugo.toml):
[security]
enableInlineShortcodes = true例: 現在の日付を表示するインラインショートコード (content/example.md)
Today is
{{< date.inline ":date_medium" >}}
{{- now | time.Format (.Get 0) -}}
{{< /date.inline >}}.
Today is {{< date.inline ":date_full" />}}.出力結果例:
<p>Today is May 4, 2025.</p>
<p>Today is Sunday, May 4, 2025</p>ショートコードの呼び出し方
ショートコードの呼び出しは、主に「タグ」「引数」「記法」の3つの要素で構成されます。
タグ (Tags)
ショートコードは開始タグと終了タグで囲む形式 ({{< name >}}...{{< /name >}}) と、自己完結型 ({{< name ... />}}) があります。
- 内容を伴う場合:
detailsのように開始・終了タグが必要。 - 内容を伴わない場合:
instagramのように自己完結でも可。 - どちらも可能な場合:
qrは内容としてテキストを渡すか、text引数で渡せる。
例:
{{< details summary="詳細を見る" >}}内容はこちら{{< /details >}}
{{< instagram CxOWiQNP2MO >}}
{{< qr text="https://gohugo.io" />}}引数 (Arguments)
ショートコードに情報を渡す方法として、「名前付き引数」と「位置引数」があります。1回の呼び出しで両方を混在させることはできません。 引数内のスペースは引用符で囲む必要があります。
- 名前付き引数 (Named):
キー=値の形式。順序は問わない。(例:figureのsrc,alt) - 位置引数 (Positional): 引数の位置で意味が決まる。(例:
instagramの最初の引数は投稿ID)
例:
{{< 名前付き引数の例 >}}
{{< figure src="/images/cat.jpg" alt="可愛い子猫" >}}
{{< 位置引数の例 >}}
{{< instagram CxOWiQNP2MO >}}例 (Raw String Literal):
{{< myshortcode `複数行の
文字列引数` >}}記法 (Notation)
ショートコードの呼び出しには2つの記法があり、タグの区切り文字で区別されます。どちらを使用するかはショートコードの作者が決定します。
Markdown記法 ({{% ... %}})
例:
{{% foo %}} ## Section 1 {{% /foo %}}ショートコードの内容が、Markdownレンダラーによって処理される前に展開されます。
影響: ショートコード内のMarkdown見出し (## Section 1) は、ページの目次 (.TableOfContents) に含まれます。
標準記法 ({{< ... >}})
例:
{{< foo >}} ## Section 2 {{< /foo >}}ショートコードの内容が、Markdownレンダラーによる処理とは別に展開され、後でページにマージされます。
影響: ショートコード内のMarkdown見出し (## Section 2) は、ページの目次 (.TableOfContents) に含まれません。
ショートコードのネスト (Nesting)
インラインショートコードを除き、ショートコードは入れ子にすることができます。これにより、親子関係を持つ複雑な構造を作成できます。
例: ギャラリーショートコード内に画像ショートコードを入れる (content/example.md)
{{< gallery class="content-gallery" >}}
{{< image src="/images/a.jpg" >}}
{{< image src="/images/b.jpg" >}}
{{< image src="/c.jpg" >}}
{{< /gallery >}}