Hugoのショートコードを理解する(入門)

Web開発
Page content

1.目的

Hugoにはショートコードという機能があります。ショートコードとは、マークダウンドキュメント内で使用できる関数のようなものであり、ショートコードを作っておくことで複雑なHTMLを簡単に出力することができます。

本ページでは、ショートコードの基礎的な意義や動作確認を含めてわかりやすく記載したいと思います。

2.参考

公式(英語)では詳細な説明がされています。基礎的な点を理解している場合は公式を参照した方がよいかもしれません。

3.具体例(簡単なサンプルで比較)

具体的な比較が無いとイメージしづらいと思うので、ここでは簡単なシナリオを元にショートコードの無い場合と、ある場合を比較してみます。

次の機能をシナリオとして、実際にショートコードを作成してみます。

・各記事の末尾に自ページの記事タイトルと記事URLを表示する。
・表示方法は、「このページは<記事タイトル>です。」とする
・<記事タイトル>の部分は当該記事へのリンクになっていることとする

ショートコードが無い場合

この場合は、content配下のマークダウンファイル内に手書きでURLを記載するしかありません。例えば以下のようなマークダウンをすべての記事に書くことになります。

このページは[記事タイトル](記事URL)です。

記事タイトルやURLは各ページでそれぞれ異なる内容になるので、想像しただけで面倒であることがわかります。

ショートコードがある場合

ショートコードを作成すると、すべての記事で単一の記載で済ませることができます。ここでは独自にmytitleandurlという名前でショートコードを作成しました。

今回作成したショートコードの場合は、下記の記述をすべての記事に書くだけで機能を実現することができます。(ショートコードの内容は後述します)

{{< mytitleandurl >}}

上記ショートコードを埋め込んだ記事をブラウザで開くと、以下のように表示されます。

ショートコード表示例1

それではショートコードの内容です。

Hugoのショートコードは一般的にlayouts/shortcodes配下に作成します。

今回のショートコードの内容は以下の通りです。シンプルな内容ですのでコピペでも動くはずです。私はviでファイル(mytitleandurl.html)を作成しました。

% vi layouts/shortcodes/mytitleandurl.html
このページは<a href="{{ .Page.RelPermalink }}">{{ .Page.Title }}</a>です。

ここで重要なポイントですが、ファイル名の.htmlを除いた部分がそのままショートコード名となります。ここではmytitleandurl.htmlがファイル名になるので、ショートコードはmytitleandurlとなります。

また、上記ショートコードではHugoに内蔵されている変数.Page.RelPermalinkと.Page.Titleを使って情報を取得&表示しています。

変数はいくつか用意されていますので、より詳しい変数については公式を参照してみてください。