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

目次

はじめに

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

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

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

検証環境

  • OS : Win11
  • Hugo : v0.151.1

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

公式ページ によると、

A shortcode is a template invoked within markup, accepting any number of arguments. They can be used with any content format to insert elements such as videos, images, and social media embeds into your content.

There are three types of shortcodes: embedded, custom, and inline.

(Goole翻訳)

ショートコードはマークアップ内で呼び出されるテンプレートで、任意の数の引数を受け入れることができます。あらゆるコンテンツ形式で使用でき、動画、画像、ソーシャルメディアの埋め込みなどの要素をコンテンツに挿入できます。

ショートコードには、埋め込み、カスタム、インラインの 3 種類があります。

うん、よくわからんですね（笑)。
「埋め込み用テンプレート」って感じでしょうか。

情報はどこにあるの?

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

どうやって使うの？

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

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

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

  1. /layouts/_shortcodes/<SHORTCODE>.html
  2. /themes/<THEME>/layouts/_shortcodes/<SHORTCODE>.html

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

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

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

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

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

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

[security]
  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 >}}

おわりに

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