How to Add Images in Markdown

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.