Markdown: マークダウン画像構文と代替テキスト
百聞は一見にしかず。Markdown では、構文を 1 行記述するだけで画像を挿入できますが、それをうまく行うには少しのノウハウが必要です。
1. 学ぶこと
- マークダウン画像構文の基本
- Alt テキストの重要性とそれを上手に書く方法
- 画像へのリンクの追加 (クリックして移動)
- 参考画像による一元管理
- 画像のベスト プラクティス (サイズ、形式、CDN)
2. テクノロジーブロガーの実話
(1) 問題点: 画像が読み込まれない
James は技術ブログを運営しており、記事ごとにいくつかのスクリーンショットが含まれています。最初、彼は自分のサーバーで画像をホストしていましたが、リンクが切れ続け、サーバーが数回移行し、古いリンクはすべて無効になりました。さらに悪いことに、彼の画像ファイル名は中国語であり、一部のブラウザでは読み込めませんでした。読者からは「画像が壊れている」という苦情が寄せられ、直帰率は70％に跳ね上がった。
(2) 解決策: イメージ CDN と命名規則を使用する
James はすべての画像を CDN ベースの画像ホスティング サービス (Cloudinary など) に移行し、英語のファイル名に切り替え、すべての画像に説明的な代替テキストを書きました。また、Markdown の参照スタイルの画像を使用して、すべての URL を一元管理しました。切り替え後、画像の読み込み時間は 3 倍に短縮され、直帰率は 35% に低下しました。
3. 画像構文の基本
(1) インライン画像
画像の構文はリンクと非常によく似ていますが、先頭に ! が追加されているだけです。
MARKDOWN
| パート | 説明 | 例 |
|---|---|---|
![Alt Text] |
画像の読み込みに失敗したときに表示されるテキスト | ![Screenshot] |
(Image URL) |
画像ファイルのアドレス | (https://example.com/img/logo.png) |
(2) 画像サイズの調整
標準の Markdown は、画像の寸法の設定をサポートしていません。必要に応じて、HTML <img> タグを使用します。
MARKDOWN
<img src="logo.png" width="200" alt="Set width to 200px">
💡 ヒント: 90% の場合、必要なのは標準の Markdown 画像構文だけです。実際にサイズ制御が必要な場合にのみ、HTML
<img> に戻ります。
▶ 例: ローカル画像の挿入
MARKDOWN
💡 ヒント: 適切な代替テキストは、画像の内容と機能の両方を説明する必要があります。装飾画像 (区切りアイコンなど) の場合、代替テキストは空にすることができます
![] が、完全に省略してはいけません。
5. リンクとしての画像
(1) クリック可能な画像
画像をリンク構文内にラップしてクリック可能にします。
MARKDOWN
[](fullsize-image.jpg)
[](https://example.com)
構造の内訳:
MARKDOWN
[ ← Link starts
 ← Image (clickable area)
] ← Link ends
(https://example.com) ← Navigation target
▶ 例: 画像リンクの実践的な使用法
MARKDOWN
## Project Badges
[](https://github.com/user/repo/actions)
[](https://www.npmjs.com/package/package-name)
## Product Screenshots
| Feature | Screenshot |
|:-----|:-----|
| Dashboard | [](img/dashboard-full.png) |
| Settings | [](img/settings-full.png) |
💡 ヒント: これは、GitHub README で見られる一般的な「バッジ」パターンです。バッジをクリックすると、対応するサービス (CI ステータス ページ、npm パッケージ ページなど) に移動します。
6. 参考画像
参照リンクと同様に、画像 URL も一元管理できます。
MARKDOWN
In the body:
![Company Logo][logo]
![Product Screenshot][screenshot1]
Defined at the bottom:
[logo]: https://cdn.example.com/logo.png "Company Logo"
[screenshot1]: https://cdn.example.com/screenshots/v2/dashboard.png "New Dashboard Screenshot"
💡 ヒント: 参照画像は、大規模なドキュメント セットを管理する場合に特に役立ちます。新しいイメージ ホストに移行する場合、下部の URL 定義を更新するだけで済みます。
7. 画像のベストプラクティス
(1) ファイル形式の選択
| フォーマット | 最適な用途 | 長所 | 短所 |
|---|---|---|---|
| PNG | スクリーンショット、アイコン、透明な背景 | ロスレス、高品質 | ファイルサイズが大きい |
| JPEG | 写真、複雑なカラー画像 | ファイルサイズが小さい | 非可逆圧縮 |
| SVG | アイコン、ロゴ、イラスト | 無限に拡張可能な小さなファイル | 写真用ではありません |
| GIF | シンプルなアニメーション | 優れた互換性 | 限られた色、大きなファイル |
| ウェブP | PNG/JPEG を置き換える | 25 ～ 35% 小型化 | 一部の古いブラウザはサポートされていません |
(2) 画像最適化のヒント
MARKDOWN
1. Control size: keep individual images under 500KB, aim for 100-300KB
2. Use a CDN: accelerate global loading
3. English filenames: logo.png ✅ lo#go.png ❌
4. Logical directories: assets/images/ or img/
5. Write Alt text: every image must have descriptive Alt text
⚠️ 注: GitHub README では、ローカル イメージ パス (
./assets/image.png) を参照することは安全ですが、外部イメージ ホストを参照する場合は、サービスが安定していて信頼できることを確認してください。
▶ 例: 製品ドキュメント内の画像
MARKDOWN
## UI Showcase
### Login Page
### Dashboard
> **Note:** Click the image to view the full-resolution version
[](img/dashboard-full.png)
8. 完全な例: プロジェクト README 内の画像ショーケース
TEXT
📖 参照専用
Awesome App README Structure:
Title line: # Awesome App + badge images
Screenshot table: Mobile | Desktop
Install command: npm install awesome-app
Logo reference: [logo]: https://cdn.example.com/logo.png
期待される結果: プロジェクト バナー、バッジ、スクリーンショットのショーケース、ドキュメントの最後に定義された一元管理されたロゴを備えた、視覚的に充実した GitHub README。
❓ よくある質問
Q 画像が大きすぎます。Markdown で縮小するにはどうすればよいですか?
A 標準の Markdown はサイズ制御をサポートしていません。 HTML を使用します:
<img src="url" width="400" alt="description">。Q GitHub でイメージ パスを記述するにはどうすればよいですか?
A リポジトリ内のイメージには
./assets/image.png のような相対パスを使用します。外部画像ホスティングに絶対 URL を使用することもできます。Q アニメーション GIF を使用できますか?
A はい。構文は静止画像と同じです。ただし、ファイル サイズに注意してください。大きな GIF は 5 ～ 10MB にもなり、ページの読み込み速度が遅くなる可能性があります。
Q 代替テキストの最大長はどれくらいですか?
A 厳密な制限はありませんが、125 文字以下が推奨されます。スクリーン リーダーは通常、長すぎる代替テキストを切り捨てます。
Q SVG アイコンはどのように使用すればよいですか?
A
.svg ファイルを Markdown で直接参照します。 SVG ソース コードを Markdown に埋め込むこともできます (一部のパーサーでサポートされています)。📖 まとめ
- 画像構文
は、リンク構文!が 1 つだけ異なります。 - 代替テキストはアクセシビリティと SEO にとって重要です。画像が何を示しているか、またその動作の両方を説明します。
- リンクとしての画像:
[](link)により画像をクリック可能になります - 参照イメージは URL 管理を一元化し、メンテナンスと移行を容易にします。
- CDN ホスティング、英語のファイル名、および制御されたファイル サイズを優先します。
- サイズ制御が必要な場合は、HTML
<img>タグに戻ります
📝 練習問題
-
基本: 説明的な代替テキストを含む画像 (オンラインまたはローカルの画像) を Markdown に挿入します。次に、ブラウザでの画像の読み込みを無効にして、代替テキストが正しく表示されることを確認します。
-
中級: README.md に「サムネイルをクリックして完全な画像を表示する」設定を備えた小さなプロジェクトを作成します。ページには小さな画像が表示され、クリックすると新しいタブでフルサイズのバージョンが開きます。
-
課題: 少なくとも 5 つのスクリーンショットとドキュメントの下部に定義されている URL を含む参照スタイルの画像を使用して、「Web サイトのスクリーンショット ギャラリー」を維持します。次に、それらのスクリーンショットを WebP 形式に変換して、ファイル サイズの違いを比較してみてください。
