こんにちは、tamaoki (@t0shiya) です。
今回は、静的サイトジェネレータ Hugo の shortcodes について。
Hugo はコンテンツの記述にMarkdown記法を用いますが、Markdown記法はシンプルで覚えやすい反面、対応していない事項が多数あります。
例えば、コンテンツにスタイルを適用したりビデオを埋め込んだりしたい場合はHTMLを直接書かなければいけません。
それらを回避するために Hugo では shortcodes という仕組みが用意されています。
使い方
shortcode とは簡単に言うとコンテンツファイルの中で使用できるスニペットです。
※テンプレートファイルの中には記述できませんので注意してください。
使い方は簡単で、コンテンツ内に以下のようなタグを記述します。
{{% name parameters %}}
一つ目の単語が shortcode の名前で、それにパラメータが続きます。パラメータはスペース区切りで複数指定でき、スペースを含むパラメータはダブルクオートで括ります。 パラメータは name=“value” という形式で名前つきで指定することもできます。
また、HTML と同じように終了タグが必要なものがあります。その場合は、以下のように記述します。
{{% name parameters %}} shortcode's **inner** content {{% /name %}}
上の例は shortcode のタグに % を使っていましたが < > を使用する場合もあります。
{{< name parameters >}} shortcode's <strong>inner<strong> content {{< /name >}}
% と < > では、タグの間のコンテンツの扱いが異なります。
% はタグ間のコンテンツをMarkdown変換しますが、< > は変換せずそのままHTMLに出力されます。
作り方
shortcode は、layouts/shortcodes フォルダ内にテンプレートを配置します。
テンプレートのファイル名が shortcode の名前になります。
パラメータの取得
shortcode に渡されたパラメータを取得する方法は二つあります。
名前付きでパラメータを指定した場合は、テンプレート中から以下のように取得できます。
{{ .Get "parameter_name" }}
パラメータが名前つきでない場合は、ポジションを指定します。0 が先頭パラメータのポジションです。
{{ .Get 0 }}
変数
開始タグと終了タグの間に記述した部分は .Inner 変数に格納されます。
.Inner を使用している shortcode の終了タグを省略する場合は以下のように記述してください。
{{< name parameters />}}
また、shortcode を記述したページには .Page 変数を介してアクセスできます。
{{ .Page.Title }}
使用例
例1. baseurl
簡単な例として、コンテンツ内にサイトの BaseURL を埋め込む shortcode をご紹介します。
layouts/shortcodes/baseurl.html
{{ .Page.Site.BaseURL }}
コンテンツ内で {{< baseurl >}} と記述すると、当サイトでしたらHTMLに http://staff.feedtailor.jp/ と出力されます。
例2. div
もう少しだけ複雑な例として style 属性を指定できる div タグの shortcode を挙げます。
layouts/shortcodes/div.html
<div{{ with .Get "style" }} style="{{ . | safeCSS }}"{{ end }}>{{ .Inner }}</div>
コンテンツには以下のように記述します。
{{< div style="color: red;" >}}red{{< /div >}}
実際にこのエントリに埋め込んでみたところ、
が出力されています。
このように shortcode を定義すると、コンテンツに複雑なHTMLを配置したり、繰り返し記述する定型文を簡単に埋め込むことができるようになります。
Hugo に最初から組み込まれている便利な shortcodes もありますのでぜひ活用してください。
http://gohugo.io/extras/shortcodes/
feedtailor では、静的サイトジェネレータの利用に限らず、ウェブサイト静的化の御相談を承っておりますのでお気軽にお問い合わせください。