Hugo で独自のショートコードを作成する

2017-09-29

Hugo で独自のショートコードを作成すると、定型の HTML コードを記事内に簡単に埋め込めるようになります。

ショートコード作成の基本

ショートコードは、layouts/shortcodes ディレクトリ内に .html 拡張子のファイルとして作成します。

layouts/shortcodes/my-shortcode.html

This is my first short code.

ファイル名から拡張子を除いたものが、ショートコード名となります。上記の例の場合、my-shortcode というショートコードを作成したことになります。記事（Markdown ファイル）の中から、下記のように呼び出すと、上記の内容がそこに展開されます。

content/page1.md

---
title: "ページタイトル"
---

{{< my-shortcode >}}

ショートコード呼び出し時に、パラメータを渡すことができます。下記の例では、２つのパラメータ red、32px を渡しています。

{{< my-shortcode red 32px >}}

渡されたパラメータは、ショートコードの中で {{ .Get インデックス番号 }} のように参照することができます。

layouts/shortcodes/my-shortcode.html

<div style="color:{{ .Get 0 }}; font-size:{{ .Get 1 }};">
  This is my first short code.
</div>

上記の例では、参照するパラメータをインデックス番号 (0, 1, 2, …) で指定していますが、2 つ以上のパラメータを持つショートコードを作成するときは、名前付きパラメータ の仕組みを使うと分かりやすくなります。

{{< my-shortcode color="red" size="32px" >}}

名前付きパラメータとして渡された値を参照するには、{{ .Get "パラメータ名" }} のように、インデックス番号の代わりにその名前を引用符で囲んで指定します。

<div style="color:{{ .Get `color` }}; font-size:{{ .Get `size` }};">
  This is my first short code.
</div>

上記のように HTML 要素の属性値の中で .Get のパラメータ名を記述するときは、ダブルクォーテーション (") の代わりにバッククォート (`) で囲むと、引用符の対応がわかりやすくなります。

パラメータが渡されたかどうかで処理を分岐するには、.Get で取得した値を if や with で評価します。次の例では、ショートコードに class パラメータが渡されたときに、span 要素の class 属性の値として出力しています。

<span{{ with .Get "class"}} class="{{.}}"{{ end }}>{{ .Inner }}</span>

default 関数を組み合わせて使うと、パラメータが指定されなかった場合のデフォルト値を用意しておくことができます。以下のいずれの書き方も同様に振る舞いますが、1 つ目の書き方が直感的かと思います。

width パラメータのデフォルト値を auto にする

{{ $width := .Get "width" | default "auto" }}
{{ $width := default "auto" (.Get "width") }}
{{ $width := or (.Get "width") "auto" }}

ショートコードの開始タグと終了タグで任意のテキスト（内部テキスト）を囲むと、ショートコードのテンプレート内からそのテキストを参照することができます。下記は、caution という独自ショートコードにテキストを渡す例です。

content/page1.md

---
title: "ページタイトル"
---

{{< caution >}}
決して、この発射ボタンを押さないでください。
{{< /caution >}}

開始タグと終了タグで囲まれた内部テキストは、ショートコードの中から {{ .Inner }} で参照することができます。

layouts/shortcodes/caution.html

<div style="color:red;">
  {{ .Inner }}
</div>

内部テキストを最終的に Markdown プロセッサで処理してもらいたい場合は、下記のように % を使用した呼び出し方をする必要があります。

---
title: "ページタイトル"
---

{{% caution %}}
決して、この __発射ボタン__ を押さないでください。
{{% /caution %}}

テーマの付属品として配布されるショートコードは、次のようなパスに配置します。

同じ名前のショートコードが、現在の Hugo プロジェクト自身のショートコードディレクトリ (layouts/shortcodes) に存在する場合は、そちらが優先して使用されます。

2017-09-29