まくまくHugo/Goノート
独自のショートコードを作成する
2017-09-29
独自のショートコードを作成すると、定型の HTML コードを記事内に簡単に埋め込めるようになります。

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

ショートコードは、/layouts/shortcodes/ ディレクトリ内に作成しておきます。 ファイル名から拡張子を除いたものが、ショートコード名となります。

layouts/shortcodes/myshortcode.html

This is my first short code.

記事の中から、下記のように呼び出すと、上記の内容がそこに展開されます。

content/page1.md

{{< myshortcode >}}

ショートコードにパラメータを渡す (.Get)

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

{{< myshortcode red 32px >}}

渡されたパラメータは、ショートコードの中から、{{ .Get インデックス }} で取得することができます。

layouts/shortcodes/myshortcode.html

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

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

{{< myshortcode color="red" size="32px" >}}

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

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

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

パラメータが渡されたかどうかで処理を分岐するには、.Get で取得した値を ifwith で評価すれば OK です。

{{ with .Get "class"}} class="{{.}}"{{ end }}

default 関数を使って、パラメータが指定されなかった場合のデフォルト値を用意しておくのもよいでしょう。

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

ショートコードにテキストデータを渡す (.Inner)

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

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

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

layouts/shortcodes/caution.html

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

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

{{% caution %}}
この**発射ボタン**を押さないでください。
{{% /caution %}}

テーマ用のショートコード

ショートコード用の HTML ファイルは、/layouts/shortcodes/ ディレクトリに配置することで、任意のコンテンツ内から利用できるようになります。 ショートコード用の HTML ファイルをテーマの一部(付属品)として提供したい場合は、下記のディレクトリに配置してください。

/themes/<THEME>/layouts/shortcodes/<SHORTCODE>.html

同じ名前のショートコードが /layouts/shortcodes/ ディレクトリにも存在する場合は、そちらが優先して使用されます。

2017-09-29