How to add an image in Markdown:exclamation mark, alt text, path.

Q: How do I add an image in Markdown?

Write ![alt text](path/to/image.png). The path is a web address or a file path relative to the Markdown file.

Q: How do I change the size of an image in Markdown?

Markdown has no size syntax. Use an HTML tag such as .

Q: How do I center an image or add a caption in Markdown?

Use HTML: wrap the image in to center it, or in with a for a caption. Support varies by app.

The Markdown image is one short line. Size, alignment and captions are not part of it, so they need a little HTML. Here is the syntax, the path rules and the workarounds.

Download for Mac

macOS 14 or later. Reading is free; editing and reviews are one payment.

Quick answer

An image is a link with an exclamation mark in front: ![alt text](path/to/image.png). The path can be a web address or a file relative to the document. For a size, switch to HTML: <img src="image.png" width="400">.

![A cat on a keyboard](assets/cat.png)

<img src="assets/cat.png" alt="A cat on a keyboard" width="400">

Published 3 November 2026 · Updated 3 November 2026

The syntax

![Alt text](path/to/image.png "Optional title")

Alt text in the square brackets describes the image to screen readers and is shown if the image cannot load. Write what the picture shows, not "image".
The path goes in parentheses. If it has spaces, write them as %20 or wrap the path in angle brackets.
The title is optional text in quotes, usually shown as a tooltip on hover.

Reference style also works, which keeps long addresses out of the text:

![Logo][logo]

[logo]: https://example.com/logo.png "DotMD logo"

Relative paths and where the file lives

A path without a scheme is relative to the Markdown file, not to where you opened the app. With the files laid out as

docs/
  spec.md
  assets/
    flow.png

the image in spec.md is ![Flow](assets/flow.png). From a file one folder up, write docs/assets/flow.png, and from a folder below, ../assets/flow.png. On GitHub a path that starts with / is relative to the repository root. Keep images next to the document, in an assets folder, so that moving the folder moves the pictures too.

Image file names are case-sensitive on Linux servers even though a Mac ignores case, which is a common reason an image works locally and breaks online.

How to set the image size

Markdown itself has no size. Use an HTML img tag with a width; the height follows the proportions:

<img src="assets/screen.png" alt="Settings window" width="400">

Width and height are in pixels, and a percent such as width="50%" works in most apps. GitHub supports this tag in READMEs and comments. Some apps also accept a size inside the alt text, such as ![Screenshot|400](assets/screen.png). That form comes from Obsidian and DotMD reads it, but other apps will show the |400 as part of the alt text, so use the HTML tag for a file that has to work everywhere. In a table cell, a pipe has to be written \|.

Alignment and captions

Alignment and captions are also HTML. To center an image, put it in a paragraph with align:

<p align="center">
  <img src="assets/logo.png" alt="Logo" width="200">
</p>

For a caption, use a figure with a figcaption:

<figure>
  <img src="assets/flow.png" alt="Request flow" width="500">
  <figcaption>Figure 1. The request flow.</figcaption>
</figure>

Not every app keeps these tags; GitHub does for most of them, and DotMD shows both. If you need a caption that works anywhere, put an italic line under the image instead: *Figure 1. The request flow.*.

A clickable image and other tricks

Put the image inside a link to make it clickable:

[![Build status](https://example.com/badge.svg)](https://example.com/builds)

That is how badges at the top of a README are built. To show a different picture in dark mode, use a picture element with a <source media="(prefers-color-scheme: dark)">, where the app supports it.

Alt text, file size and formats

Write alt text as if you were describing the picture over the phone: Settings window with the Sync option turned on says more than screenshot. For a purely decorative image, leave the brackets empty so a screen reader skips it.

Use PNG for screenshots and diagrams, JPEG for photos, SVG for logos and line art, and keep files small: a 6 MB screenshot slows down a README and a repository. Most apps also show animated GIFs the same way as any other image.

Why the image does not show

The path is wrong. Check it from the Markdown file's folder, and check the case of the file name.
A missing exclamation mark. Without it you get a link, not a picture.
A space in the path that is not escaped.
A local file in an online page. A path to a file on your disk only works on your disk.
A blocked remote image. Some apps do not load pictures from the web until you allow it.

To see how an image will look, open the file in a reader that resolves paths relative to the document. DotMD does: images are shown no wider than the text column, the HTML width tag is respected, and a screenshot pasted in the editor is saved in an assets folder next to the file. Reading is free.

Questions about images in Markdown

How do I add an image in Markdown?

Write ![alt text](path/to/image.png). The path is a web address or a file path relative to the Markdown file.

How do I change the size of an image in Markdown?

Markdown has no size syntax. Use an HTML tag such as <img src="image.png" width="400">.

How do I center an image or add a caption in Markdown?

Use HTML: wrap the image in <p align="center"> to center it, or in <figure> with a <figcaption> for a caption. Support varies by app.

Why is my Markdown image not showing?

Usually the relative path is wrong or its case does not match the file name. Check that there is an exclamation mark and that the path is relative to the Markdown file.

Guides

Markdown cheat sheet Reading Markdown The editor