Markdown（マークダウン）はシンプルな記法で文章を構造化できるツールとして人気ですが、画像を埋め込む方法がよくわからないという声をよく耳にします。
この記事では、Markdownで画像を正しく埋め込む基本構文から、相対パス・URL指定・代替テキストの使い方や実用上の注意点まで、初心者にもわかりやすく丁寧に解説します。
画像埋め込みの基本構文
基本的な記法
Markdownでの画像埋め込みは、シンプルで覚えやすい構文を使用します：
基本構文：
構文の要素説明：
!：画像を表示することを示す記号[代替テキスト]：画像が表示されない場合に表示される説明文(画像URLまたはパス)：画像ファイルの場所を指定
外部URLを使った画像表示
インターネット上の画像を表示する例：
URLを使用する際のポイント：
- 画像のダイレクトリンクを使用する
https://で始まる安全な接続を推奨- 画像の著作権や利用許可を確認する
- リンク切れのリスクを考慮する
ローカルファイルの相対パス指定
同じフォルダ内の画像：
フォルダ構成を考慮した相対パス：
project/
├── README.md
├── docs/
│ └── guide.md
└── images/
├── logo.png
├── screenshot1.jpg
└── icons/
└── user.svg
上記構成での画像指定例：
<!-- README.mdから画像を参照 -->
<!-- docs/guide.mdから画像を参照 -->
代替テキストの重要性
代替テキストの役割：
- アクセシビリティ向上：スクリーンリーダーで読み上げられる
- SEO効果：検索エンジンが画像内容を理解する手がかり
- 表示エラー時の説明：画像が読み込めない場合の代替情報
- コンテキストの明確化：画像の内容や目的を説明
良い代替テキストの例：
<!-- ❌ 悪い例：情報が不十分 -->
<!-- ✅ 良い例：内容が具体的 -->
Markdownでは![]()の形式で画像を簡単に埋め込めます。代替テキストは画像が表示されないときの説明になります。次に、実際の活用例を詳しく見ていきましょう。
実用例：様々な場面での画像埋め込み
GitHub READMEでの活用
プロジェクトロゴの表示：
# My Awesome Project
## 概要
このプロジェクトは...
バッジとロゴの組み合わせ：
デモGIFの埋め込み：
## デモンストレーション
上記のGIFは実際のアプリケーションの動作を示しています。
使用前後の比較：
## 機能改善の効果
| Before | After |
|--------|-------|
|  |  |
パフォーマンスが大幅に向上しました。
技術文書・マニュアルでの活用
インストール手順での画面キャプチャ：
## インストール手順
### ステップ1: ダウンロード
公式サイトからインストーラーをダウンロードします。
### ステップ2: インストール実行
ダウンロードしたファイルを実行し、以下の画面が表示されることを確認してください。
### ステップ3: 設定
設定画面で必要な項目を入力します。
API仕様書での例示：
## レスポンス例
### 成功時のレスポンス
```json
{
"status": "success",
"data": {...}
}
エラー時の画面表示
**システム構成図の掲載：**
```markdown
## システムアーキテクチャ
### 各コンポーネントの説明
2. 依存関係のインストール
npm install
**比較・検証結果の表示：**
```markdown
## パフォーマンス比較結果
### 従来手法との速度比較
### メモリ使用量の比較
チュートリアル・ハウツー記事
ステップバイステップの解説：
# Photoshopで写真を加工する方法
## 準備: 画像を開く
まず、Photoshopを起動し、加工したい画像を開きます。
## ステップ1: レイヤーの複製
背景レイヤーを右クリックして「レイヤーを複製」を選択します。
## ステップ2: フィルターの適用
「フィルター」メニューから適用したいエフェクトを選択します。
## 完成イメージ
ヒント： パスはMarkdownファイルから見た位置に対して相対指定する必要があります。
画像の配置パターンを知っておくと、資料やブログに視覚的なアクセントを加えることができます。
より高度な書き方とオプション
HTMLタグを使ったサイズ調整
Markdownの基本構文では画像サイズを調整できませんが、HTMLタグを併用することで詳細な制御が可能です：
基本的なサイズ指定：
<!-- 幅を300pxに指定 -->
<img src="https://example.com/image.jpg" alt="説明" width="300">
<!-- 高さを200pxに指定 -->
<img src="./images/chart.png" alt="グラフ" height="200">
<!-- 幅と高さの両方を指定 -->
<img src="./logo.png" alt="ロゴ" width="150" height="50">
<!-- パーセンテージでの指定 -->
<img src="./screenshot.png" alt="画面" width="80%">
レスポンシブ対応：
<!-- 最大幅を設定してレスポンシブに -->
<img src="./large-image.jpg" alt="大きな画像" style="max-width: 100%; height: auto;">
<!-- CSSクラスを使用 -->
<img src="./responsive-image.png" alt="レスポンシブ画像" class="responsive-img">
画像の配置とレイアウト
中央寄せ：
<p align="center">
<img src="./logo.png" width="200" alt="ロゴ">
</p>
<!-- または、divを使用 -->
<div align="center">
<img src="./banner.jpg" alt="バナー" width="600">
</div>
左右の配置：
<!-- 左寄せ -->
<p align="left">
<img src="./left-image.png" alt="左の画像" width="250">
</p>
<!-- 右寄せ -->
<p align="right">
<img src="./right-image.png" alt="右の画像" width="250">
</p>
画像の横並び：
<p align="center">
<img src="./image1.png" alt="画像1" width="200">
<img src="./image2.png" alt="画像2" width="200">
<img src="./image3.png" alt="画像3" width="200">
</p>
<!-- テーブルを使った整列 -->
<table>
<tr>
<td><img src="./before.png" alt="変更前" width="300"></td>
<td><img src="./after.png" alt="変更後" width="300"></td>
</tr>
<tr>
<td align="center">変更前</td>
<td align="center">変更後</td>
</tr>
</table>
画像にキャプションを付ける
HTMLのfigureタグを使用：
<figure>
<img src="./chart.png" alt="売上グラフ" width="500">
<figcaption>図1: 2024年第1四半期売上推移</figcaption>
</figure>
<figure align="center">
<img src="./architecture.svg" alt="システム構成図" width="600">
<figcaption><strong>システム全体のアーキテクチャ</strong></figcaption>
</figure>
テーブルを使ったキャプション：
<table>
<tr>
<td><img src="./demo.gif" alt="デモ動画" width="400"></td>
</tr>
<tr>
<td align="center"><em>アプリケーションの動作デモンストレーション</em></td>
</tr>
</table>
画像のリンク化
画像をクリックして拡大表示：
[](./full-size-image.jpg)
画像をクリックして外部サイトへ：
[](https://github.com/username/repo)
HTMLでの詳細制御：
<a href="https://example.com" target="_blank">
<img src="./clickable-banner.png" alt="バナー" width="300">
</a>
動的な画像表示
ライト/ダークテーマ対応：
<!-- ライトテーマ用 -->
<img src="./logo-light.png" alt="ロゴ" width="200" class="light-theme">
<!-- ダークテーマ用 -->
<img src="./logo-dark.png" alt="ロゴ" width="200" class="dark-theme">
GitHubの自動テーマ切り替え：
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./logo-dark.png">
<source media="(prefers-color-scheme: light)" srcset="./logo-light.png">
<img alt="ロゴ" src="./logo-light.png" width="200">
</picture>
注意点： 一部のMarkdownビューア（Qiita、Zennなど）はHTMLタグの利用制限があります。
デザイン調整が必要な場合は、HTMLとの併用が効果的です。ただしツールごとの対応状況に注意しましょう。
プラットフォーム別の画像表示対応
主要プラットフォームの対応状況
画像表示の挙動はプラットフォームによって大きく異なります：
| プラットフォーム | ローカル画像 | 外部URL画像 | HTMLタグ | 画像アップロード機能 |
|---|---|---|---|---|
| GitHub | ◯（公開リポジトリ） | ◯ | 一部制限あり | ◯（ドラッグ&ドロップ） |
| VSCode Preview | ◯ | ◯ | ◯ | – |
| Qiita | △（要アップロード） | ◯ | 制限あり | ◯（専用UI） |
| Zenn | △（要アップロード） | ◯ | 制限あり | ◯（専用UI） |
| GitLab | ◯ | ◯ | 一部制限あり | ◯ |
| Notion | ◯ | ◯ | ×（独自記法） | ◯ |
| Obsidian | ◯ | ◯ | ◯ | ◯ |
GitHub固有の機能と注意点
GitHub Issues/PRでの画像貼り付け：
<!-- ドラッグ&ドロップで自動的に以下の形式になる -->
GitHub Pagesでの相対パス：
<!-- GitHub Pagesでは以下の形式を推奨 -->
<!-- または通常の相対パス -->
プライベートリポジトリの画像：
<!-- プライベートリポジトリの画像は外部からアクセス不可 -->
<!-- 公開したい場合は別途ホスティングが必要 -->
ブログプラットフォームでの最適化
Qiitaでの画像利用：
<!-- Qiitaエディタで画像をアップロード後 -->
Zennでの画像管理：
<!-- Zennの画像アップロード機能を使用 -->
<!-- または外部ホスティング -->
画像ホスティングサービスの活用
主要な画像ホスティングサービス：
GitHub（無料、制限あり）
<!-- GitHub Issues/Discussionsでアップロード -->
Imgur（無料、商用利用注意）
Cloudinary（無料枠あり）
AWS S3 + CloudFront（有料、高性能）
トラブルシューティングと解決策
よくある問題と対処法
問題1：画像が表示されない
原因と解決策：
<!-- ❌ よくある間違い：パスが正しくない -->
 <!-- ファイルが存在しない -->
<!-- ✅ 正しい例：正確なパスを指定 -->
 <!-- 正しい相対パス -->
 <!-- 有効なURL -->
デバッグ方法：
# ファイルの存在確認
ls -la images/
ls -la ./images/image.png
# 相対パスの確認
pwd # 現在のディレクトリ
find . -name "*.png" # png画像の検索
問題2：相対パスが環境によって異なる
解決策：
<!-- 環境に依存しない絶対パス（GitHub）の使用 -->
<!-- または、各環境用のパスを用意 -->
<!-- 開発環境 -->
<!-- 本番環境 -->
問題3：画像のサイズが大きすぎる
最適化の方法：
<!-- CSSでサイズ制限 -->
<img src="./large-image.png" alt="大きな画像" style="max-width: 100%; height: auto;">
<!-- 幅を制限 -->
<img src="./large-image.png" alt="大きな画像" width="600">
画像ファイルの最適化：
# ImageMagickを使った最適化
convert large-image.png -resize 800x600 optimized-image.png
# 品質を指定した圧縮
convert large-image.jpg -quality 85 compressed-image.jpg
問題4：外部URLの画像が読み込めない
チェックポイント：
<!-- HTTPSを使用しているか確認 -->
 <!-- ✅ 安全 -->
 <!-- ❌ 非安全 -->
<!-- 画像の直接リンクか確認 -->
 <!-- ✅ 直接リンク -->
 <!-- ❌ HTMLページ -->
パフォーマンス最適化
画像の軽量化：
<!-- WebP形式の使用（対応ブラウザ） -->
<picture>
<source srcset="./image.webp" type="image/webp">
<img src="./image.jpg" alt="画像" width="400">
</picture>
遅延読み込み：
<!-- 遅延読み込みの設定 -->
<img src="./image.jpg" alt="画像" loading="lazy" width="400">
CDNの活用：
<!-- CDN経由での配信 -->
アクセシビリティの向上
良い代替テキストの作成：
<!-- ❌ 悪い例 -->
<!-- ✅ 良い例 -->
装飾的な画像の処理：
<!-- 装飾的な画像は空の alt を使用 -->
<img src="./decoration.png" alt="" width="50">
<!-- または CSS で背景画像として扱う -->
<div style="background-image: url('./decoration.png'); width: 50px; height: 50px;"></div>
まとめとベストプラクティス
効果的な画像埋め込みのコツ
ファイル構成の整理：
project/
├── README.md
├── docs/
│ ├── guide.md
│ └── api.md
└── assets/
├── images/
│ ├── logos/
│ ├── screenshots/
│ └── diagrams/
└── videos/
命名規則の統一：
<!-- 一貫した命名規則を使用 -->
<!-- 日付やバージョンを含める -->
画像の最適化：
<!-- 適切なフォーマットの選択 -->
プラットフォーム別の戦略
GitHub向けの最適化：
<!-- リポジトリのルートにassetsフォルダを作成 -->
<!-- 大きな画像は外部ホスティングを使用 -->
<!-- GitHubの自動画像アップロード機能を活用 -->
<!-- ドラッグ&ドロップで簡単挿入 -->
技術文書向けの最適化：
<!-- 手順書では連番を使用 -->
<!-- 比較表示で理解を促進 -->
| 変更前 | 変更後 |
|--------|--------|
|  |  |
コメント