Gitのレポジトリにコミットされているマークダウンで書かれたドキュメントがあって、それをCI/CDパイプラインの中でHTMLに変換してBASIC認証かけて公開したい。。
というタスクを業務で振られたんでマークダウン をHTMLに変換するツールをいくつか試した。その時の内容を書いてみる。
要件
- マークダウン ファイルをCLIでHTMLに変換したい
- 所定のフォルダの中にHTMLとして吐き出してNginxでBASIC認証をかけて公開したい
- マークダウンの中のリンク先のファイル拡張子がマークダウン用の「.md」になっているのを「.html」に変換したい
- 見た目もいい感じにしたい
試したもの
- pandoc
- redcarpet
- vuepress
- gatsby.js
以下それぞれのツールについて
pandoc
- ツール自体の実装はHaskell
- マークダウン→HTMLだけじゃなくPDFとかOfficeファイルとかいろんなフォーマットに対応している
- Haskellの実行環境作らなくても公式のDockerイメージがあるのでpullしてすぐ使える。
- ファイル内のリンク先の拡張子を「.md」から「.html」に変換するのがちょっと面倒。フィルタ用のスクリプトを書いてコマンド実行時にオプションで渡さないといけないんだけどその場合その言語の実行環境も作らないといけなかったりちょっと面倒。
- 個人的にRubyが好きなのでRubyでスクリプト書く手段を調べた結果、rubyでのラッパーだったりrubyでフィルターを書くgemがあったんでその辺りは良さそう
- 見た目をいい感じにするにはCSS書いて読み込ませる必要あり
redcarpet
- マークダウンをHTMLに変換するRubyのgem
- Railsの中のhelper関数の中で使ってWebアプリケーション上でマークダウン をHTMLにして表示する。みたいな使われ方が多そう
- 今回のような使い方で見た目をいい感じにするにはCSS書いて読み込ませる必要あり。Railsアプリ内で使うならRailsのCSSを適用すればいいんだろうけど、今回の要件だとちょっと面倒
- カスタマイズするにはgem内で定義されているクラスを再オープンしてメソッドをオーバライドしていく↓
こんな感じ
class CustomHTMLRender < Redcarpet::Render::HTML def table(header, body) "<table class='table'>" \ "<thead>#{header}</thead>" \ "<tbody>#{body}</tbody>" \ "</table>" end end options ||= { tables: true, } markdown = Redcarpet::Markdown.new(CustomHTMLRender, options)
vuepress
- 見た目がデフォルトでもかっこいい。カスタマイズも楽
- カスタマイズはスタイルシート追加、config追加で基本対応可能
- 名前にvueとついてるけど普通に使う分にはVueのコードを書く必要ない。凝ったカスタマイズをする場合はVueでプログラムを書く必要あり
- 開発用のホットリロードのコマンドと本番配布用にdistフォルダにbundleしたコードを吐き出すコマンドが用意されていてwebpackを書く必要がない
- 特に設定したりプログラム書かなくてもリンク先を「.html」に自動で変換してくれる
gatsby
- 有名で情報量が多い
- vuepressは名前の通りvueだけどこっちはReactっぽく書ける
- マークダウンに対応するにはjsライブラリを追加する必要あり
- GraphQLで記事を管理できる。ワードプレスみたいなCMS感覚で使いたいならvuepressよりこっちのがいいのかもしれない。。けど今回のCI/CDでコマンド叩いてHTML作ってNginxで公開すればいいのでvuepressのがいいかな？
結果
要件に合致しているvuepressにしました。
