Markdown Image Syntax
How to add images in Markdown. Covers the core  syntax, reference-style and clickable images, relative paths, sizing/alignment workarounds, and the mistakes that break them.
Basic Syntax
A Markdown image starts with an exclamation mark, followed by alt text in square brackets, followed by the image URL in parentheses.
Image Titles
Add a quoted title after the URL. It renders as a tooltip on hover in most browsers and is useful for extra context. It is not a visible caption.
Reference Images
Reference-style images keep long URLs out of your paragraphs. Use ![alt][id] inline, then define [id]: url on its own line later in the document.
![MarkdownFormatting logo][logo]
[logo]: https://markdownformatting.com/favicon.png "Site logo"
Clickable Images
Wrap the image syntax in link syntax to make the image itself clickable. This is common for banners and thumbnails.
[](https://markdownformatting.com)Relative Paths
Use relative paths for images stored next to your Markdown file. The path is resolved relative to the file containing the image.
Sizing & Alignment
Standard Markdown cannot set width, height, or alignment. Use raw HTML when the renderer allows it. GitHub allows width and height attributes but strips style. Many static-site generators allow both.
<img src="https://placehold.co/600x300?text=Example+Image" alt="Example image" width="300" /><p align="center">
<img src="https://placehold.co/600x300?text=Example+Image" alt="Centered image" />
</p>
Alt Text
Alt text describes the image for screen readers and search engines. Keep it short, accurate, and contextually relevant. Avoid phrases like "image of" because the screen reader already knows it is an image.
Good: ![A crescent moon over a dark ocean]
Bad: ![image]
Common Mistakes
The five most common reasons a Markdown image fails. Each row shows the broken version and the corrected one side by side.
Broken
[Alt text](https://example.com/image.png)Fixed
Broken
Fixed
Broken
Fixed
Broken
Broken
![Alt text][logo]
[logo] https://example.com/image.pngFixed
![Alt text][logo]
[logo]: https://example.com/image.pngQuick Reference
| Syntax | What it does |
|---|---|
|  | Inline image |
|  | Inline image with tooltip |
| ![alt][id] | Reference image marker |
| [id]: url "title" | Reference image definition |
| [](url) | Clickable image |
|  | Relative-path image |
| <img src="" alt="" width="300" /> | HTML fallback for sizing |
Platform Support
Images are part of standard Markdown, so they are widely supported. The differences are mainly in HTML attribute handling and relative-path resolution.
| Platform | Supported? | Notes |
|---|---|---|
| GitHub | Yes | Inline and reference images work. Relative paths resolve in the repository. GitHub strips inline style but allows width/height attributes. |
| GitLab | Yes | Same as GitHub Flavored Markdown. |
| Reddit (new) | Yes | Image links work; titles are ignored. Hosted image URLs must be whitelisted by Reddit. |
| Reddit (old) | Partial | Images require a direct link; old Reddit has no image upload hosting of its own. |
| Discord | Yes | Embeds image URLs automatically. Markdown image syntax also works. |
| Slack | Yes | Image URLs unfurl automatically. Markdown image syntax works in posts but not in all Block Kit surfaces. |
| Notion | Partial | Pasting an image uploads it; Markdown image syntax is accepted on import but may become Notion-native. |
| Obsidian | Yes | Relative paths use vault-relative paths. Wikilink embeds ![[image.png]] are the native style. |
| VS Code preview | Yes | Renders inline, reference, and HTML img images. Relative paths resolve from the open file. |
| CommonMark | Yes | Inline and reference images are part of the CommonMark spec. |
| Docusaurus / VitePress / Astro | Yes | Relative paths resolve according to the static site config; HTML img also works. |
Frequently Asked Questions
How do you add an image in Markdown?
Use inline image syntax: . The text inside the square brackets is alt text, and the URL inside the parentheses points to the image file.
What is alt text in a Markdown image?
Alt text describes the image for screen readers and appears if the image fails to load. Keep it concise and descriptive: .
Can you add a title or caption to a Markdown image?
Yes. Add a title in double quotes after the URL: . Most browsers show this as a tooltip on hover. It is not a visible caption; for a true caption, use HTML or place text below the image.
How do you make an image a link in Markdown?
Wrap the image syntax in link syntax: [](https://example.com). The image becomes the clickable element that takes the reader to the target URL.
Can you resize or align an image in Markdown?
Standard Markdown has no syntax for image size or alignment. Use raw HTML: <img src="image.png" width="300" /> or <p align="center"><img ... /></p>. Not every renderer allows inline HTML; GitHub allows width and height attributes but strips style attributes.
Do relative paths work for images in Markdown?
Yes. Use ./image.png for an image in the same directory and ../images/diagram.png for an image in a sibling folder. The path is resolved relative to the Markdown file. On GitHub and static-site generators, the repository root is the base for absolute paths starting with /.
What is a reference-style image in Markdown?
A reference-style image separates the alt text from the URL, like a footnote: ![Alt text][id] followed later by [id]: https://example.com/image.png. This keeps long paragraphs readable and lets you reuse the same image URL.
Why is my Markdown image not showing?
Check that: the URL has a protocol for external images, there are no unescaped spaces in the URL, the closing parenthesis is present, the exclamation mark precedes the square brackets, and the relative path is correct for the renderer.
Can I use Markdown inside image alt text?
Alt text is treated as plain text. You cannot use bold, italic, or links inside it. Write a literal description, such as !['Deploy succeeded' banner with a green checkmark].
Are images supported in GitHub Markdown?
Yes. GitHub supports inline and reference images, relative repository paths, and HTML <img> tags with width and height attributes. GitHub strips style and class attributes for security.