開発者向け

執筆・検証: MD Converter編集部

GitHub の README を PDF にする方法｜バッジ・コードブロックも崩さず変換

GitHubのREADME.mdをそのままPDF化する手順を解説。バッジ画像・コードブロック・目次リンクが崩れる原因と、社内提出や印刷用にきれいに整える方法をまとめます。

この記事でわかること

  • GitHubのREADME.mdをそのままPDF化する手順
  • バッジ画像・相対リンクが壊れる原因と直し方
  • コードブロックやシンタックスハイライトを崩さず出力する方法
  • 社内共有・監査提出向けに印刷しやすいPDFに整えるコツ

READMEはGitHub上で見る分には問題なくても、そのままPDFにするとバッジ画像が読み込まれない、相対リンクが壊れる、コードブロックが見切れるといった問題が起きがちです。社内向けの提出資料や監査資料としてリポジトリのドキュメントをPDF化したいとき向けに、崩れにくい変換手順をまとめます。

手順：README.md をPDFにする

  1. GitHubのリポジトリから README.md の生のテキスト（Raw）を開くか、ローカルのファイルをエディタで開きます。
  2. .mdとして保存し、GitHub Flavored Markdownに対応したPDF変換器へ読み込みます。
  3. プレビューでバッジ画像・見出し構成・コードブロックの見え方を確認します。
  4. 目次が必要なら見出しから生成し、余白やフォントを印刷用CSSまたは変換器の設定で調整します。
  5. 「PDFで保存」で書き出します。

README特化ではない、Markdown全般をPDFへ変換する基本的な流れはMarkdownを印刷・PDFに変換する方法で詳しく解説しています。

バッジ画像が表示されない場合

READMEの先頭によくある ![Build Status](https://img.shields.io/...) のようなバッジ画像は、外部サービスへのリクエストによって表示されています。ネットワークの状態やアクセス制限によっては、PDF化のタイミングで画像が読み込まれず、空白または壊れたアイコンとして表示されることがあります。バッジが多いREADMEでは、PDFとして配布する前に一度プレビューを開き、すべての画像が読み込まれているか確認してください。読み込まれない場合は、時間を置いて再試行するか、提出用途であればバッジ行を削除したコピーを別途用意するのが確実です。

相対リンクが壊れる場合

READMEの中には [使い方](./docs/usage.md) のようなリポジトリ内の相対パスでリンクされている箇所がよくあります。これらはGitHub上でリポジトリ構造を前提に解決されているため、単体のMarkdownテキストとしてPDF化するとリンク切れになります。PDFの用途がドキュメントの構造を伝えることであれば、リンク切れ自体は許容範囲のことが多いですが、参照先を明示したい場合はリンクをGitHubの絶対URL（https://github.com/ユーザー名/リポジトリ名/blob/main/docs/usage.md）に置き換えてから貼り付けると確実です。

コードブロックとシンタックスハイライト

READMEにはインストール手順やAPIの使用例として、```bash や ```js などのコードブロックが多く含まれます。長いコマンドや横に長いコードは、PDFの用紙幅に収まらず折り返しや見切れが起きることがあるため、プレビューで確認し、必要であれば用紙をA4縦から横向きに変更する、印刷用CSSでコードの文字を少し小さくするなどの調整をおすすめします。

目次（TOC）を使うと読みやすい

READMEは見出しの階層が深くなりがち（インストール・使い方・API・コントリビューション…）なため、PDF化する際は目次機能をオンにしておくと、紙やPDFビューアで該当セクションにすぐアクセスできるようになります。目次の作り方は Markdown PDF に目次（TOC）を付ける方法 で詳しく解説しています。

複数リポジトリのREADMEをまとめて配布したい場合

社内の複数プロジェクトのREADMEを1つの資料にまとめたい場合は、各READMEの前に # プロジェクト名 の見出しを追加してから連結すると、目次機能でプロジェクトごとに区切られた一覧PDFが作れます。

よくある質問（FAQ）

Q. READMEのバッジ画像がPDFで表示されません

バッジは外部サービスから読み込まれる画像のため、通信状況によって表示されないことがあります。プレビューで読み込みを確認し、それでも表示されない場合は再試行するか、提出用にバッジ行を削除したコピーを用意してください。

Q. READMEのリンクをクリックしても別のページに飛べません

リポジトリ内の相対パスで書かれたリンクは、単体のMarkdownとしてPDF化すると解決できません。GitHubの絶対URLに置き換えてから変換すると、リンク切れを防げます。

Q. コードブロックが用紙からはみ出します

長いコマンドや横長のコードは折り返されるか見切れることがあります。用紙を横向きにする、印刷用CSSでコードのフォントサイズを小さくするといった調整を試してください。

Q. READMEをWord形式で提出する必要がある場合は？

相手が編集する場合は、Pandocなどで同じMarkdownをdocx形式へ変換できます。固定して配布するPDFと、編集用のdocxを使い分けてください。

まとめ

GitHubのREADMEをPDF化する際は、バッジ画像の読み込みと相対リンクの解決が崩れやすいポイントです。変換前にプレビューで確認し、必要に応じてバッジや相対リンクを整理してから書き出すと、提出用途でも安心して使えるPDFになります。

GitHubのREADMEをPDFに変換する

関連記事