Syntax Reference
Markdown Images
Markdown images use the form  — a link with a leading exclamation mark. The alt text sits in the brackets, the image path in the parentheses, and the syntax converts to an HTML <img> element.
Key facts
- Syntax form
- 
- Output element
- <img src alt>
- Alt text source
- the bracket text
- Resizing
- none in pure Markdown — use a raw <img> tag
How do you add an image in Markdown?
Write an exclamation mark, the alt text in square brackets, then the image path in parentheses: . The path accepts a relative file location or an absolute URL. The output is an <img> element.
The syntax mirrors Markdown Links with a leading exclamation mark. Paste any image syntax into Markdown Links & Images to HTML to see the emitted HTML live.
<img src="/images/logo.png" alt="Company logo">How do you write good alt text?
Describe what the image shows, briefly and factually. Alt text is read aloud by screen readers and rendered in place of the image when loading fails. Leave it empty () only for purely decorative images.
The bracket text transfers to the alt attribute verbatim — no Markdown formatting applies inside it.
How do you add a title to an image?
Add a quoted title after the path: . The title becomes the title attribute and shows as a hover tooltip. Title and alt serve different readers — tooltips for pointers, alt for screen readers.
<img src="chart.png" alt="Chart" title="Quarterly revenue">Can you resize an image in Markdown?
No. Pure Markdown has no width or height syntax. To control size, write a raw HTML tag instead: <img src="chart.png" width="400">. Converters pass raw HTML through to the output unchanged.
Some platforms bolt on sizing extensions, but none are part of CommonMark or GFM — raw HTML is the only portable method.
How do you make an image a link?
Nest the image inside link syntax: [](target-url). The output wraps the <img> in an <a> element, so clicking the image opens the target. README badges use exactly this pattern.
[](https://example.com)<a href="https://example.com"><img src="logo.png" alt="Logo"></a>Frequently Asked Questions
- Can I use a local image file?
- Yes — pass its relative path: . The path resolves against the page hosting the converted HTML, so keep the image in the same relative location when publishing.
- How do I add a caption to an image?
- Markdown has no caption syntax. Wrap the output in <figure> and <figcaption> elements manually, or write the caption as an italicised paragraph directly below the image.
- What image formats does Markdown support?
- All of them — Markdown only writes the path into the src attribute. Format support is decided by the reader's browser: PNG, JPEG, GIF, SVG, WebP, and AVIF all work in modern browsers.
- Why is my image not displaying?
- A wrong path is the usual cause; the alt text renders in its place. Check that the URL is reachable, the relative path matches the published location, and the syntax starts with ! before the bracket.