Hugo のショートコードで本文内に HTML スニペットを埋め込む

2020-01-25

記事の中に定型のコード（YouTube 動画表示用 HTML など）を埋め込みたいときは、Hugo のショートコード (Shortcode) の機能を使用すると便利です。

ショートコードの基本

Hugo は基本的にマークダウン形式で記事を記述していくのですが、マークダウンの表現力には限界があるので、ときには HTML を直接記述したくなることがあります。しかし、毎回同じような HTML を記述するのでは、マークダウン形式を使用する意味がなくなってしまいます。このような場合に、HTML 部分をショートコードとして外部ファイルに保存しておくと、記事の中に簡単にその HTML を埋め込めるようになります。

☝️ ワンポイントショートコードは記事（コンテンツファイル）の中から呼び出すことができますが、テンプレートファイルの中からは呼び出せないことに注意してください。テンプレートの中から同様のことを行いたい場合は、パーシャルテンプレートの仕組みを使用します。

Hugo には、いくつかの組み込みのショートコードが用意されています。例えば、下記は Youtube の動画や、Instagram の投稿を埋め込むためのショートコードの使い方の例です。

例: Youtube 動画を記事内に埋め込む

{{< youtube w7Ft2ymGmfc >}}
{{< youtube id="w7Ft2ymGmfc" autoplay="true" >}}

例: Instagram の投稿を記事内に埋め込む

{{< instagram BWNjjyYFxVx >}}

例: ツイートを記事内に埋め込む

{{< tweet 877500564405444608 >}}

ショートコードの呼び出し方

記事内からショートコードを呼び出すには、下記のような構文を使用します。

{{< shortcode-name param1 param2 >}}

名前付きのパラメータを使用する場合は、param1="value1" のように記述します。

{{< shortcode-name param1="value1" param2="value2" >}}

HTML タグのように、開始タグと終了タグで内部テキストを囲むこともできます (paired shortcode)。

{{< shortcode-name >}}
長めのテキストをショートコードへの入力として扱う場合は、このように開始タグと終了タグで囲む方式を使うとよいです。
この部分のテキストは、ショートコードの実装の中で .Inner という変数で参照できます。
{{< /shortcode-name >}}

内部テキストの中で Markdown 記法を使う場合は、{{< と >}} の代わりに、{{% と %}} でショートコード名を囲みます。

{{% shortcode-name %}}
内部テキストの中で __強調テキスト__ や `inline code` などの Markdown 記法を使うことができます。
{{% /shortcode-name %}}

参考: 独自のショートコードを作成する

2020-01-25