🧜♀ Mermaid 入り Markdown を、美しい PDF に変換する Pandoc フィルタを開発した
gazu: Mermaid 入り Markdown を、美しい PDF に変換する
Markdown 文書を PDF に変換するには Pandoc が便利。Pandoc は Haskell 製の汎用文書変換器で、Markdown → PDF はもちろん、Word → HTML とかも可能。ただし Pandoc は Mermaid を解釈できないので、文書が Mermaid を含む場合は専用の filter が必要になる。
そこで、Mermaid を処理する Pandoc filter gazu を開発しました。使い方は簡単！Pandoc のコマンドに --filter gazu を加えるだけ。
# HTML
pandoc input.md -o output.html --filter gazu
# PDF via weasyprint
pandoc input.md -o output.pdf --pdf-engine=weasyprint --filter gazu
# PDF via typst
pandoc input.md -o output.pdf --pdf-engine=typst --filter gazu -V mainfont="Noto Sans"
Code language: Bash (bash)詳しい使い方と仕様は ReadMe を見てね。インストールもコマンド一発で簡単だよ。
cargo install gazu
Code language: Bash (bash)なぜ作ったか？
もちろん Mermaid 用の Pandoc filter が、今まで 1 つも存在しなかったわけじゃない。先行事例としては、例えば mermaid-filter は人気のある Pandoc filter だそうだ。しかし、mermaid-filter の仕様はイケてない僕の目的には合わなかった。mermaid-filter の惜しい仕様は、次の 3 点。
- PDF に Mermaid 図をベクタ画像で埋め込めない (PNG にラスタ化される)
- PNG の解像度が粗い。デフォルトで横最大 784 px (一応、設定で変更は可能)
- 文書中の Mermaid 図が多いと、変換処理が遅い (図 3 つの変換に 10 秒要することも)
gazu 美しい。(右) mermaid-filter ジャギジャギ「これは酷い改善の余地だ。自分で作ってみよう」そうして作り始めたのが gazu だった。結果、gazu はデフォルトでジャギの無い滑らかな SVG を書き出し、かつ mermaid-filter より 7 – 11 倍の高速化を実現した。きっと mermaid-filter より使いやすいと思うので、ぜひ使ってみてね。
Why the name?
gazu の名前の由来は、『画図百鬼夜行』『今昔画図続百鬼』の「画図」。これは江戸時代の妖怪画家 鳥山石燕の代表作に挙がる妖怪画集シリーズで、石燕はこのシリーズで日本古来の人魚像を描いている¹。「人魚を描き、画集に収録」したものが「画図」なら、「Mermaid を描き、PDF に収録」するものは gazu だろうと考え名付けてみた。
gazu は Mermaid に関するツールで、つまり人魚に関するツールだ。人魚にまつわる何らかから名前のヒントを得ようとしていた。例えば Mermaid 公式 CLI は mmdc = Mermaid CLI で、あまりに味気ない。名前なんて mermaid-svg でも mermaid2svg でも mmd2svg でも問題は無いけど、せっかくならそんな説明的な名前ではなく、僕ならではの要素を盛り込みたかった。
実は、最初は西洋美術から名前の着想を得ようとしてた。人魚美術の代表作 A Mermaid の作者 John William Waterhouse に因んで waterhouse とか。でも、どうもしっくり来ない。もっと独創的な名前にするには… と考えたとき、「日本の人魚なら、きっと独創的じゃん！」と閃いたんだよね。
日本古来の人魚を描いた有名な画家を探すと、鳥山石燕の他に葛飾北斎も挙がる。でも CLI 名として reference することを考えたとき、葛飾北斎はちょっと『富嶽三十六景 / 神奈川沖浪裏』が有名すぎて、人魚を連想しづらい。そう思って、鳥山石燕に因むことにしたのでした。当の石燕も、実際には人魚画家としてではなく、妖怪画家として有名なんだけどね😅
(*1) 人魚を収録するのは第 3 作『今昔百鬼拾遺』で、実は「画図」を冠してない。それでも gazu を選んだのは、打ちやすさや発音しやすさを考慮して
[余談] 設計の紆余曲折と、実際の開発順序
こうした本格的なツールの開発は僕にとって初めてだったから、実は gazu の設計と仕様は大きく二転三転してる。最終的に現行の「Pandoc filter の gazu」と「Mermaid → SVG 変換ライブラリ」の 2 段構えに辿り着くまで、工夫に工夫を重ねて紆余曲折だった。詳しくは別の記事を参照してね。