MD を PDF に変換

これはサイト内の他の文書変換と決定的に違う点です。Word のファイルは自分のページサイズや余白、フォントを知っていますが、Markdown ファイルはそのどれも知りません。この形式は意図的に構造だけを記録し、見た目は表示するもの側にゆだねているからです。

そのためページのサイズ、余白、書体、どこで改ページするかといった判断はすべて変換器が行い、あなたのファイルにはそのどれも書かれていません。それが Markdown の取引で、たいていは良い取引です。同じ文書がウェブページにもスライドにも PDF にも、書き直すことなくなれるからです。ただしこのペアの背後にあるエンジンは Markdown を読む仕組みを持たないため、コストがここに現れます。表示するものが何もなく、文字をそのまま組むしかありません。

ファイルのすべての文字が、順番どおり、同じ書体で紙面に現れます。## Requirements という行は ## Requirements のまま組まれます。ハイフンで書いた箇条書きは、ハイフンで始まる行のままです。フェンスで囲まれたコードブロックも上下の3つのバッククォートを保ったままです。太字も4つのアスタリスクを保ちます。何も捨てられず、何も解釈されません。このペアの背後にある文書エンジンはテキストを読むものであって、Markdown 用のフィルターを渡されたことがないからです。

ここから何が残るかは正確に言っておく価値があります。改行、空行、字下げは正確に保たれるので、コマンドや設定内容が値打ちの文書はそのまま使える形に変換されます。見出しの階層構造こそが値打ちの文書はそうはならず、そのときの答えは書いたツールの中で Markdown をレンダリングしてから印刷することです。エディターのプレビュー、静的サイトのビルド、ドキュメントのパイプラインなど、どれでも構いません。この変換はファイルの文字を修正するためのもので、組版のためのものではありません。

6枚の図を表示している Markdown 文書には、図そのものは1つも入っていません。入っているのは6つのパスで、絵はディスクやサーバー上のそのパスの先にあります。これは初めて変換する人を驚かせやすく、PDF に空白が生じるいちばんよくある原因です。

対処法は変換する前にパスが解決する状態にしておくことです。相対パスなら文書に実際に付随しているファイルを指していなければならず、絶対パスの URL ならそのサーバーが到達可能である必要があります。画像が文書の主眼であれば、変換の設定より先にここを整えてください。

多くの Markdown ファイルは、タイトルや日付、タグを含む3本のハイフンで囲まれたブロックで始まります。静的サイトジェネレーターやドキュメントビルダー、メモアプリはそれをメタデータとして読み取り、レンダリングする前に取り除きます。

この変換はその慣習を知らないので、そのブロックも他のすべてと同じように印字してしまい、PDF は3本のハイフンとキーと値のペアの一覧から始まります。変換する前にそのブロックを削除するのがそのまま対処法で、元のファイルはそのツールの中で動き続けるよう、複製の上で行っておくとよいでしょう。

2004年の最初の Markdown の記述は非公式なもので、CommonMark はほとんどのツールが従う厳密な仕様であり、みんなが使うパイプテーブルやタスクリスト、脚注、取り消し線はその上に乗った拡張です。どれを実装しているかが、通常は文書がどう仕上がるかを左右する分かれ道になります。

このページではそれが問題になりません。ここには本体もどの拡張も実装されておらず、GitHub のテーブルも CommonMark の見出しも等しくただの行として扱われます。少なくとも予測はしやすく、どの流儀かを推測する必要も、どのレンダラーで試すかも考えなくてよく、シンタックスハイライトを切ったエディターで見えるものが、そのまま PDF の中身になります。

読み手があなたではないからです。クライアントや弁護士、委員会、コンプライアンス担当者が求めているのは、開いて印刷して署名を回して保管できる文書であって、コードエディターで開くかと聞いてくる機械や、たどらなければならないリポジトリではありません。記号がそのまま残るので、これは見せるためのコピーというより固定するためのコピーです。

PDF は状態も凍結します。README は毎週変わりますが、その PDF はそれが何かに添付された日に真実だった内容です。審査や提出、契約の付属書類にはまさにそれが必要です。普段は Markdown で書き続け、外部の誰かにコピーが必要になった瞬間だけ書き出してください。

行き先がウェブページやドキュメントサイトなら HTML です。Markdown はもともとそのための省略記法として設計されたので、この変換はレンダリングというよりむしろ翻訳に近い作業になります。

DOCX が向いているのは1つの具体的でよくある状況です。相手が Word ファイルしか受け付けず、変更履歴を付けて追記したい場合です。Markdown にはレビューの仕組みが一切ないので、コメントのやり取りが必要な文書は DOCX として渡し、あとで読み戻すほうがよく、PDF は仕上がった版のためのものです。この行き先も同じエンジンを通るので、記法は Word ファイルの中でも文字として届きます。違うのは、レビューする人が見出しを直せるのに対し、PDF の中では直せないという点です。

この変換に持ち込む前に、見出しや強調が実際にレンダリングされた状態が必要かどうかを確認してください。必要であれば、ここではなく Markdown を書いたエディターやツールから印刷するほうが目的にかないます。

必要ないなら、つまり修正の履歴や設定を固定したいだけなら、このページで問題ありません。フロントマターのブロックを削除してから、ファイルを置いてください。

このペアはサーバー上で動きます。Markdown を本物の文書エンジンで組版するには、ブラウザーの中で完結する仕組みでは足りないからです。ファイルは暗号化された接続で送られ、インターネットへの出口を持たない隔離された環境で変換され、作業が終わるとすぐに削除されます。

無料枠は1ファイルあたり25 MB までです。ファイルサイズが大きい大量のドキュメントを変換する場合は、その上限にも注意してください。