Hugoショートコードの使い方(基礎編)

2024年4月16日

はじめに

Hugoでサイトを作っていると、Markdownで対応できないことがでてきます。そこでHugoには「ショートコード」というしくみが用意されています。

しかしなかなか思い通りの表示をしてもらえず、ネットにある情報をコピペで使用するだけになっていました。

これではイカンので、自分の勉強も兼ねて使い方の基本やハマったところをまとめておきます。

検証環境

OS : Win10 WSL(Ubuntu22.04)
Hugo : V0.111-3

ショートコード(ShortCode)ってなに?

公式ページによると、

Shortcodes are a means to consolidate templating into small, reusable snippets that you can embed directly inside your content.

(Goole翻訳)

ショートコードは、コンテンツ内に直接埋め込むことができる小さな再利用可能なスニペットにテンプレートを統合する手段です。

うん、よくわからんですね（笑)。
「用意しておいたHTML文を、いい感じに整形して挿入できる」って感じでしょうか。

情報はどこにあるの?

結局公式が一番情報が多く、最新です。英語ですがGoogle翻訳等を利用して読みましょう。

どうやって使うの？

ショートコードの実態はhtmlファイルです。htmlファイルにhtmlタグではなく、独自の記号({{/*< … >*/}})を使って記載します。hugoでビルドする際に、この部分がhtmlに変換されます。

1. 「ショートコード名.html」のファイルを準備

ファイルは以下の順番で検索されます。

/layouts/shortcodes/.html
/themes//layouts/shortcodes/.html

1.に置けば問題ないと思います。

2. markdownファイルから呼び出す

{{< ショートコード名 >}}または{{% ショートコード名 %}}で呼び出します。("< >“と”% %“の違いはこちら )

インラインショートコードを有効にする

上記のようにhtmlファイルを用意するのは、テスト中だと意外と面倒なものです。 .mdファイル内にショートコード定義を埋め込む「インラインショートコード」があるので有効にしておきます(デフォルトでfalse)。

config.tomlに以下の行を追加します。

enableInlineShortcodes = true

markdownファイルに以下のように書き込むと、

{{< test.inline >}}{{ now }}{{< /test.inline >}}

このように出力されます。

2023-04-01 21:17:52.536927307 +0900 JST m=+0.139802547

一度書き込めば、そのファイル内では{{< test.inline />}}で呼び出し可能です。

インラインショートコードの注意点

{{< test.inline >}} の「.inline」は必須です。ないと定義済みショートコードと認識されてエラーとなります(定義がされていない)。「test」部分は任意の名前を指定できます。
再呼び出しの際、末尾にスラッシュ(self-closing syntax )が必要です。忘れると「inline shortcodes do not support nesting 」エラーが出ます。

ショートコード関係でハマったところ

勉強中にハマったポイントです。というか、まだハマり続けているので、ほんの一部です。解決できたら追加していきたいと思います。

{{< >}}と{{% %}} の違いは？

一番最初につまずいたポイントです。

<> : HTMLレンダリング可、MARKDOWN不可
%% : HTMLレンダリング不可、MARKDOWN可

例として、下記のようなショートコードを準備します。

markdown : **太字**
html : <b>太字</b>

このコードを読み込むと以下のようにhtml出力されます。

	{{< test >}}	{{% test %}}
markdown:	太字	<b>太字</b>
html:	<b>太字</b>	<!– raw HTML omitted –>

「<>」ではマークダウン記号がそのまま出力されてしまいます。「%%」ではHTMLタグが消されるだけでなく、内容まで消されてしまうため、注意が必要です。

「%%」でHTMLを出力するには、config.tomlに以下の内容を追加します。

[markup.goldmark.renderer]
unsafe= true #HTML直書きの許可

markdown,htmlともにhtmlタグに変換されます。

	{{% test %}}
markdown:	<b>太字</b>
html:	<b>太字</b>

ショートコードの記号を記事中に表示するには？

ショートコードの呼び出し記号 {{< >}} や {{% %}} は記事中ではショートコードとして認識されてしまいます。カッコの中身に /* */ を書きことでページに表示することができます。

markdownファイル

{{</* sample-shortcode */>}}

画面表示

{{< sample-shortcode >}}

おわりに

まだわからないところが多くて、やっと原理的なところが理解できた程度です。今後は具体例も紹介していければと思います。