Shortcodes で HTML コードを埋め込む
今回は Shortcodes の話。
たとえば記事の中に YouTube の動画や SlideShare の HTML コードを埋め込みたいとする。 Hugo では段落単位に HTML コードを記述するとそのまま出力してくれるけど，頻繁に使うコードはテンプレート化して再利用したいだろう。 こういうときは Shortcodes の機能を使うと便利だ。
Shortcodes の使い方
Shortcodes は partial template の一種だけど，テンプレートの中に埋め込むのではなく，記事（markdown）ファイルに埋め込むことができる。
指定した範囲を加工する
書式は以下のとおりである。
{{< shortcodename >}} ... {{< /shortcodename >}}
Shortcodes の実体は layouts/shortcodes フォルダに shortcodename.hml などとコード名をそのままファイル名にしてで配置する。
たとえば layouts/shortcodes/fig-quote.html というファイルを作成し，以下のコードを書く。
{{ with .Get "lang" }}<figure lang="{{ . }}">{{ else }}<figure>{{ end }}
<blockquote>{{ .Inner }}</blockquote>
{{ if .Get "title"}}<figcaption>via <q>{{ with .Get "link"}}<a href="{{.}}">{{ end }}{{ .Get "title" }}{{ with .Get "link"}}</a>{{ end }}</q></figcaption>{{ end }}
</figure>
これを使って
{{< fig-quote title="Compatible Licenses - Creative Commons" link="https://creativecommons.org/compatiblelicenses" lang="en" >}}
<q>The <a href="https://www.gnu.org/copyleft/gpl.html">GNU General Public License version 3 </a> was declared a <q>BY-SA–Compatible License</q> for version 4.0 on 8 October 2015.
Note that compatibility with the GPLv3 is one-way only, which means you may license your contributions to adaptations of BY-SA 4.0 materials under GPLv3, but you may not license your contributions to adaptations of GPLv3 projects under BY-SA 4.0.
Other <a href="https://wiki.creativecommons.org/wiki/ShareAlike_compatibility:_GPLv3#Considerations_for_adapters_applying_the_GPLv3" target="_blank">special considerations</a> apply.
See the full <a href="https://wiki.creativecommons.org/wiki/ShareAlike_compatibility:_GPLv3">analysis</a> and <a href="https://wiki.creativecommons.org/wiki/ShareAlike_compatibility_analysis:_GPL">comparison</a> for more information.</q>
{{< /fig-quote >}}
このように記述すると，以下のように展開される。
<figure lang="en">
<blockquote>
<q>The <a href="https://www.gnu.org/copyleft/gpl.html">GNU General Public License version 3 </a> was declared a <q>BY-SA–Compatible License</q> for version 4.0 on 8 October 2015.
Note that compatibility with the GPLv3 is one-way only, which means you may license your contributions to adaptations of BY-SA 4.0 materials under GPLv3, but you may not license your contributions to adaptations of GPLv3 projects under BY-SA 4.0.
Other <a href="https://wiki.creativecommons.org/wiki/ShareAlike_compatibility:_GPLv3#Considerations_for_adapters_applying_the_GPLv3" target="_blank">special considerations</a> apply.
See the full <a href="https://wiki.creativecommons.org/wiki/ShareAlike_compatibility:_GPLv3">analysis</a> and <a href="https://wiki.creativecommons.org/wiki/ShareAlike_compatibility_analysis:_GPL">comparison</a> for more information.</q>
</blockquote>
<figcaption>via <q><a href="https://creativecommons.org/compatiblelicenses">Compatible Licenses - Creative Commons</a></q></figcaption>
</figure>
The GNU General Public License version 3 was declared aBY-SA–Compatible Licensefor version 4.0 on 8 October 2015. Note that compatibility with the GPLv3 is one-way only, which means you may license your contributions to adaptations of BY-SA 4.0 materials under GPLv3, but you may not license your contributions to adaptations of GPLv3 projects under BY-SA 4.0. Other special considerations apply. See the full analysis and comparison for more information.
{{< fig-quote >}} ... {{< /fig-quote >}} で囲まれている部分が .Inner 変数に格納され展開されているのがお分かりだろうか。
Shortcodes では .Inner 変数以外に任意のパラメータを持たせることができる。
上の例で言うなら lang, title, link が {{< fig-quote >}} に対するパラメータである。
名前を持たないパラメータでも有効である。
ここではルビ（ruby）を振る Shortcodes layouts/shortcodes/ruby.html を考える。
こんな感じ。
<ruby><rb>{{ .Inner }}</rb><rp> (</rp><rt>{{ index .Params 0 }}</rt><rp>) </rp></ruby>
これで例えば
{{< ruby "ひらがな" >}}平仮名{{< /ruby >}}
と記述すれば
これで例えば <ruby><rb>平仮名</rb><rp> (</rp><rt>ひらがな</rt><rp>) </rp></ruby> と記述すれば
これで例えば
平仮名 と記述すれば
と展開される。 パラメータの順番に意味ができるので，多数のパラメータが必要な場合には向かないかもしれない。
指定した範囲を Markdown ドキュメントとして処理する
.Inner 変数の内容を markdownify 関数に渡すことで Markdown ドキュメントとして処理する事ができる。
先程の layouts/shortcodes/fig-quote.html を少し改造した layouts/shortcodes/fig-quote-md.html を作ってみよう。
{{ with .Get "lang" }}<figure lang="{{ . }}">{{ else }}<figure>{{ end }}
<blockquote>{{ .Inner | markdownify }}</blockquote>
{{ if .Get "title"}}<figcaption>via <q>{{ with .Get "link"}}<a href="{{.}}">{{ end }}{{ .Get "title" }}{{ with .Get "link"}}</a>{{ end }}</q></figcaption>{{ end }}
</figure>これを使って以下の Markdown 記述を処理してみる。
{{< fig-quote-md title="Compatible Licenses - Creative Commons" link="https://creativecommons.org/compatiblelicenses" lang="en" >}}
The [GNU General Public License version 3](https://www.gnu.org/copyleft/gpl.html) was declared a “BY-SA–Compatible License” for version 4.0 on 8 October 2015.
Note that compatibility with the GPLv3 is one-way only, which means you may license your contributions to adaptations of BY-SA 4.0 materials under GPLv3, but you may not license your contributions to adaptations of GPLv3 projects under BY-SA 4.0.
Other [special considerations](https://wiki.creativecommons.org/wiki/ShareAlike_compatibility:_GPLv3#Considerations_for_adapters_applying_the_GPLv3) apply.
See the full [analysis](https://wiki.creativecommons.org/wiki/ShareAlike_compatibility:_GPLv3) and [comparison](https://wiki.creativecommons.org/wiki/ShareAlike_compatibility_analysis:_GPL) for more information.
{{< /fig-quote-md >}}
結果は以下の通り。
<figure lang="en">
<blockquote>The <a href="https://www.gnu.org/copyleft/gpl.html">GNU General Public License version 3</a> was declared a “BY-SA–Compatible License” for version 4.0 on 8 October 2015.
Note that compatibility with the GPLv3 is one-way only, which means you may license your contributions to adaptations of BY-SA 4.0 materials under GPLv3, but you may not license your contributions to adaptations of GPLv3 projects under BY-SA 4.0.
Other <a href="https://wiki.creativecommons.org/wiki/ShareAlike_compatibility:_GPLv3#Considerations_for_adapters_applying_the_GPLv3">special considerations</a> apply.
See the full <a href="https://wiki.creativecommons.org/wiki/ShareAlike_compatibility:_GPLv3">analysis</a> and <a href="https://wiki.creativecommons.org/wiki/ShareAlike_compatibility_analysis:_GPL">comparison</a> for more information.</blockquote>
<figcaption>via <q><a href="https://creativecommons.org/compatiblelicenses">Compatible Licenses - Creative Commons</a></q></figcaption>
</figure>
The GNU General Public License version 3 was declared a “BY-SA–Compatible License” for version 4.0 on 8 October 2015. Note that compatibility with the GPLv3 is one-way only, which means you may license your contributions to adaptations of BY-SA 4.0 materials under GPLv3, but you may not license your contributions to adaptations of GPLv3 projects under BY-SA 4.0. Other special considerations apply. See the full analysis and comparison for more information.
Shortcodes を入れ子にする
もうひとつ，以下の内容の layouts/shortcodes/quote.html ファイルを作ってみよう。
{{ with .Get "lang" }}<q lang="{{ . }}">{{ else }}<q>{{ end }}{{ .Inner }}</q>
これは .Inner 変数の内容を <q> 要素で囲むだけの簡単なコードだが，先程の fig-quote-md と組み合わせて
{{< fig-quote-md title="Compatible Licenses - Creative Commons" link="https://creativecommons.org/compatiblelicenses" lang="en" >}}
{{< quote >}}The [GNU General Public License version 3](https://www.gnu.org/copyleft/gpl.html) was declared a “BY-SA–Compatible License” for version 4.0 on 8 October 2015.
Note that compatibility with the GPLv3 is one-way only, which means you may license your contributions to adaptations of BY-SA 4.0 materials under GPLv3, but you may not license your contributions to adaptations of GPLv3 projects under BY-SA 4.0.
Other [special considerations](https://wiki.creativecommons.org/wiki/ShareAlike_compatibility:_GPLv3#Considerations_for_adapters_applying_the_GPLv3) apply.
See the full [analysis](https://wiki.creativecommons.org/wiki/ShareAlike_compatibility:_GPLv3) and [comparison](https://wiki.creativecommons.org/wiki/ShareAlike_compatibility_analysis:_GPL) for more information.{{< /quote >}}
{{< /fig-quote-md >}}
と入れ子構造にしてみる。 結果は以下の通り入れ子でも上手く処理されているのが分かる。
<figure lang="en">
<blockquote><q>The <a href="https://www.gnu.org/copyleft/gpl.html">GNU General Public License version 3</a> was declared a “BY-SA–Compatible License” for version 4.0 on 8 October 2015.
Note that compatibility with the GPLv3 is one-way only, which means you may license your contributions to adaptations of BY-SA 4.0 materials under GPLv3, but you may not license your contributions to adaptations of GPLv3 projects under BY-SA 4.0.
Other <a href="https://wiki.creativecommons.org/wiki/ShareAlike_compatibility:_GPLv3#Considerations_for_adapters_applying_the_GPLv3">special considerations</a> apply.
See the full <a href="https://wiki.creativecommons.org/wiki/ShareAlike_compatibility:_GPLv3">analysis</a> and <a href="https://wiki.creativecommons.org/wiki/ShareAlike_compatibility_analysis:_GPL">comparison</a> for more information.</q></blockquote>
<figcaption>via <q><a href="https://creativecommons.org/compatiblelicenses">Compatible Licenses - Creative Commons</a></q></figcaption>
</figure>
The GNU General Public License version 3 was declared a “BY-SA–Compatible License” for version 4.0 on 8 October 2015. Note that compatibility with the GPLv3 is one-way only, which means you may license your contributions to adaptations of BY-SA 4.0 materials under GPLv3, but you may not license your contributions to adaptations of GPLv3 projects under BY-SA 4.0. Other special considerations apply. See the full analysis and comparison for more information.
Shortcodes のみで HTML 展開する場合
{{< shortcodename >}} のみ，または {{< shortcodename />}} で表記すると {{ .Inner }} を持たない Shortcodes を表現できる。
たとえば layouts/shortcodes/fig-youtube.html というファイルを作成し，以下のコードを書く。
<figure style='margin:0 auto;text-align:center;'>
<div style="position: relative; margin: 0 2rem; padding-bottom: 56.25%; padding-top: 30px; height: 0; overflow: hidden;">
<iframe class="youtube-player" style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;" allowfullscreen frameborder="0" src="https://www.youtube-nocookie.com/embed/{{ .Get "id" }}" allowfullscreen></iframe>
</div>{{ if .Get "title"}}
<figcaption><a href="https://www.youtube.com/watch?v={{ .Get "id" }}">{{ .Get "title" }}</a></figcaption>
{{ end }}</figure>
これを使って
{{< fig-youtube id="Kjqff5bkUrE" title="「はやぶさ2」地球スイングバイ解説CG ／ Hayabusa2's Earth Swing-by CG - YouTube" >}}
と記述すると，以下のように展開される。
<figure style='margin:0 auto;text-align:center;'>
<div style="position: relative; margin: 0 2rem; padding-bottom: 56.25%; padding-top: 30px; height: 0; overflow: hidden;">
<iframe class="youtube-player" style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;" allowfullscreen frameborder="0" src="https://www.youtube-nocookie.com/embed/Kjqff5bkUrE" allowfullscreen></iframe>
</div>
<figcaption><a href="https://www.youtube.com/watch?v=Kjqff5bkUrE">「はやぶさ2」地球スイングバイ解説CG ／ Hayabusa2's Earth Swing-by CG - YouTube</a></figcaption>
</figure>
組み込みの Shortcodes
Hugo にはあらかじめ組み込まれた Shortcodes が幾つかある。
この中で一番よく使うのは記事間の相互リンクを張ることのできる ref および relref だろう。
たとえばこの記事の「ブックマーク」節にリンクを張る場合は
[このページのブックマーク]({{< relref "#bookmark" >}})
とすると
<a href="#bookmark">このページのブックマーク</a>
のように展開される。
ちなみに ref は絶対パス， relref は相対パスに展開される。
相互リンクは Hugo で管理している記事ならどれでも指定できる。 たとえば
[「ブックマーク」ページの「公式サイト」節]({{< ref "/hugo/bookmark.md#official" >}})
と記述すると
<a href="https://text.baldanders.info/hugo/bookmark/#official:9bacfa348e5fe42acc9342a16675997d">「ブックマーク」ページの「公式サイト」節</a>
のように展開される。