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 は、素直に使っていると、使わないという選択肢がありません。

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

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

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

正直、Shortcodes は書くの面倒です。書き方忘れますし。(←後者は個人の問題)
使わなくても表現できるのであれば、使いたくはないです。 (個人の感想です)

Shortcodes を作るのであれば、Markdown では記述が面倒・そもそも表現できない、条件判断が複雑だったり繰り返しが発生したりする、というような表現をカバーする、というのが目標であってほしいと思っています。

最後はなにやら愚痴っぽくなりましたが、これも一つの観点として、便利な機能について考えていただければ幸いです。