[Hugo] Hugoのショートコードを記事内に表示するのは意外と手間がかかる
Nプログラマ(@Nprog128)です。
当ブログでは Hugo に関する記事もちらほらと書いていますが、ちょっと困る時があります。
それは、ショートコード呼び出しをサンプルソースとして表示する時です。
例えば、こんなショートコードを表示したいとします。
{{< sample-shortcode >}}
これをそのまま書くと、こんな感じでエラーが表示されるはずです。
1failed to extract shortcode: template for shortcode "sample-shortcode" not found
Hugoのショートコードとして解釈されて、存在しないショートコードを指定しているのでエラーが出てしまいました。
今回は、このような場合に試行錯誤したメモリアを残しておきたいと思います。
対処1: htmlのエスケープ文字で書く
markdown内には直接htmlが書くこともできるので、試しにエスケープ文字で書いてみたらうまくいきました。
{< sample-shortcode >}}
ただ書くのがちょっと大変なので、スニペットを登録しておいた方がいいと思います。
実際に記述した内容はこんな感じになります。
1{{< sample-shortcode >}}
| 表示したい文字 | エスケープ文字 |
|---|---|
| { | { |
| } | } |
| < | < |
| > | > |
パッと見て分かりづらいですね。
こういうのはなるべく専用の変換処理に渡してあげて、自分としてはなるべく書かないようにしたいトコロです。
デメリットは、このようなhugoのハイライト記法が書けないことです。
エスケープ文字で書いてやればいいや！って思い書いてみたのですが、本来は{{< sample-shortcode >}}となって欲しいのですが、エスケープ文字がそのまま出力されています。
1{{< sample-shortcode >}}
対処2: バックスラッシュでエスケープする
こちらはmarkdown内でのエスケープ処理として、バックスラッシュでやってみたらうまくいきました。
{{< sample-shortcode >}}
これは実際に書くと以下のようになります。
1\{\{\< sample-shortcode \>\}\}
先程よりは少し見やすく感じになりましたが、それでもちょっと面倒です。
こちらもハイライト記法では、バックスラッシュがそのまま表示されてしまいます。
対処3: 表示用ショートコードを作る
後述する対処の方がいい感じだったため、お蔵入りになったショートコード。
ざっくり説明すると、ショートコード名を引数に渡して内部で{{<と>}}を表示させる、というものです。
本来はこれを題材に記事を書くつもりでしたが、これよりもいい方法があったので断腸の思いでお蔵入りへ。
こんな感じのショートコードを作りました。
複数行も表示することができ、オマケ機能としてコメント行と行番号の表示機能も作りました。
コメント行の判定は正規表現で先頭の#の数が1以上なら、コメント行としてそのまま表示するというものです。
行番号はカウンターを持たせておいて、行の先頭に現在のカウント数を表示しています。
こちらもハイライト記法は使えません。
対処4: 外部ファイルとして読み込み表示させる
対処3のお蔵入りになったショートコードの代わりに採用した方法です。
外部ファイルをjQueryのajax通信で読み込んだらうまく表示できるかも、、、と考えながら先人の知恵を検索したらこちらのページを見つけました。
ソースコードを簡単綺麗にハイライト表示する「highlight.js」
jQueryが使えればすぐにできるのでオススメです。
ハイライト処理は使わないので、コードはこんな感じにしました。
1$(function(){
2 $.ajax({
3 url: '読み込みたい外部ファイルのパス',
4 success : function(data){
5 $('pre.external-code').text(data);
6 },
7 });
8});
先程のお蔵入りになったショートコードのサンプルも、この方法で表示しています。
まだ試せていない内容: ハイライト
先程 参考にしたページ では、highlight.jsで読み込んだ外部ファイルを行単位でハイライトしていました。
ページ読み込み時よりも、予めハイライトした結果を表示したいなぁ〜と思って、先人の知恵（2回目）を検索したら、こちらのページを見つけることができました。
highlight.jsをローカルで実行してハイライトされたファイルを出力
表題の通りで、ローカル環境でハイライトした結果を生成しているようです。
こちらもまだ試せていないのですが、たぶん出力されたハイライト済みのファイルを先程の外部ファイルを置き換えれば、ハイライトされた状態でコードを表示できると思います。
感想: 色々と試行錯誤してみた結果。。。
まぁ、、、確かにGistの方がラクですね（笑）
ラクなんですが、記事内で数行のコードを表示するために、gistを使うのもなんだか面倒でありまして。。。
ファイル単位で表示する場合は、リポジトリを分けるか、 gist-embed を使うなどの方法もありますが、ちょっと手間がかかります。
その点では、対処3の外部ファイルから読み出す方法は自分のリポジトリ内で管理できますし、ローカルのファイルの書き換えで変更がすぐに確認できるので、個人的にはこちらの方法が気に入っています。
おわりに
今回は、Hugoのショートコードを記事内に表示するのに色々と試行錯誤した、という内容でした。
かなり時間がかかりましたが、外部ファイルから読み込むという方法に行き着いてよかったです。
Hugoのショートコードを記事内に表示する時の参考になれば、と思います。
それでは、このへんで。
バイナリー！
