執筆・検証: MD Converter編集部
Markdownで画像が表示されない原因と対処法
Markdownの画像が表示されない原因を、パス、ファイル名、URL、権限、対応形式、HTML・PDF変換の違いに分け、症状別の確認手順と直し方を解説します。
最初に画像の参照先を確認する
Markdownで画像が表示されないときは、記法そのものより、画像ファイルの場所やURLが正しく解決できていないケースが多くあります。まず、次の基本形になっているか確認します。
!を忘れると通常のリンクになり、角括弧や丸括弧が全角だと画像として解釈されません。画像の説明、参照先の順に書き、前後へ余計な引用符を入れないようにします。
原因1：相対パスの基準が違う
images/screen.pngのような相対パスは、Markdownファイルや表示ページなど、処理系が基準とする場所から画像を探します。次の構成なら、Markdownから見たパスはimages/screen.pngです。
project/
├─ manual.md
└─ images/
└─ screen.png
画像が1つ上の階層にあるなら../screen.pngが必要です。ただし、オンライン変換ツールへMarkdownだけを読み込んだ場合、手元のフォルダ構成までは渡されません。エディタでは見えるのに変換後のHTMLやPDFで消える場合は、相対パスの画像を変換先が参照できていない可能性があります。リンクが開かない場合も同じようにパス指定のミスが原因になりやすいため、Markdownのリンクが開かない原因と正しい書き方も参考にしてください。
原因2：ファイル名の大文字と小文字が違う
Screen.pngとscreen.pngは、環境によって別のファイルとして扱われます。手元では表示できても、Webサーバーへ公開すると消えることがあります。拡張子を含めて実際のファイル名と完全に一致させます。
日本語、空白、#、?などを含むファイル名も、URL化したときに問題を起こす場合があります。画像名はsetup-screen-01.pngのような半角英数字とハイフンにそろえると安全です。
原因3：外部URLへアクセスできない
Web上の画像は絶対URLで指定できます。
URLをブラウザの別タブで直接開き、画像単体が表示されるか確認します。ログインが必要なURL、一時的な共有URL、期限付きURL、社内ネットワークからしか開けないURLは、閲覧者やPDF変換処理からアクセスできないことがあります。
また、画像を置いているサーバーが外部サイトからの参照を禁止している場合もあります。配布文書では、後から消える可能性がある外部URLより、画像をHTMLへ埋め込む方法が安定します。
原因4：画像形式に対応していない
PNG、JPEG、GIF、WebPなど一般的な形式でも、利用するブラウザやPDF生成環境によって対応状況が異なります。HEICや特殊なSVGは、プレビューできても保存結果が変わる場合があります。
表示できないときはPNGまたはJPEGへ変換して試します。SVGでは、外部フォント、スクリプト、別ファイルへの参照が含まれていないかも確認してください。拡張子だけを.pngへ変更しても形式は変換されないため、画像編集ソフトなどで正しく書き出します。
原因5：ファイルやURLへのアクセス権がない
file:///...で始まるローカルパスや、C:\Users\...のようなPC内の絶対パスは、作成者の環境でしか開けません。そのままHTMLを送っても相手のPCには同じ画像がないため表示されません。
GitHubなどの非公開リポジトリにある画像も、ログインしている本人には見えて、受け取った人には見えないことがあります。シークレットウィンドウや別端末で開くと、権限の問題を切り分けられます。
HTMLでは見えるのにPDFで消える場合
PDF保存を開始した時点で画像の読み込みが終わっていないと、空白のまま出力される場合があります。プレビューですべての画像が表示されてから保存してください。大きな画像が多数ある場合は、ファイルサイズを小さくして再確認します。
背景画像として指定した画像は、印刷設定で「背景のグラフィック」が無効だと出力されないことがあります。本文に必要な図はCSS背景ではなく、通常の画像要素として配置する方が確実です。
1ファイルで安全に配布する方法
HTMLと画像を別々に渡すと、フォルダ構成が変わっただけで相対パスが切れます。1ファイルで配布する必要がある場合は、画像をData URLとしてHTMLへ埋め込める変換方式を選びます。ただし、埋め込み画像はHTMLの容量を増やすため、解像度と圧縮率を先に調整してください。
ただし、埋め込み画像が多いほどHTMLの容量は大きくなります。必要な解像度へ縮小し、機密画像や個人情報が含まれていないか確認してから配布してください。
切り分けチェックリスト
1枚だけ表示されない場合
同じ文書内でほかの画像が表示できているなら、変換機能全体ではなく、その画像固有の問題と考えられます。表示できる画像と、拡張子、ファイル容量、ファイル名、URLの公開範囲を比較します。画像URLの末尾が.pngに見えても、実際にはログインページやHTMLを返している場合があるため、別タブで開いて画像単体が表示されるか確認してください。
すべての画像が表示されない場合
すべて消える場合は、相対パスの基準やローカルファイルへのアクセス制限が原因である可能性が高くなります。Markdownだけを別の環境へ渡しても、同じフォルダにある画像は自動では付いてきません。画像フォルダも同じ相対構造で渡すか、変換前に画像を文書へ埋め込んでください。
プレビューでは見えるのに保存後だけ消える場合
保存直前に画像が完全に表示されているか、大容量画像の読み込みが続いていないかを確認します。一度PDFを保存して開き直し、先頭だけでなく全ページを確認してください。外部URLの画像は後日の再生成時に消える可能性もあるため、長期保存する設計書や報告書では埋め込み画像が安全です。
の形になっている- ファイル名と拡張子の大文字・小文字が一致している
- URLを単独で開ける
- 閲覧者にもアクセス権がある
- PNGまたはJPEGへ変換しても再現するか確認した
- HTMLを移動した後も画像が表示される
- PDF保存前に画像の読み込みが完了している
上から順に確認すれば、記法、場所、権限、形式、変換処理のどこで画像が消えているかを判断できます。
画像が一部だけ表示されない場合は、表示できる画像とファイル名、形式、容量、参照方法を比較します。すべて表示されない場合は、基準パスや変換ツールの画像対応を先に疑うと効率的です。
よくある質問（FAQ）
Q. GitHubでは表示される画像が、PDFにすると消えるのはなぜですか？
GitHubはリポジトリを基準に相対パスを解決し、ログイン中のセッションを通じて非公開リポジトリ内の画像も表示できます。一方、ブラウザ上のPDF変換処理は、そのリポジトリ構成やログイン状態を引き継ぎません。誰でも直接開ける公開URLへ切り替えるか、画像を文書へ埋め込んでから変換してください。
Q. 画像の代替テキスト（alt）は空のままでもよいですか？
画像の目的が伝わる簡潔な代替テキストを書いておくことをおすすめします。代替テキスト自体が参照切れを直すわけではありませんが、画像を読み込めない環境でも内容が伝わり、アクセシビリティの面でも役立ちます。