How to add an image in Markdown
Try it — edit the markdown and watch the preview
Result
Runs entirely in this tab. Open the full editor to work on a real document.
An image is the link syntax with an exclamation mark in front:
The square brackets hold the alt text, the parentheses hold the path. A title can follow the path in quotes, and it shows on hover:
Alt text does real work
It is announced by screen readers, shown when the image fails to load, and read by search engines. “diagram.png” or “image” tells nobody anything. Describe what the image conveys:
If an image is purely decorative, leave the brackets empty —  —
so assistive technology skips it rather than announcing a filename.
Sizing is not part of Markdown
There is no width syntax, on purpose: size is a presentation concern. If you need it, use HTML directly, which most renderers allow:
<img src="diagram.png" alt="Site map" width="480">
Clickable images
Wrap the image in a link — the image becomes the link text:
[](https://example.com/map)
Paths resolve against the output
A relative path is resolved from wherever the rendered page lives, not from the source file. That is the usual reason an image works in your editor and breaks once published.
Common questions
- What is the syntax for an image?
- An exclamation mark, square brackets around the alt text, then parentheses around the path — . It is the link syntax with a leading bang.
- What should the alt text say?
- What the image conveys, in a short phrase. It is read aloud by screen readers and shown when the image fails to load, so repeating the filename or writing "image" helps nobody. If the image is purely decorative, leave the brackets empty.
- How do I resize an image?
- Markdown has no sizing syntax, because size is presentation rather than content. Use an <img> tag with width and height, or size the file itself. Some renderers accept extensions, but none of them are portable.
- How do I make an image clickable?
- Wrap the whole image in link syntax — [](https://example.com). The image becomes the link text.
- Why is my image not showing?
- Usually the path. Relative paths resolve against the rendered document's location, not the source file's, which is why an image that works in your editor can break on a website. Check the path in the browser first.