帰ってきた「しっぽのさきっちょ」

Shortcodes で HTML コードを埋め込む — ゼロから始める Hugo

今回は 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 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.
via Compatible Licenses - Creative Commons

{{< fig-quote >}} ... {{< /fig-quote >}} で囲まれている部分が {{ .Inner }} として展開されているのがお分かりだろうか。 Shortcodes では {{ .Inner }} 以外に任意のパラメータを持たせることができる。 上の例で言うなら lang, title, link{{< fig-quote >}} に対するパラメータである。

更に {{% fig-quote %}} ... {{% /fig-quote %}} と表記すると,囲まれた部分を Markdown と解釈する。

{{% fig-quote 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 %}}
<figure lang="en">
<blockquote><p>“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.”</p>
</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.”

via Compatible Licenses - Creative Commons

{{< shortcodename >}} のみ,または {{< shortcodename />}} で表記すると {{ .Inner }} を持たない Shortcodes を表現できる。 たとえば layouts/shortcodes/fig-youtube.html というファイルを作成し,以下のコードを書く。

<figure style='margin:0 auto;text-align:center;'>
<iframe class="youtube-player"{{ with .Get "width"}} width="{{ . }}"{{ end }}{{ with .Get "height"}}  height="{{ . }}"{{ end }} src="https://www.youtube-nocookie.com/embed/{{ .Get "id" }}" allowfullscreen></iframe>
{{ if .Get "title"}}<figcaption><a href="https://www.youtube.com/watch?v={{ .Get "id" }}">{{ .Get "title" }}</a></figcaption>{{ end }}
</figure>

これを使って

{{< fig-youtube id="Kjqff5bkUrE" width="500" height="281" title="「はやぶさ2」地球スイングバイ解説CG / Hayabusa2's Earth Swing-by CG - YouTube" >}}

このように記述すると,以下のように展開される。

<figure style='margin:0 auto;text-align:center;'>
<iframe class="youtube-player" width="500"  height="281" src="https://www.youtube-nocookie.com/embed/Kjqff5bkUrE" allowfullscreen></iframe>
<figcaption><a href="https://www.youtube.com/watch?v=Kjqff5bkUrE">「はやぶさ2」地球スイングバイ解説CG / Hayabusa2&#39;s Earth Swing-by CG - YouTube</a></figcaption>
</figure>
「はやぶさ2」地球スイングバイ解説CG / Hayabusa2's Earth Swing-by CG - YouTube

Shortcodes の例

spiegel-im-spiegel/hugo-theme-text theme では Shortcodes を収録してないが,このサイトの作業用リポジトリにはいくつか置いてある。 再利用はご自由に。

組み込みの Shortcodes

Hugo にはあらかじめ組み込まれた Shortcodes が幾つかある。 この中で一番よく使うのは記事間の相互リンクを張ることのできる ref および relref だろう。

たとえばこの記事の「ブックマーク」節にリンクを張る場合は

[このページのブックマーク]({{< relref "#bookmark" >}})

とすると

<a href="#bookmark:10ef41a6c37b90d6a6452868d5ba00ba">このページのブックマーク</a>

のように展開される。 ちなみに ref は絶対パス, relref は相対パスに展開される。

相互リンクは Hugo で管理している記事ならどれでも指定できる。 たとえば

[「ブックマーク」ページの「公式サイト」節]({{< ref "hugo/bookmark.md#official" >}})

と記述すると

<a href="http://text.baldanders.info/hugo/bookmark/#official:9bacfa348e5fe42acc9342a16675997d">「ブックマーク」ページの「公式サイト」節</a>

のように展開される。

ブックマーク

Hugo に関するブックマークはこちら