MarkdownをPDFに変換

どのMarkdownを、どう変換するのか

Markdownは1つの仕様ではなく、仕様の集まりです。見出し、強調、リスト、リンク、画像、引用、コードブロックといった共通部分はどこでも同じですが、それ以外は実装ごとに異なります。ここで対応しているのは、広く合意された拡張セットです。表、シンタックスハイライト付きのフェンスコードブロック、タスクリスト、取り消し線、脚注、フロントマター。ほぼ誰もが書く内容はこれで網羅できますが、境界がどこにあるかは、後で気付くより先に知っておく価値があります。

見出しは単に大きな文字ではなく、PDFの本物の構造になります。アウトラインレベルを持つので、PDFには移動に使えるしおりパネルができます。リンクは機能するリンク注釈になります。コードブロックはハイライト付きの等幅フォントで組まれます。読みやすい文書になるか、灰色の文字の壁になるかの違いです。Markdownファイルは用紙について何も指定しないので、ページサイズと余白は読みやすさを考えて選ばれます。

画像は参照できる場所にある必要があり、これが最もよくある期待外れの原因です。Markdownファイルは画像を含むのではなく参照しているだけなので、相対パスは画像をファイルと一緒にドロップした場合にしか解決できず、Webアドレスはそのサーバーがほかのサイトからの取得を許可している場合にしか解決できません。見つからない画像は、黙って空白にするのではなくPDF内にその旨が表示されるので、図が欠けていても、送信した後ではなくその場で気付けます。

2つのものは、描画せずに意図的にコードとして表示します。LaTeX記法の数式とMermaidの図は、それぞれ専用の描画エンジンが必要で、間違って描画するくらいなら元のコードを見せるほうがましです。誤って描画された数式は、誰にも気付かれない形で間違っています。Markdown内のHTMLは、簡単なインライン書式には対応しますが、レイアウトには対応しません。任意のマークアップのブロックは、ページ分けされた文書にはなじまないからです。

ほかの目的には

この用途の本格的なツールは Pandoc で、無料です。pandoc doc.md -o doc.pdf --pdf-engine=xelatex はLaTeXで組版するので、適切なハイフネーション、段落末の孤立行の制御、本物の目次を備えた、本当に美しい出力になります。テンプレートを使えばデザインのあらゆる面を制御できます。このページでは対応していないLaTeXの数式も正しく描画します。代償はTeXディストリビューションのインストールで、決して小さくはありません。

単発の文書ではなくドキュメント類なら、静的サイトジェネレーターや mdBook のほうがPDFより良いものを作れます。検索でき、リンクでき、スマートフォンでも読めます。PDFに変換するのは、印刷、添付、保管が必要なときにしましょう。どちらの場合もMarkdownを正本として残してください。編集や差分の比較ができるのはそちらだからです。