How to Add Images in Markdown
Embed an image in Markdown with an exclamation mark, alt text in brackets, and the image URL in parentheses: . The syntax is identical to a link with a leading ! — that exclamation mark is the only difference.
Platform Support
The bracket text is the alt attribute, and it matters more than most people realize: screen readers speak it, search engines index it, and it displays in place of the image when the file fails to load. Write what the image shows ("Bar chart of monthly downloads, peaking in March"), not a filename or the word "image". Purely decorative images can use empty alt text (), which tells assistive technology to skip them.
Like links, images accept an optional hover title in quotes —  — and the URL can be absolute or relative. In a GitHub repository, relative paths like ./assets/screenshot.png resolve against the file location on the current branch, which keeps images working in forks. One caveat for README badges and screenshots: GitHub proxies all images through its Camo CDN, so dynamically generated images may be cached for a while.
To make an image clickable, nest the image inside a link: the image becomes the link text. [](https://example.com) reads inside-out — the inner  is the image, the outer [...](...) is the link. This is the standard pattern for CI badges that link to build pages, and thumbnails that link to full-size versions.
Pure Markdown cannot resize images — there is no width syntax in CommonMark or GFM. Where raw HTML is allowed (GitHub READMEs, most static site generators), use an img tag: <img src="image.png" alt="alt text" width="400">. GitHub also supports <picture> with prefers-color-scheme media queries to swap images between light and dark mode. Obsidian has its own shorthand (), but it is non-portable.
Examples
Embed an image with alt text.
Add a tooltip title to an image.
[](https://example.com)
Make an image clickable by wrapping it in a link.
<img src="https://placehold.co/600x200" alt="Wide banner" width="300">Markdown has no native sizing syntax; use an HTML img tag on platforms that allow it.
[](https://example.com/ci)
The image is the link text: image syntax inside link syntax.
){kind=link}
Common Mistakes
[alt text](image.png)Without the leading exclamation mark you get a hyperlink to the image file instead of an embedded image.
 for a meaningful imageEmpty alt text on informative images hides them from screen readers and loses SEO value. Reserve empty alt for purely decorative images.
Spaces in the URL break the parser. Percent-encode spaces as %20, or rename the file to avoid spaces.
Platform Notes
GitHub
Relative paths resolve within the repo; all images are proxied through the Camo CDN. Drag-and-drop into issues/PRs uploads the file and inserts the Markdown for you.
Discord
Image Markdown syntax does not render in normal messages — attach or paste images instead.  only works inside bot embeds.
Obsidian
Uses ![[image.png]] embeds for vault files, with a size shorthand ![[image.png|400]]. Standard  also works for external images.
Notion
Pasted Markdown image syntax converts to image blocks on import; in normal editing you add images as blocks, not with Markdown syntax.
Frequently Asked Questions
How do I insert an image in Markdown?
Use an exclamation mark, alt text in brackets, and the image URL in parentheses: .
How do I resize an image in Markdown?
Standard Markdown has no sizing syntax. On platforms that allow HTML (like GitHub), use <img src="image.png" width="400" alt="...">. Obsidian supports .
How do I make an image a clickable link?
Wrap the image in link syntax: [](https://example.com). The inner part is the image, the outer brackets and parentheses are the link.
What should I write as alt text?
Describe what the image shows and why it matters in context — for example "Line chart showing response time dropping after the cache change". Skip phrases like "image of".
How do I center an image in Markdown?
Markdown itself cannot center images. Where HTML is allowed, wrap the image: <p align="center"><img src="..." alt="..."></p> works on GitHub.
Related Syntax
Links
Learn how to create links in Markdown: inline links, reference links, autolinks, and titles.
Tables
Learn how to create tables in Markdown with pipes and dashes, align columns with colons, escape pipes inside cells, and work around missing features like merged cells.
Code Blocks
Learn Markdown code formatting: inline code with backticks, fenced code blocks with syntax highlighting, nesting backticks, and indented code blocks.