MDUtil

Images in Markdown

An image is a link with an exclamation mark in front: ![alt text](image.png). This guide covers titles, sizes, captions, reference-style images and the extra syntax some apps add.

Quick answer

How do you insert an image in Markdown?

Write an exclamation mark, the alt text in square brackets and the image address in parentheses: ![Green hills](hills.png). The address can be a URL or a path relative to the Markdown file. Markdown cannot set the size; use an HTML <img> tag with width for that.

Markdown
![Green hills under a blue sky](/samples/landscape.svg)

Result

Green hills under a blue sky

Image syntax and examples

The examples use a small picture from this site; replace the address with your own image.

Image with a title

Text in quotes after the address becomes the image's title, shown on hover.

Markdown
![Green hills under a blue sky](/samples/landscape.svg "Spring hills")

Result

Green hills under a blue sky

Setting the size with HTML

Markdown has no size syntax. An <img> tag with width sets the width, and the height follows.

Markdown
<img src="/samples/landscape.svg" alt="Green hills under a blue sky" width="240">

Result

Green hills under a blue sky

Reference-style images

Like reference links, the address can live elsewhere in the document under a label.

Markdown
![Green hills under a blue sky][hills]

[hills]: /samples/landscape.svg

Result

Green hills under a blue sky

Image with a caption

Markdown has no caption syntax. Where HTML is allowed, use <figure> and <figcaption>.

Markdown
<figure>
  <img src="/samples/landscape.svg" alt="Green hills under a blue sky" width="300">
  <figcaption>Hills in spring.</figcaption>
</figure>

Result

Green hills under a blue sky
Hills in spring.

Obsidian: width after a pipe

Obsidian sets the width with a number after | in the alt text, or after the file name of an embedded image.

Markdown
![Green hills|200](https://example.com/hills.png)

![[hills.png|200]]

Obsidian only. Other Markdown apps display this differently, so there is no preview.

Pandoc: size in braces

Pandoc reads width and height from braces after the image, in pixels, centimeters or percent.

Markdown
![Green hills](hills.png){width=50%}

Pandoc only. Other Markdown apps display this differently, so there is no preview.

Images in popular apps

![alt](url) works wherever Markdown files are rendered. Sizing and chat apps differ.

AppSupportNotes
GitHub / GitLabSupportedImages and <img> with width; relative paths point into the repository. GitHub also shows <picture> dark-mode images.
ObsidianSupportedImages and embeds; |300 sets the width.
VS Code / TyporaSupportedImages and <img> sizing work in the preview.
Discord / SlackNot supportedNo image syntax; upload the image or paste its URL.

Questions and answers

How do I resize an image in Markdown?

Markdown has no size syntax. Use HTML: <img src="image.png" alt="…" width="300">. Obsidian accepts ![alt|300](image.png), and Pandoc ![alt](image.png){width=300px}.

How do I center an image?

Wrap it in HTML: <p align="center"><img src="image.png" alt="…" width="300"></p>. GitHub keeps the align attribute but removes style.

Why is my image not showing?

Check the path: relative paths start from the Markdown file's folder, file names are case-sensitive on most servers, and spaces need %20 or angle brackets around the address. The ! must sit right before the [.

What is the alt text for?

The text in the brackets describes the image to screen readers and search engines, and it shows when the image fails to load. Describe what the image shows.

How do I add an image from my computer?

Put the file next to the Markdown file and use a relative path: ![Diagram](images/diagram.png). On GitHub you can also drag an image into an issue or comment to upload it.

How do I show a different image in dark mode on GitHub?

Use a <picture> element with <source media="(prefers-color-scheme: dark)" srcset="dark.png"> and an <img> for light mode inside it.

How do I add a caption?

Markdown has no caption syntax. Put a line of text under the image, or use <figure> and <figcaption> where HTML is allowed.

Do images survive a Word or PDF export?

Yes. Markdown to Word embeds every image it can load, and Markdown to PDF prints them with the page.