Markdown (MD)をPDFに変換して公開する方法
Markdownで書く人がPDF出力を使うべき理由
Markdownは、ワープロと格闘することなくコンテンツに集中したいテクニカルライター、開発者、ブロガーにとって最適なフォーマットです。ファイルサイズは小さく保たれ、バージョン管理もスムーズに行え、生のままでも構文は読みやすいです。しかし、クライアントに何かを提出したり、レポートを提出したり、洗練されたドキュメントを公開したりする瞬間に問題が発生します。プレーンな.mdファイルはエディターごとに表示が異なり、ほとんどの非技術系の受け取り手は開き方を知りません。 PDFはその問題を解決します。PDFはどのデバイスでも同じように表示され、フォントを埋め込み、見出しの階層を保持し、再フォーマットの心配なく印刷できます。VS Codeで完璧に見える40ページにもわたる技術仕様書を、クライアントの受信箱に、何もインストールすることなく任意のブラウザやPDFリーダーで開ける単一の自己完結型ファイルとして届けることができます。 ただし、変換プロセスは常に単純ではありません。Markdown自体には、改ページ、余白、フォントサイズに関する標準がありません。これらの決定は、それを処理するレンダラーに委ねられます。「アスタリスク付きのテキスト」と「印刷可能なPDF」の間のこのギャップこそが、このガイドでカバーする内容であり、CocoConvertのようなツールがどこに役立つか、そしてより専門的なツールが必要になる場合についても説明します。
MDからPDFへの変換中に何が起こるのか
このパイプラインを理解することで、出力の問題を予測し、修正するのに役立ちます。MarkdownをPDFに変換するプロセスは、実際には内部で2つのステップに分かれています。たとえツールがそれらのステップを1つのボタンの裏に隠していてもです。 ステップ1：Markdownは中間フォーマット（ほとんどの場合HTML）にパースされます。すべての見出しは`<h1>`から`<h6>`タグになり、太字のテキストは`<strong>`に、コードブロックは`<pre><code>`要素になるなどです。このステップの品質は、パーサーがどのMarkdownフレーバーをサポートしているかにかかっています。CommonMarkが最も標準化された仕様です。GitHub Flavored Markdown (GFM)は、テーブル、タスクリスト、打ち消し線を追加します。もしあなたのドキュメントがパイプテーブルのようなGFM機能を使用しており、コンバーターがCommonMarkしか扱えない場合、それらのテーブルは出力で生のパイプ文字として表示されてしまいます。 ステップ2：HTMLは、ヘッドレスブラウザエンジン（PuppeteerのようなChromiumベースのツール）または専用のPDFライブラリを使用してPDFにレンダリングされます。このステップでは、タイポグラフィ、スペーシング、ページレイアウトのためにCSSが適用されます。A4またはレターサイズの用紙では、通常、各辺に20〜25mm程度の余白が設定されます。コードブロックには等幅フォントが適用されます。ツールが適切なデフォルトスタイルシートを使用していれば、設定なしでプロフェッショナルな見た目の結果が得られます。 実用的な意味合いとしては、PDF出力がおかしい場合、バグは通常これら2つのステップのいずれかにあります。つまり、Markdownが正しくパースされなかったか、レンダリング中に適用されたCSSが予期しないスペーシングやフォントの選択を生み出したかのどちらかです。
CocoConvertでMDからPDFへ素早く変換する方法
READMEファイル、会議の議事録、短いレポート、ドキュメントページなど、シンプルなドキュメントの場合、CocoConvertの[MD-to-PDF変換ツール](/convert/md-to-pdf)は、ソフトウェアのインストールやコマンドラインの知識を必要とせずに、その仕事をこなします。 プロセスは3つのステップです。まず、.mdファイルを変換ツールにドラッグするか、ファイルピッカーをクリックしてアップロードします。最大25MBのファイルがサポートされており、これはMarkdownドキュメントの大部分をカバーします（埋め込み画像のない10,000語のドキュメントは通常100KB未満です）。次に、「変換」をクリックします。このツールは、言語ヒント付きのフェンスコードブロック、パイプテーブル、インラインHTMLを含むCommonMarkおよびGFM構文をパースします。最後に、結果のPDFをダウンロードします。 デフォルトの出力は、A4ページサイズ、20mmの余白、11ptの読みやすいサンセリフ体本文フォント、そしてコードブロックのシンタックスハイライトを使用しています。見出しは24pt (H1) から13pt (H6) までスケールします。これらのデフォルト設定は、ほとんどのドキュメントやレポートに適しています。 正直なところ、ここには限界があります。CocoConvertは現在、カスタムCSSの挿入、YAMLフロントマターの処理、またはLaTeXの数式表記（例：`$E = mc^2$`はレンダリングされた数式ではなく、そのままのテキストとして表示されます）をサポートしていません。もしあなたのドキュメントに数式が含まれている場合、LaTeXバックエンドを持つPandocや、MathJax対応のコンバーターのようなツールを使う方が良い結果が得られるでしょう。同様に、改ページを正確に制御したい場合（例えば、各H2の前に強制的に新しいページを挿入するなど）は、コマンドラインのワークフローの方がより多くの制御が可能です。
変換前にMarkdownファイルを準備する
変換前の数分間の準備が、最も一般的な出力の問題を防ぎます。 **見出し構造を確認しましょう。** 複数のH1見出しを持つドキュメントは、PDFで複数の行が同じ大きなフォントサイズを共有することになり、構造化されていないように見えます。ドキュメントのタイトルには単一のH1を使用し、主要なセクションにはH2、サブセクションにはH3を使用してください。ほとんどのMarkdownリンター（markdownlintルールMD025）は、複数のH1を自動的にフラグ付けします。 **画像を慎重に扱ってください。** .mdファイルが``のような相対パスで画像を参照している場合、ファイルを単独でWebベースのコンバーターにアップロードすると、それらのパスは壊れてしまいます。画像をMarkdown内にBase64データURIとして直接埋め込むか、公開されている画像への絶対URL（例：``）を使用してください。5〜10枚の画像を含むドキュメントの場合、手動でBase64に変換するのは面倒です。コンバーターがアーカイブのアップロードをサポートしている場合は、.mdファイルを画像フォルダと一緒にzip圧縮することを検討するか、画像が多いドキュメントにはPandocのようなローカルツールを使用してください。 **サポートされていない構文を削除または置換してください。** ファイルがHugoのショートコード、Obsidianのコールアウト（`> [!NOTE]`）、またはその他の非標準拡張機能を使用している場合、アップロードする前にそれらを削除するか、標準のMarkdown相当のものに変換してください。Obsidianのコールアウトはシンプルなブロッククォートに置き換えられます。Hugoの`{{< figure >}}`タグは標準の`![]()`画像参照に置き換えられます。 **改行コードを確認しましょう。** WindowsスタイルのCRLF改行コードは、一部のパーサーで段落のスペーシング問題を引き起こすことがあります。ファイルを素早く`dos2unix`変換にかけるか、エディターからLF改行で保存することで、この変数を排除できます。
代わりにPandocを使うべき時（またはCocoConvertと併用する時）
Pandocは、MarkdownからPDFへの変換を、どのWebツールよりもはるかに高い設定可能性で処理する、無料のオープンソースのコマンドラインツールです。いつそれを使うべきかを知っていれば、時間を節約できます。 PandocとLaTeXディストリビューション（Linux/MacにはTeX Live、WindowsにはMiKTeX）をインストールしてから、次のコマンドを実行します。 ``` pandoc report.md -o report.pdf --pdf-engine=xelatex -V geometry:margin=1in -V fontsize=12pt ``` この1つのコマンドで、`report.md`を1インチの余白と12ptの本文テキストを持つPDFに変換します。`--toc`を追加すると、目次が自動的に生成されます。`-V`フラグはLaTeXテンプレートに変数を渡します。`mainfont`、`monofont`、`papersize`、`linestretch`など、何十ものパラメータを設定できます。 数式が多いドキュメントには、XeLaTeXを搭載したPandocが適切なツールです。LaTeXの数式をネイティブにレンダリングします。カスタムの表紙、ヘッダーとフッター、または正確なウィドウ/オーファン制御が必要なドキュメントには、LaTeXテンプレートが完全なタイポグラフィ制御を提供します。 トレードオフはセットアップ時間です。TeX Liveのインストールには、3〜5GBのディスクスペースと15〜30分かかります。LaTeXテンプレートのエラーをデバッグするには、LaTeX構文の知識が必要です。締め切り前の午後11時に一度きりのREADME変換を行うなら、CocoConvertの方が速い方法です。四半期ごとに発行される200ページの技術マニュアルの場合、Pandoc + LaTeXワークフローに投資することは、2版目か3版目以降に報われます。 これらのツールは相互に排他的ではありません。合理的なワークフローとしては、CocoConvertを素早いプレビューやドラフトの共有に使い、最終版は洗練されたテンプレートを使ってPandocで処理し、公開用の出力を作成するという方法があります。
よくある変換問題のトラブルシューティング
**テーブルがプレーンテキストとして表示される。** これは通常、コンバーターがGFMパイプテーブルをサポートしないCommonMark専用のパーサーを使用していることを意味します。テーブルの構文が正しいことを確認してください。すべての行に同じ数のパイプ文字が必要であり、区切り行（ダッシュのある行）が存在している必要があります。コンバーターがGFMをサポートしていれば、正しくフォーマットされたテーブルはレンダリングされます。そうでない場合は、サポートするツールに切り替えるか、テーブルをHTMLの`<table>`ブロックに変換してください。ほとんどのMarkdownパーサーはこれを変更せずに通過させます。 **コードブロックのインデントが失われる。** これはフォントの問題で、PDFレンダラーがコードにプロポーショナルフォントにフォールバックしたためです。コンバーターが`<pre>`要素に等幅フォントを適用しているか確認してください。Pandocを使用している場合は、特定の等幅フォントを強制するために`--variable monofont='Courier New'`を追加してください。 **画像が欠落している。** ほとんどの場合、パス解決の問題です。上記の準備セクションを参照してください。画像URLがHTTP 200を返し、認証の背後にないことを確認してください。 **PDFにページ番号がない。** Webベースのコンバーターは通常、ヘッダーやフッターを追加しません。これは、カウンターサポート付きのCSS `@page`ルールが必要であり、すべてのPDFエンジンがこれを一貫して処理するわけではないためです。ページ番号が必要な場合は、LaTeXバックエンドを持つPandocがデフォルトで追加するか、Adobe AcrobatでPDFを後処理できます（ツール > PDFを編集 > ヘッダーとフッター > 追加）。 **コードブロックの長い行がページ余白からはみ出す。** これは改行の問題です。CSSでは`pre { white-space: pre-wrap; }`で修正できますが、ほとんどのWebコンバーターではCSSを挿入できません。回避策は、変換前にソースファイル内の長い行を手動で折り返し、行を80〜90文字未満に保つことです。
公開（パブリッシング）に適した設定を選ぶ
「公開（パブリッシング）」という言葉は幅広い出力をカバーしており、適切な設定はそれぞれで大きく異なります。 **Webまたはメール配信の場合：** A4またはUSレターサイズのページ、20〜25mmの余白、11〜12ptの本文テキスト。受信者のマシンで一貫したレンダリングを保証するために、すべてのフォントを埋め込んでください。ファイルサイズが重要である場合（例えば、10MBの制限があるメールに添付する場合など）は、大きな画像ファイルをフル解像度で埋め込むのは避けてください。Markdownソースに含める前に、画像を150〜200 DPIにリサイズしてください。 **印刷の場合：** ラスタ画像には少なくとも300 DPIを使用してください。ドキュメントをホチキス止めしたり製本したりする場合は、製本を考慮して余白を広く（25〜30mm）する必要があります。プロのサービスを通じて印刷する場合は、PDF/X-1aまたはPDF/X-4への準拠が必要かどうかを尋ねてください。ほとんどのWebコンバーターは標準のPDF 1.4または1.5を生成し、印刷制作用のPDF/Xバリアントではありません。 **電子書籍リーダーやタブレットの場合：** 実際にPDFが適切なフォーマットであるかどうかを検討してください。EPUBは小さな画面でリフロー可能なテキストをより良く処理します。とはいえ、PDFが必要な場合は、A4ページを縮小するよりも、より小さなページサイズ（トレードペーパーバックに似た約6×9インチ）の方がタブレットでの読書体験が向上します。 **技術ドキュメントポータル向け：** 多くのドキュメントプラットフォーム（ReadTheDocs、GitBook、Docusaurus）は、ChromiumまたはWeasyPrintをベースにした独自のPDFエクスポートパイプラインを持っています。もしすでにこれらのプラットフォームのいずれかを使用しているなら、個々の.mdファイルを個別に変換するよりも、ネイティブのエクスポートの方がサイトのテーマやナビゲーション構造をより尊重します。 洗練されたレポートの共有、仕様書の配布、READMEのアーカイブなど、ほとんどの日常的な公開ニーズには、[CocoConvertのMD-to-PDFツール](/convert/md-to-pdf)をデフォルト設定で直接変換するだけで、1分以内にクリーンで読みやすい結果が得られます。