Hugo のショートコード内で Markdown を使う
Hugo のショートコード内の Markdown もレンダーさせる際にちょっとハマったのでメモです。
やりたいこと
よく技術系の Web サイトで以下のようなメモカード (一般的になんていうのかわからない) ってノーティス目的やワーニング目的で使ったりするじゃないですか。このサイトでも前回から使い始めています。
これを Hugo のショートコードで作って、カード内のコンテンツで Markdown を使えるようにしたかったのですが、ハマって色々調べたり試してみました。
結論
今回色々調べてはうまくいかなかったりと記事が長くなってしまったので、結論を先に書いておきます。
Hugo v0.100.0 以降でショートコード内で Markdown をレンダーするには config.toml
の markup.goldmark.renderer.unsafe
オプションを true
にし、ショートコードの呼び出しは {{% shortcode %}}
で行う。(検証できていませんが、v0.100.0 より前のバージョンでは config.toml
の markup.defaultMarkdownHandler
を blackfriday
にすればレンダーできるかもしれません)
順序付きリスト内でショートコード利用時に順序付きリストをブレイクさせないためには、ショートコード定義内でコンテンツを渡す際に、{{ .Inner -}}
と後ろにハイフンを付けて、空白を除去する。
詳細や、NG 事例は以下で紹介していますのでよかったら読んでください。
Shortcode とは
Hugo ではレイアウトファイルを使ってサイト自体のデザインを自由度高くカスタマイズできますが、コンテンツ内容は純粋に Markdown のパースおよび規定の HTML への置換と CSS でのデザインが限界です。
Hugo v0.62.0 以降は Markdown Render Hooks 機能が追加され、一部の要素についてカスタマイズが可能となりましたが、利用できる要素は限定的です。
そこで登場するのがショートコード機能です。ショートコード機能を使えば任意の要素をコンテンツ内に挿入することができます。また Hugo のビルトインショートコードも多く用意されており、ショートコードを利用することで、コンテンツデザインについても高い自由度が得られます。
ビルトインショートコードは Shortcodes | Hugo で紹介されています。
環境
- OS
- Windows 10 21H2
- Hugo
- v0.101.0
準備
自分のサイトだとテンプレートも自作しているので、ショートコードの問題なのかテンプレートの問題なのかわからなくなるので、Quick Start | Hugo に沿ってテスト用サイトを作り、既存テーマを適用します。
-
新しいサイトを作ります。
-
Ananke theme を適用します。
-
テーマを
config.toml
に定義します。
ショートコード作成と使用
-
layouts/shortcodes/memocard.html
というファイルを作成し、以下のコードを記載します。Create Your Own Shortcodes | Hugo に説明がありますが、ショートコードの定義は
layouts/shortcodes
ディレクトリ配下に HTML ファイルを作成し、定義します。 -
新しいコンテンツを作成します。
-
作成したコンテンツファイル
content/shortcodecontent.md
に以下を記載します。 -
サーバーを起動します。
-
ブラウザで
http://localhost:1313/shortcodecontent
にアクセスします。他の Hugo server を起動している場合、ポートは
1313
以外になりますので、適宜置き換えてください。
事象と対処
すでにコンテンツの中で事象を書いてしまっていますが、以下のような表示結果になってしまいます。
生成された HTML を見てみると以下のようになっています。
まず順序付きリスト 1 に記載したショートコードは {{< shortcode >}}
という記法で記載しています。この記法の場合、ショートコードに渡した Markdown はレンダーされないようです。ただ何故か HTML はレンダーされるようです。
The < character indicates that the shortcode’s inner content does not need further rendering. Often shortcodes without markdown include internal HTML - Shortcodes | Hugo
次に順序付きリスト 2 に記載したショートコードは {{% shortcode %}}
という記法で記載しています。この記法の場合、ショートコードに渡した Markdown はレンダーされるのですが、ショートコード定義に記載した HTML がすべて無視されています。生成された HTML にも <!-- raw HTML omitted -->
とコメントされています。加えて、順序付きリストがブレイクされ、順序付きリスト 3 の連番が 1 に戻ってしまっています。HTML でも <ol>
が分かれてしまっています。
In Hugo 0.55 we changed how the % delimiter works. Shortcodes using the % as the outer-most delimiter will now be fully rendered when sent to the content renderer. - Shortcodes | Hugo
ショートコード内の Markdown と HTML をレンダーさせる解決方法
HTML が無視される問題については、config.toml
に次のように記載すれば解消されます。
markup.goldmark.renderer.unsafe
オプションは コンテンツ内の HTML をレンダーさせるかを決めるオプションです。インライン JavaScript も埋め込み可能になりますので、セキュリティーの観点からデフォルトでは false
(=レンダーしない) になっています。
unsafe By default, Goldmark does not render raw HTMLs and potentially dangerous links. If you have lots of inline HTML and/or JavaScript, you may need to turn this on.
- Configure Markup | Hugo
しかし、ショートコードのためにセキュリティーリスクを高めてまで、markup.goldmark.renderer.unsafe
オプションを true
にするのも嫌ですよね。 (結論、この方法しかありませんでした。)
ショートコード内の Markdown と HTML をレンダーさせる NG その 1
{{< shortcode >}}
は Markdown はレンダーされないが HTML はレンダーされる、{{% shortcode %}}
は Markdown はレンダーされるが、HTML はレンダーされる。であれば、渡されたコンテンツをただ表示するだけのショートコードを作成しネストすればどうだ、と考え以下のようにやってみました。
コンテンツを表示するだけのショートコード (inner.html
):
ショートコードをネストさせる (順序付きリスト 2 のところ):
Markdown も HTML もレンダーされないどころか、<pre><code></code></pre>
でラップされてしまいました。
この挙動は上で書いた config.toml
の markup.goldmark.renderer.unsafe
を true
にしても同じです。
なお、ショートコード内に HTML を書いて {{< shortcode >}}
で呼び出した外側のショートコード内の HTML はちゃんとレンダーされています。
いずれにしてもこのやり方は NG です。
ショートコード内の Markdown と HTML をレンダーさせる NG その 2
そもそも config.toml
の markup.goldmark.renderer.unsafe
オプションは Markdown レンダリングエンジンに Goldmark が採用されているからです。 Goldmark は Hugo v0.60.0 からデフォルトレンダリングエンジンとして採用されています。それ以前は BlackFriday というレンダリングエンジンが使われていました。ではレンダリングエンジンを BlackFriday に戻してやればいいのではと思いましたが…。
config.toml
の markup.defaultMarkdownHandler
を blackfriday
に変更。
レンダーしてみると Hugo v0.100.0 で Blackfriday は削除されたとのことで、以下のようなエラーが出てしまいます。
まあそもそもこのやり方は config.toml
の markup.goldmark.renderer.unsafe
を true
にするのと同義だと思いますので、あまり意味ないですね。
ショートコード内の Markdown と HTML をレンダーさせる NG その3
その 3 と言いますかそもそも Hugo のビルトインショートコードがたくさんあるので、その実装を見れば答えがあるのでは?と考えたのですが、そもそも Hugo のビルトインショートコードにコンテンツを渡すタイプのものがない (シンタックスハイライトぐらい)ということに気づきました。ショートコードに Markdown 渡してレンダーさせるの邪道なのか。
順序付きリストがブレイクされる問題の解決方法
さて、ショートコード内の Markdown と HTML 両方をレンダーさせる方法は config.toml
の markup.goldmark.renderer.unsafe
を true
にするしかなかったわけですが、もう一つ順序付きリストがブレイクされてしまう問題がありました。
こちらはショートコード HTML 内で .Inner
を渡すときにハイフン -
をつけることで解消されました。
-
は空白を除去してくれるようです。
Go 1.6 includes the ability to trim the whitespace from either side of a Go tag by including a hyphen (
-
) and space immediately beside the corresponding{{
or}}
delimiter. - Introduction to Hugo Templating | Hugo
なお、両サイドに -
をつけると {{< shortcode >}}
でショートコードを呼び出したときと同じ挙動 (Markdown はレンダーされない。HTML はレンダーされる)になります。
あとがき
ちょっと釈然としませんが、Hugo のショートコードで Markdown をレンダーする方法と、順序付きリスト内でショートコードを使ってもブレイクさせない方法を調査、紹介しました。今後は Markdown Render Hooks 機能がもっと追加されればショートコードの利用を最小限にできるのかなと思います。