Hugo テーマ 8. Shortcodes と Render hooks

Markdown で記述したコンテンツ (テーマの利用側) に対して Hugo が用意した HTML 変換の仕組みを解説します。

普通であればこれまで解説してきた仕組みを通じてサイトやページの構成がされ、個々のコンテンツとしては Markdown の内容が HTML に変換されます。

Hugo には、このとき出力される HTML を Markdown の表現を拡張して行えるような仕組みが用意されています。
それが Shortcodes と Render hooks です。

いずれも、テーマ側が用意できるものです。

今回はそれぞれを紹介していきます。
また、それぞれの特徴を比較してどちらを使うか、ということも話題にします。

共通することがら

レイアウト定義に対して

いきなり Shortcodes ⇔ Render hooks の構図から外れますが、両者とこれまで解説してきたレイアウト定義との対比もします。

これまで解説してきたレイアウト定義は、どちらかというと、コンテンツの配置場所やメタ情報 (フロントマター) に基づいてサイトの構造を定義するものでした。

これに対し、Shortcodes, Render hooks は、コンテンツを部分的に装飾する・その表現能力を拡張する、という役割があります。

別にテーマ側がすべて用意する必要はない

要は、たとえばテーマとは別に、Shortcodes や Render hooks だけを提供するようなものを作っても良い、ということです。

１回目の内容 (テーマとは) を少し掘り下げます。

テーマは「モジュール」の一種なのでした。
そして、モジュールは「コンポーネント」をまとめたものなのでした。
コンポーネントは、archtypes や layouts といったディレクトリーに対応した何かしらのファイルを利用者側に提供するものです。

テーマに関連するような Shortcodes や Render hooks はテーマに含めて配布されるでしょうが、それら単体のみを配布したりそれを利用したりできるわけです。

というか、両者を分離しておいた方が利便性は高いでしょう。

ちなみに、モジュールの作成やインポートについては Use Hugo Modules ☐↗ に説明があります。

どちらも Hugo 独自の記法である

どちらも、ほかの Static Site Generator にはない記法です。 そのため、ある程度 Hugo 前提でのコンテンツ作成をすることを決めた利用者向けといえそうです。

まあ、ほかの Static Site Generator では、これとは別の独自記法があるわけで、Hugo へのロックインを危惧していてもしょうがないのですが。

HTML をコンテンツ内に記述する方法もあります。
多くの SSG でも生の HTML を記述可能なようなので、コンテンツを他システムにも転用したい場合には生 HTML が一番「かたい」とも言えます。
ただしそれをした場合、Shortcodes 内の Markdown が表現しづらくなる (もしくはできなくなる) 不便さは生じます。

Shortcodes とは

コンテンツ内に少し特殊な書き方をすることで、それ専用の HTML に変換する仕組みです。

通常、コンテンツ内には Markdown しか記述できません。
サイトとしてはただの文章やイラストだけではなく、YouTube のリンクなどもっとダイレクトに情報を伝えられる形式があればそれを提示したくなるはずです。

Shortcodes を使うと、Markdown では表現できないようなものを HTML に直接変換できます。

例: YouTube shortcode

一例として、Hugo 組み込みの YouTube shortcode ☐↗ を紹介します。

YouTube shortcode では、以下のように記述することで、コンテンツに YouTube 動画を埋め込むことができます。

記述例

{{< youtube 0RKpf3rK57I >}}

こうなる

生成された HTML

<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden;">
  <iframe allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share; fullscreen" loading="eager" referrerpolicy="strict-origin-when-cross-origin" src="https://www.youtube.com/embed/0RKpf3rK57I?autoplay=0&amp;controls=1&amp;end=0&amp;loop=0&amp;mute=0&amp;start=0" style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border:0;" title="YouTube video"></iframe>
</div>

例: Details shortcode

もう一例として、同じく Hugo 組み込みの Details shortcode ☐↗ を紹介します。

これは折り畳みを実現するものです。

記述例

{{< details summary="See the details" >}}
This is a **bold** word.
{{< /details >}}

こうなる (“See the details” をクリックしてみてください)

生成された HTML

<details>
  <summary>See the details</summary>
  <p>This is a <strong>bold</strong> word.</p>
</details>

Hugo 組み込みの Shortcodes

なお、Hugo 組み込みの Shortcodes は Shortcodes ☐↗ にまとめてあります。

Render hooks とは

次は Render hooks についてです。

これは、通常の Markdown から HTML に変換する際のルールを変更するためのものです。

実例を掲載します。

例: 外部サイトは別タブで開くリンク

記述例

[このサイト内](/hugo_theme/00/)  
[サイト外リンク](https://gohugo.io/)

こうなる

このサイト内
サイト外リンク ☐↗

生成された HTML

<p>
  <a href="/hugo_theme/01/">このサイト内</a><br>
  <a href="https://gohugo.io/" target="_blank" rel="external noopener noreferer">サイト外リンク <span style="position:relative;"><span style="">&#x2610;</span><span style="position:absolute; top:-0.3em; left:0.2em">&#x2197;</span> </span></a>
</p>

Hugo で利用可能な Render hooks

Hugo のドキュメント (Render hooks / Introduction ☐↗ ) によりますと、以下の Render hooks を定義できます。

• Blockquotes
  • > hogehoge
  • > [!note] hogehoge もフック可能
• Code blocks
  • ```html (コード) ```
  • ASCII 文字で図を描く GoAT は Render hooks として拡張されている
• Headings
  • # heading1
  • 記号に対応するレベルの調整、id 属性値の指定
• Images
• Links
• Passthrough elements
  • Hugo が Markdown の処理に使っている Goldmark の拡張に対するフック (よくわかっていない)
• Tables

Hugo 自身が定義している Render hooks は GitHub ☐↗ 上にいくつかあるようです。

使い分け

両者をどのように使い分けていくか、幾つかの観点で比較します。

利用者に対する使う・使わないの選択肢を考慮する必要がある

利用者側からすると、不要な Shortcodes に対しては使わないという選択肢があります。
それに対して Render hooks は、素直に使っていると、使わないという選択肢がありません。

利用者はモジュール (テーマ) が用意した Render hooks の利用を強制されることになります。
一応、利用者側としては「自身のプロジェクトで Hugo 標準の Render hooks を定義する」というやり方をとることで、モジュール (テーマ) の Render hooks を無効化 (上書き) できます。
ですが、利用者にその方法をとれる利用者を期待するのはやめたほうが良いでしょう。

テーマがその中に Render hooks を作る場合は、上記のことを考慮したうえで、必然性のある範囲の内容で提供するのが良いでしょう。

安全方向に振るなら Shortcodes だが…

上で述べたように、Shortcodes の方が柔軟性に優れます。

Markdown で表現できるなら作らない

ただし… これは個人的なお願いにはなるのですが、Shortcodes を「Markdown でも書けることをショートカットするための記法」と捉えるのは、できれば避けてください。
そのような特殊な記法を濫用することは、Markdown でコンテンツを記述できるという Hugo の利点を損ないます。 また、コンテンツの記述を後から見返した際にも理解を妨げることになります。

以下のような場合に Shortcodes を作ることを検討するのが良いでしょう。

• Markdown では表現できない
• 条件判断が複雑だったり繰り返しが発生したりする

ドキュメントで説明する

また、Shortcodes について説明するドキュメントが必要になることには注意してください。
(たとえば、README に Shortcodes 一覧などのセクションを設ける)

Render hooks とは異なり引数をとれる関係上、引数の説明も必要です。 また、利用者に結果を理解してもらうためには、出力される HTML の例を掲載した方が親切でしょう。

テーマの中に Shortcodes を用意する場合には、その結果がテーマの用意するスタイルなどと調和して表示されることが期待されます。 便利だからといって、テーマに必然性のない Shortcodes を量産するのは避けましょう。