Markdown Image Syntax: Add Images to README & Docs
The Markdown image syntax with copy-ready examples: alt text, titles, sizing, links and GitHub README images, plus how to host the image file.
By PictureToLink Team · · 7 min read
Facts checked against official sources on
On this page
To add an image in Markdown, write an exclamation mark, the alt text in square brackets, and the image's address in round brackets: . The address can be a full URL or, inside a repository, a relative path to the file. Markdown has no built-in way to set the size, so for resizing you fall back to an HTML img tag where the platform allows it.
How do I add an image in Markdown?
To add an image in Markdown, write an exclamation mark, the alt text in square brackets, then the image's address in round brackets. The address can be a full URL, which works anywhere the image is publicly reachable, or a relative path to a file next to your Markdown file.
The image syntax mirrors the link syntax, with a ! in front:
Two common forms of address:
The first is an absolute URL, which works anywhere the image is publicly reachable. The second is a relative path, which works when the image lives next to your Markdown file, for example in the same repository.
The CommonMark specification, which most modern Markdown tools follow, describes it this way: image syntax is like link syntax, except that the description starts with ![ instead of [, and when rendered to HTML the description "is standardly used as the image's alt attribute".
Reference-style images
For long URLs, or an image you use several times, you can define the address once at the bottom of the file:
![Build status][status]
[status]: https://example.com/badges/build.svg
The spec's examples show that ![foo][bar], ![foo][] and ![foo] all work when a matching reference is defined.
Alt text and titles
Alt text
The text in square brackets becomes the image's alt text. Screen readers read it aloud, and it appears if the image fails to load. GitHub's documentation calls alt text "a short text equivalent of the information in the image".
Good alt text describes what the image tells the reader:
| Image | Weak alt text | Better alt text |
|---|---|---|
| Screenshot of a settings page | screenshot | Settings page with the API key field highlighted |
| Architecture diagram | diagram | Diagram: browser sends uploads to the API, which stores files in object storage |
| Logo at the top of a README | logo.png | Acme CLI logo |
Purely decorative images can have empty alt text (), but in documentation most images carry information, so describe them.
A note if you use PictureToLink: our "Markdown" copy format gives you  with the brackets empty, because only you know what the image shows. Type your description between the square brackets before you publish.
Titles
You can add a title in quotes after the address. Browsers usually show it as a tooltip on hover:
CommonMark renders that as an img element with both alt and title attributes. A title is optional and never replaces alt text, because many readers (on touch screens, or using screen readers) never see the tooltip.
How do I make a Markdown image clickable?
To make a Markdown image a link, put the whole image code, , inside the square brackets of a normal link, followed by the destination address in round brackets. The image becomes the link text, so clicking it opens the page. This is how most README badges work.
For example:
[](https://example.com/demo)
Read it from the inside out:  is the image, and the outer [...](https://example.com/demo) turns it into a link.
If you want to understand the same idea in HTML, email and documents, our guide to making a picture a clickable link covers each one.
How do I resize an image in Markdown?
The CommonMark spec has no syntax for width or height. Some tools add their own extensions, but they are not portable. The reliable approach is an HTML img tag with a width attribute, on platforms that allow HTML inside Markdown. Set only the width and the height scales automatically, keeping the image's proportions.
For example:
<img src="docs/images/screenshot.png" alt="Dashboard showing three charts" width="600">
Tips that save time:
- Set only the width. The height scales automatically and the image keeps its proportions.
- Use attributes, not CSS, on GitHub. GitHub sanitises HTML in Markdown. A port of GitHub's sanitiser rules, marked-sanitizer-github, lists
widthandheightas allowed attributes, butstyleis not on the list, so inline CSS sizes are stripped. - Resize the file itself too. Displaying a 4000-pixel screenshot at 600 pixels wide still makes everyone download the full file. Resize it before uploading.
For more on HTML image tags, including alt text and responsive sizing, see our guide to embedding an image in HTML.
GitHub README images
GitHub supports images in README files, other .md files, issues, pull requests, discussions and comments. Its basic writing and formatting guide says you can display an image from your repository, link to an online image, or upload one.
Images stored in the repository
GitHub recommends relative links for images in your repository. Its examples include:
| Where the Markdown is | Relative path example from GitHub's docs |
|---|---|
A .md file on the same branch | /assets/images/electrocat.png |
A .md file on another branch | /../main/assets/images/electrocat.png |
| Issues, pull requests and comments in the same repository | ../blob/main/assets/images/electrocat.png?raw=true |
GitHub explains that it transforms relative paths based on the branch you are viewing, and that paths starting with / are relative to the repository root. Relative paths also keep working when someone clones the repository.
A typical README setup looks like this:
my-project/
README.md
docs/
images/
screenshot.png
Uploading images to issues and comments
In an issue, pull request or comment, you can drag and drop an image into the comment box, click to browse for a file, or paste an image in many browsers. GitHub's page on attaching files lists a 10 MB maximum for images and GIFs, and supported image types including PNG, GIF, JPEG and SVG. It also notes that in public repositories, uploaded files can be accessed without signing in.
Dark and light themes
GitHub's formatting guide states that the HTML picture element is supported, which is how you can show a different image to readers using dark mode.
External images on GitHub
When you use an image hosted elsewhere, GitHub serves it through an anonymising proxy called Camo. GitHub's page on anonymized URLs explains the two most common reasons an external image does not appear: the server returns a Content-Type that Camo does not support, or the image is on a private network or behind a login. If you updated an image and GitHub still shows the old one, the same page explains how caching headers affect it.
Where should I host images for Markdown?
There are three main places to host a Markdown image. Keep images inside the repository for READMEs and project docs, upload them to an issue or comment for bug reports and discussions, or use an external image host for docs sites, wikis, forums and Markdown outside GitHub. For an external host, use the direct link to the image file.
Each suits a different case.
| Option | Best for | Watch out for |
|---|---|---|
| Inside the repository | READMEs and project docs | Large images make the repository bigger for everyone who clones it |
| Uploaded to an issue or comment | Bug reports and discussions | Files in public repositories are publicly accessible |
| An external image host | Docs sites, wikis, forums, Markdown outside GitHub | The image depends on the host staying online |
For an external host, you need the direct link to the image file (ending in .png, .jpg and so on), not a page that shows the image. A link to a viewer page renders as a broken image. Our explainer on direct links, viewer links and embed codes shows the difference.
With PictureToLink, you can paste or drop an image and copy the ready-made Markdown line. Honest caveats: we accept JPG, PNG, WebP, GIF and AVIF up to 25 MB (no SVG; iPhone HEIC photos are converted to JPG in your browser first), images are compressed and stripped of metadata, and an image is removed after 12 months without views. For a project's permanent documentation, keeping images in the repository is usually the more durable choice. For a quick image in a forum post, chat or wiki, an external host is faster.
Next step
Copy the template that fits your case, add meaningful alt text, and preview the file before you commit. If your image is not online yet, upload it to get a Markdown-ready link, then add your description between the square brackets.