VSCodeでMarkdownに画像を表示する方法について

VSCodeでMarkdownに画像を表示する基本的な方法

VSCode（Visual Studio Code）では、Markdownファイル内に画像を簡単に表示できます。

基本的にはMarkdownの画像記法を使用し、画像ファイルへのパスを指定します。

基本構文は次のとおりです。

![代替テキスト](画像のパス)

たとえば、Markdownファイルと同じフォルダにsample.pngという画像がある場合は、次のように記述します。

![サンプル画像](./sample.png)

Markdownプレビューを開くと、指定した画像が表示されます。

代替テキストには画像の内容を書く

![ ]の中には、画像を説明する代替テキストを記述します。

たとえば、次のように書きます。

![VSCodeでMarkdownプレビューを表示している画面](./images/vscode-preview.png)

代替テキストは、画像を表示できない場合の説明として使われるほか、アクセシビリティの観点でも重要です。

単に、

![画像](./images/sample.png)

とするよりも、画像の内容が分かる文章を記述するとよいでしょう。

Markdownファイルと同じフォルダの画像を表示する方法

Markdownファイルと画像が同じフォルダにある場合は、画像ファイル名をそのまま指定できます。

たとえば、次のようなフォルダ構成だったとします。

project/
├─ README.md
└─ sample.png

README.mdからsample.pngを表示する場合は、次のように記述します。

![サンプル画像](./sample.png)

次のように./を省略しても参照できます。

![サンプル画像](sample.png)

./は現在のフォルダを意味する

./は「現在のフォルダ」を意味します。

そのため、

./sample.png

は、「現在のMarkdownファイルと同じ階層にあるsample.png」を参照しています。

./は必須ではありませんが、ファイルの位置関係が分かりやすくなるため、明示しておく方法もおすすめです。

imagesフォルダ内の画像を表示する方法

実際のMarkdown管理では、画像を専用フォルダにまとめることも多くあります。

たとえば、次のような構成です。

project/
├─ README.md
└─ images/
   ├─ sample.png
   └─ logo.jpg

この場合、README.mdからsample.pngを表示するには、次のように記述します。

![サンプル画像](./images/sample.png)

JPEG画像の場合も同じです。

![ロゴ画像](./images/logo.jpg)

画像専用フォルダを作ると管理しやすい

画像の枚数が増える場合は、

images/

や、

assets/images/

などの専用フォルダにまとめると管理しやすくなります。

たとえば、

project/
├─ README.md
└─ assets/
   └─ images/
      └─ vscode.png

という構成なら、次のように指定します。

![VSCodeの画面](./assets/images/vscode.png)

1つ上のフォルダにある画像を表示する方法

現在のMarkdownファイルより上の階層に画像がある場合は、../を使用します。

たとえば、次のような構成です。

project/
├─ images/
│  └─ sample.png
└─ docs/
   └─ article.md

docs/article.mdからimages/sample.pngを表示する場合は、次のように記述します。

![サンプル画像](../images/sample.png)

../は1階層上を意味する

../は、現在のフォルダから1階層上に移動するという意味です。

2階層上に移動する場合は、

../../

とします。

たとえば、

![画像](../../images/sample.png)

のように記述します。

相対パスで迷った場合は、「Markdownファイルの場所から画像ファイルまでどのように移動するか」を考えると理解しやすくなります。

Web上の画像をMarkdownに表示する方法

インターネット上に公開されている画像をMarkdownに表示することもできます。

画像URLをそのまま指定します。

![サンプル画像](https://example.com/images/sample.png)

この方法なら、ローカルに画像ファイルを保存する必要はありません。

外部画像はHTTPSを使用する

VSCodeのMarkdownプレビューにはセキュリティ機能があります。

そのため、外部画像を使用する場合は、

https://

で始まるURLを使用するのがおすすめです。

http://の画像については、VSCodeのセキュリティ設定によって表示が制限されることがあります。

また、外部サイトの画像は、削除されたりURLが変更されたりする可能性があります。

長期的に管理するREADMEやドキュメントでは、できるだけプロジェクト内に画像を保存し、相対パスで参照したほうが安定します。

VSCodeでMarkdownの画像をプレビューする方法

Markdownファイルに画像構文を書いても、エディター上ではMarkdown記法のまま表示されます。

実際の表示結果を確認したい場合は、Markdownプレビューを使用します。

WindowsやLinuxでプレビューする

WindowsやLinuxでは、次のショートカットでMarkdownプレビューを開けます。

Ctrl + Shift + V

macOSでプレビューする

macOSでは、次のショートカットです。

Shift + Command + V

プレビューを横に表示する

Markdownを編集しながらプレビューしたい場合は、プレビューを横に表示すると便利です。

WindowsやLinuxでは、

Ctrl + K

を押したあと、

V

を押します。

macOSでは、

Command + K

を押してから、

V

を押します。

Markdownの編集画面とプレビュー画面を同時に確認できるため、画像や文章のレイアウトを調整しやすくなります。

画像をドラッグ＆ドロップして挿入する方法

現在のVSCodeでは、画像ファイルをMarkdownエディターへドラッグ＆ドロップして、Markdown画像リンクを挿入できます。

たとえば、

![image](./images/sample.png)

のような形式で挿入できます。

挿入形式を選択できる場合もある

VSCodeでは、ドラッグ＆ドロップ時の設定や表示される選択肢によって、画像リンクの挿入形式を変更できます。

ワークスペースからの相対パスやファイルへのリンクなど、用途に応じた形式を選択できます。

画像を大量に使用するMarkdownでは、パスを手入力するよりも効率的です。

Markdownの画像サイズを変更する方法

通常のMarkdown画像構文には、一般的に画像の横幅や高さを直接指定する機能がありません。

たとえば、

![画像](./images/sample.png)

では、画像サイズを数値で指定できません。

サイズを変更したい場合は、Markdown内でHTMLのimgタグを利用する方法があります。

<img src="./images/sample.png" width="500">

これで横幅を500pxにできます。

widthだけ指定すると縦横比を保ちやすい

画像の横幅と高さを両方指定すると、元画像と比率が異なる場合に画像が変形する可能性があります。

たとえば、

<img src="./images/sample.png" width="500" height="300">

のように指定すると、元のアスペクト比によっては縦横比が崩れます。

そのため、通常は、

<img src="./images/sample.png" width="500">

のようにwidthだけ指定する方法が扱いやすいでしょう。

HTMLが使えない環境もある

<img>タグによるサイズ指定は、Markdown標準の画像記法ではありません。

Markdown内にHTMLを埋め込む方法です。

そのため、Markdownを表示するサービスやシステムによっては、HTMLタグや一部の属性が制限される可能性があります。

VSCodeだけでなく、GitHubやWebサイトなど別の環境でも使用する場合は、その環境の仕様も確認しておくと安心です。

Markdownの画像を中央寄せする方法

一般的なMarkdown記法には、画像を中央寄せするための標準構文はありません。

HTMLが利用できる環境であれば、次のような方法があります。

<p align="center">
  <img src="./images/sample.png" width="500">
</p>

これにより、画像を中央に配置できます。

画像の下に説明文を付ける

HTMLを使用すれば、画像の下に説明文を配置することもできます。

<p align="center">
  <img src="./images/sample.png" width="500">
  <br>
  VSCodeのMarkdownプレビュー画面
</p>

ただし、これもMarkdown標準の機能ではなくHTMLによる指定です。

表示環境によって挙動が異なる場合があります。

画像をクリックして元画像を開く方法

Markdownのリンク記法と画像記法を組み合わせると、画像をクリックしたときに元画像を開くようにできます。

[![サンプル画像](./images/sample.png)](./images/sample.png)

この構造では、

![サンプル画像](./images/sample.png)

が画像で、

[コンテンツ](リンク先)

がリンクになっています。

スクリーンショットなどを掲載するときに便利な方法です。

ファイル名にスペースがある場合の注意点

画像ファイル名にスペースが含まれていると、Markdownの表示環境によっては扱いにくくなる場合があります。

たとえば、

sample image.png

というファイル名です。

URLとして処理される場合は、スペースを、

%20

として記述する方法があります。

![画像](./images/sample%20image.png)

ファイル名にはハイフンやアンダースコアを使う

トラブルを避けるなら、画像ファイル名にはスペースを使用しないほうが管理しやすくなります。

たとえば、

sample-image.png

や、

sample_image.png

などです。

WebサイトやGitHubでも利用する場合は、

vscode-markdown-preview.png

のように、英数字とハイフンを中心にしたファイル名にすると扱いやすいでしょう。

Windowsでは画像パスにスラッシュを使う

Windowsの通常のファイルパスは、

C:\Users\name\Pictures\sample.png

のようにバックスラッシュを使用します。

しかし、Markdown内では、

![画像](./images/sample.png)

のようにスラッシュ/を使う方法がおすすめです。

特に、GitHubやLinuxなど別の環境でも使用する可能性がある場合は、スラッシュで統一しておくと移植性を高められます。

VSCodeでは表示されるのにGitHubでは表示されない原因

VSCodeでは画像が表示されているのに、GitHubへアップロードすると表示されなくなることがあります。

代表的な原因が、PC内の絶対パスを指定しているケースです。

たとえば、

![画像](C:/Users/user/Desktop/sample.png)

という指定です。

このパスは自分のPC内にしか存在しません。

GitHubから利用者のPC内にあるファイルへアクセスすることはできないため、画像は表示されません。

GitHubでも表示するなら画像をリポジトリに入れる

たとえば、次のような構成にします。

project/
├─ README.md
└─ images/
   └─ sample.png

そして、

![画像](./images/sample.png)

と記述します。

Markdownファイルと画像ファイルを同じリポジトリ内で管理しておけば、VSCodeでもGitHubでも表示しやすくなります。

大文字と小文字の違いに注意する

画像が表示されない場合は、ファイル名の大文字・小文字も確認しましょう。

たとえば、実際のファイル名が、

Sample.png

なのに、

![画像](./images/sample.png)

と指定しているケースです。

Windows環境では正常に動作しているように見えても、Linuxなどの環境では、

Sample.png

と、

sample.png

が別のファイルとして扱われることがあります。

そのため、Markdown内のパスと実際のファイル名は完全に一致させるのがおすすめです。

VSCodeでMarkdownのリンク切れを確認する方法

VSCodeにはMarkdown内のリンクを検証する機能があります。

画像が多いドキュメントでは、この機能を利用するとパスの間違いを見つけやすくなります。

設定では、次の項目を利用できます。

{
  "markdown.validate.enabled": true
}

有効にすると、存在しない画像ファイルやリンクなどをVSCode上で確認しやすくなります。

たとえば、

![画像](./images/sampel.png)

のようにファイル名を間違えている場合、問題に気付きやすくなります。

VSCodeでは画像パス入力時のプレビューも利用できる

現在のVSCodeには、Markdown内で画像を扱いやすくする補助機能もあります。

画像パスの入力候補からファイルを選択したり、画像リンクにマウスを合わせて内容を確認したりできます。

そのため、毎回Markdown全体のプレビューを開かなくても、画像ファイルを確認しやすくなっています。

Markdown画像を管理しやすいフォルダ構成

画像の数が少ない場合は、Markdownファイルと同じフォルダでも問題ありません。

一方、記事やドキュメントが増えてくる場合は、画像専用フォルダを作ると管理しやすくなります。

たとえば、次のような構成です。

project/
├─ README.md
├─ docs/
│  ├─ article-01.md
│  └─ article-02.md
└─ images/
   ├─ article-01/
   │  ├─ image-01.png
   │  └─ image-02.png
   └─ article-02/
      └─ image-01.png

docs/article-01.mdから、

images/article-01/image-01.png

を参照する場合は、

![画像の説明](../images/article-01/image-01.png)

と記述します。

記事ごとに画像フォルダを分けておくと、画像が増えても整理しやすくなります。

VSCodeのMarkdownでよく使う画像記法

VSCodeでMarkdown画像を扱う場合、特によく使う記法をまとめると次のようになります。

<!-- 同じフォルダ -->
![画像](./sample.png)

<!-- imagesフォルダ -->
![画像](./images/sample.png)

<!-- 1階層上のフォルダ -->
![画像](../images/sample.png)

<!-- Web上の画像 -->
![画像](https://example.com/sample.png)

HTMLを利用できる環境なら、サイズ指定も可能です。

<img src="./images/sample.png" width="500">

中央寄せする場合は、次のような方法があります。

<p align="center">
  <img src="./images/sample.png" width="500">
</p>

画像をクリックして元画像を開く場合は、

[![画像](./images/sample.png)](./images/sample.png)

と記述します。

VSCodeでMarkdownに画像を表示するなら相対パスがおすすめ

VSCodeでMarkdownに画像を表示する場合は、

![画像の説明](./images/sample.png)

のように、相対パスを使用する方法がおすすめです。

ローカルPCの絶対パスを指定すると、そのPCのVSCodeでは表示できても、GitHubや別のPCでは画像が表示されなくなる可能性があります。

そのため、

project/
├─ README.md
└─ images/
   └─ sample.png

のようにMarkdownファイルと画像を同じプロジェクト内で管理し、

![画像の説明](./images/sample.png)

と記述しておくと扱いやすくなります。

さらに、VSCodeのMarkdownプレビューやリンク検証機能、ドラッグ＆ドロップ機能を活用すれば、画像を含むMarkdownを効率よく作成・管理できます。

以上、VSCodeでMarkdownに画像を表示する方法についてでした。

最後までお読みいただき、ありがとうございました。