コードハイライトを保持した Markdown PDF 変換: 色を残す方法
Markdown を PDF に変換するときにシンタックスカラーを残すには、Markdown の記述だけでなく、レンダリングから PDF 出力までの経路全体を確認する必要があります。コードブロックには言語識別子が必要で、レンダラーはシンタックスハイライトに対応していなければなりません。さらに、PDF 書き出し時に背景、フォント、折り返しを維持する設定が必要です。
単発の文書なら、MarkdownToImage の Markdown to PDF ツールが最短です。Markdown を貼り付けるかアップロードし、プレビューを確認してテーマと文書幅を選び、PDF を書き出します。自動化や細かな調整が必要な場合は、md-to-pdf、VS Code Markdown PDF、または Pandoc でハイライト設定を明示してください。
多くの失敗には再現できる原因があります。まず次の 3 点を確認します。
- コードフェンスに言語識別子がない。 3 つのバッククォートだけで始めたブロックは、単なる整形済みテキストとして扱われます。開始フェンスの直後に
javascript、python、bashなど、対応する言語名を指定してください。 - 背景グラフィックが無効になっている。 シンタックステーマは文字色だけでなくコードブロックの背景色にも依存します。ブラウザーや Chromium で印刷背景を無効にすると、トークンの色が残っても背景だけ消えることがあります。
- プレビューと PDF でレンダリング設定が異なる。 レンダラー、テーマ、フォント、ページ幅、印刷用 CSS の違いによって、色や行の折り返しが変わります。長い文書を処理する前に、小さな既知のサンプルで PDF とプレビューを比較してください。
「PDF だから色が消える」と考えるより、この 3 点を切り分ける方が有効です。PDF 自体は色付きテキストを保持できます。重要なのは、ファイルを書き出す直前に変換経路が何を描画していたかです。
本文全体を変換する前に、同じ文書へ次のブロックを貼り付けて一度書き出してください。
const palette = ["cyan", "amber", "coral"];
function renderStatus(format) {
return `${format}: ${palette.length} colors`;
}
console.log(renderStatus("PDF"));
プレビューと PDF の両方で、キーワードの色、文字列の色、コードブロックの背景、等幅フォント、テンプレートリテラル行の折り返しという 5 点を確認します。どれか 1 つでも変わる場合は、先にテーマまたは書き出し設定を修正してください。
この Web ツールは、サーバー側の Chromium 環境で PDF を生成します。シンタックスハイライト付きコードブロック、KaTeX 数式、Mermaid 図、表、埋め込み画像、タスクリストに対応しています。プレビューを基準にテーマ、フォント、文書幅を設定し、書き出した後にテスト用コードブロックを比較してください。
現在の無料書き出しには透かしが入ります。サインインした無料アカウントには、合計 5 回分の透かしなし書き出しが付与されます。料金や上限は変わる可能性があるため、継続利用を決める前に現在の変換ページを確認してください。
ローカルツールを導入せず、整った PDF をすぐ作りたい場合に向いています。
md-to-pdf は Marked で Markdown を変換し、highlight.js でコードを色分けし、Puppeteer と Chromium を使って PDF を生成します。既定のハイライトスタイルは GitHub で、別のスタイルも明示的に選べます。
md-to-pdf input.md --highlight-style github --pdf-options '{ "printBackground": true }'
同じ文書をスクリプトや CI で繰り返し生成する場合に適しています。暗いテーマで背景色を使う場合は、printBackground を有効にしてください。信頼できない Markdown は、無害化せずに処理しないでください。公式文書でもセキュリティ上の注意点として説明されています。
Markdown PDF 拡張機能は Chromium ベースのブラウザーで書き出し、コードフェンスのシンタックスハイライトには highlight.js を使います。ハイライトは既定で有効で、テーマは markdown-pdf.highlightStyle で個別に指定します。
"markdown-pdf.highlightStyle": "github.css"
設定を変更したら、もう一度小さなテストブロックを書き出します。この拡張機能は現在 highlight.js v11 を使用しているため、古いテーマ名が変更済み、または利用できない場合があります。過去の名前を前提にせず、現行のスタイルを選んでください。
Pandocは、言語名を指定したコードフェンスの色分けに Skylighting を使います。現行版では --syntax-highlighting が利用でき、従来の --highlight-style という指定は非推奨です。
pandoc input.md -o output.pdf --syntax-highlighting=pygments
kate、tango、zenburn、breezeDark などの組み込みスタイルに加え、独自の JSON .theme ファイルも使えます。Pandoc テンプレート、引用文献、LaTeX ベースの出版フローをすでに使っている場合に最も適しています。ただし、PDF エンジンとテンプレートも最終レイアウトに影響するため、フォントと改ページは別途テストしてください。
すでにレンダリングされた Markdown ページをブラウザーから PDF に印刷する方法も使えますが、結果はそのページの印刷用 CSS に左右されます。色と背景を保持するサイトもあれば、紙向けに単純化するサイトもあります。印刷ダイアログで背景グラフィックを有効にし、改ページを確認して、テストブロックを比較してください。
見た目が完成しているページを一度だけ保存する用途には便利です。一方、HTML、CSS、ブラウザーのバージョン、印刷設定まで管理しない限り、再現性のあるビルド経路にはなりません。
- すべてのコードフェンスに言語識別子を付ける。
- 印刷される可能性がある文書では、明るくコントラストの高いテーマを優先する。
- 選んだテーマが背景色を必要とする場合は、背景グラフィックを有効にする。
- 既知の等幅フォントを使い、書き出し環境でも利用できることを確認する。
- 最終的なページ幅で長い行を確認し、画面上の折り返しが A4 や Letter と同じだと決めつけない。
- 長い報告書の前に、小さな JavaScript サンプルを書き出す。
- ユーザーや外部システムから受け取った Markdown は、ローカル変換ツールへ渡す前に無害化する。
- 最終 PDF を一度開き、色、選択可能なテキスト、リンク、画像、改ページを確認する。
ツールを広く比較するなら、Markdown を PDF に変換する 5 つの方法を参照してください。繰り返し使える処理を組む場合は、CLI、Pandoc、CI を使った一括変換へ進んでください。
プレビューでは色が付くのに、PDF では単色になるのはなぜですか？
まず背景グラフィックを有効にします。次に、書き出し処理がプレビューと同じテーマとレンダラーを使っているか確認してください。印刷用 CSS がトークンの色を上書きしている場合もあります。
印刷向け PDF にはどのテーマが適していますか？
最初は GitHub などの明るいテーマを試してください。カラーでもグレースケールでも読みやすい傾向があります。画面閲覧専用なら暗いテーマも使えますが、共有前に背景とコントラストを確認してください。
行番号も残せますか？
選んだレンダラーとテーマが行番号を追加する場合に限られます。標準のコードフェンスに行番号は含まれません。確実に揃えるには、自分で管理できる CLI またはスタイルシートを使い、ページ幅もテストしてください。
シンタックスハイライトを失わずに複数ファイルを一括変換できますか？
できます。Web に近いハイライトを安定して得るには Chromium ベースの CLI を使うか、Pandoc でシンタックステーマを明示します。将来のビルド結果が不意に変わらないよう、CI ではツールとテーマのバージョンを固定してください。
MarkdownToImage の Markdown to PDF 変換ツールを開き、このガイドの小さな JavaScript ブロックを貼り付け、PDF を 1 つ書き出してください。プレビューとファイルを並べ、色、背景、フォント、折り返しが一致することを確認します。一致したら、サンプルを実際の文書に置き換えてください。