MarkdownViewer

Markdown Image Syntax: How to Add Images

Images in Markdown are written almost exactly like links — with one extra character. Getting that syntax right, plus useful alt text, is what makes documentation and READMEs look finished rather than broken. This guide covers the syntax, how to link an image to a URL, how to control size, and the mistakes that stop images loading.

The image syntax

An image is an exclamation mark, then square brackets for the alt text, then parentheses for the image URL. The exclamation mark is the only difference from a normal link. The alt text is what screen readers announce and what is shown if the image fails to load, so it is worth writing properly.

  1. ![alt text](image.png)
  2. ![alt text](image.png "Hover title")

Writing good alt text

Alt text describes the image for people who cannot see it and for search engines. Write what the image conveys, not the file name — 'A Code 128 barcode encoding the value INV-2026-0417' is useful; 'barcode' or 'img1' is not. If the image is purely decorative, an empty alt (a pair of empty brackets) is acceptable, but most documentation images carry meaning.

Linking an image to a URL

To make an image clickable — common with a logo that links home, or a screenshot that opens the full-size version — wrap the image syntax inside link brackets. The outer brackets create the link and the inner image becomes its content.

  1. [![alt text](thumbnail.png)](https://example.com/full.png)

Controlling image size in Markdown

Standard Markdown has no syntax for width or height. Images render at their natural size, capped by the page width. To control size you need raw HTML with an img tag and a width attribute, which most renderers pass through — but keep in mind that a fixed size hurts responsiveness on small screens.

  1. <img src="image.png" alt="alt text" width="300">

Hosting and relative paths

An image URL can be absolute (https://...) or relative. A relative path like ./images/diagram.png resolves against the location of the Markdown file, which is why images stored in a repository render on GitHub but may not load in a viewer that does not have the repository. Remote images load from their own host, which means that host can see the request — relevant for private documents.

Common mistakes

  1. Forgetting the leading exclamation mark, so the image renders as a link
  2. Leaving spaces in the path — use %20 or move the file
  3. Wrong case in the file name on a case-sensitive host
  4. Relative paths that work in a repository but not when the file is rendered elsewhere
  5. Missing alt text, which hurts accessibility and gives no fallback if the image fails

Frequently Asked Questions

What is the difference between a Markdown link and an image?
Only the leading exclamation mark. A link is [text](url) and an image is ![alt](url). The image version displays the target as a picture; the link version makes text clickable.
Why is my image not showing?
The usual causes are a wrong or relative path that does not resolve in this context, a case mismatch in the file name, spaces in the path, or the leading exclamation mark missing so it renders as a link. Check the raw URL by pasting it in a browser tab.
How do I resize an image in Markdown?
Plain Markdown cannot resize images. Use a raw HTML img tag with a width attribute; most renderers accept it. For a responsive result, prefer CSS in the surrounding page over a fixed width.
Should alt text be short or long?
As long as it needs to convey the image's meaning, and no longer. A useful guideline is to describe what a reader would miss if the image were absent. Purely decorative images can have empty alt text.

Related Markdown Tools

Markdown ViewerREADME ViewerMarkdown Cheat SheetAll Markdown Tools