Hugo の Markdown レンダリングについて調べた

日記兼備忘録。

Go 製の静的サイトジェネレータ Hugo の [link\\](url) という形式のリンクがうまくレンダリングされないバグを追いかける過程で、Hugo が使っている Markdown レンダリングのライブラリについて調べたのでまとめる。

https://opentracing.io を閲覧中、Jaeger へのリンクが壊れているのを発見。どうも2重バックスラッシュが閉じ角括弧に対するエスケープと解釈されているようだったので、暫定対処としてスペースを入れてみたら直った。ダメ元で PR を出したらマージされた。

opentracing.io は Hugo を使っていたので、クイックスタートを立ち上げてみて [link\\](url) を試してみたら無事再現。 取り急ぎ Hugo のレポジトリに Issue を登録してから、どこが問題なのか調べてみた。

Markdown レンダリングの流れをきちんと追ったわけではないが、このへんを見る限り blackfriday というライブラリを使っていることがわかったので、そちらへ。

blackfriday は v1.x を master ブランチで、v2.x を v2 ブランチで管理する体系になっていたので、どちらのブランチも確認してみた。レポジトリの構造は違っていたが、幸いリンクを処理するコードはどちらもほぼ同じで、[] の中で現れたバックスラッシュは、バックスラッシュ自体のエスケープかどうかをチェックせずに無条件に次の文字に対するエスケープとみなすような実装になっていた。さらに幸いなことに isBackslashEscaped(data []byte, i int) bool という、data[i] がバックスラッシュでエスケープされているかを判定するユーティリティ関数が別に定義されていたので、v1 と v2 両方向けにそちらを使うように修正した PR を投げた。

手元で balckfriday を修正した状態で hugo を再ビルドして、[link\\](url) のレンダリング結果を確認したところ、正しくリンクとして機能した。この時点で Hugo に罪が無いことがわかったので、Hugo に出した Issue はクローズした。後は blackfriday 側の PR のマージ待ち。

2019/01/22 追記: 無事マージされました。

blackfriday とその fork レポジトリ

以下は、blackfriday 周りを調べていてよくわからなくなったメモ。

Hugo は Markdown レンダリングのために blackfriday とは別に miekg/mmark というライブラリも利用している。

miekg/mmark は blackfriday の fork で、追加でいくつかの拡張シンタックスをサポートしているらしい。そして README のトップにある通り、このレポジトリはもう deprecated で mmarkdown/mmark に移行した模様。

mmarkdown/mmark は fork ではない新規レポジトリだが、その内部で gomarkdown/markdown というライブラリを利用している。

gomarkdown/markdown 自体は blackfriday の v2 ブランチを元にした fork とのこと。結局 blackfriday に戻ってきてしまった。もし今新規で markdown パーサを使うとしたら、結局どれがいいのだろうか…… blackfriday v2 か、それとも mmarkdown/mmark なのか……

そして Hugo に立ち返ってみると Hugo が使っているのは blackfriday の v1 と miekg/mmark。どちらも古いが、アップデートはすんなりとできるものなのか……