Images make a document easier to scan, explain ideas faster than words, and give a Markdown file a polished, professional look. Whether you're writing a README, a blog post, or project notes, learning how to add image in markdown is one of the highest-leverage skills you can pick up. The good news is that basic markdown image syntax is tiny — the rest is learning the small tricks that make images behave the way you want. This guide walks through inserting images, writing useful alt text, choosing the right URL, turning an image into a clickable link, resizing it, aligning it, and avoiding the mistakes that leave you with a broken icon on the page.
The Basic Markdown Image Syntax
The standard way to insert a markdown image is the "bang-bracket-paren" pattern, which mirrors the syntax for a link:
Breaking it down:
!— tells the parser this is an image, not a link.[alt text]— a short description, shown if the image fails to load and read aloud by screen readers.(url)— the path to the image file, which can be a full web URL or a relative file path.
You can also add an optional tooltip title in quotes:
That title appears as a small hover tooltip in most browsers. Want to test it right now? Paste any image line into our editor and it will render instantly, entirely in your browser so nothing gets uploaded.
Writing Good Alt Text (Accessibility and SEO)
Alt text is the part most people under-invest in, but it does two real jobs: it makes your document accessible to readers using screen readers, and it gives search engines (and AI tools) a textual signal about what the image shows. A useful pattern is to describe the content and purpose of the image in one short sentence.
Good examples:
Weak examples to avoid:
A few rules of thumb: be specific, skip phrases like "image of" or "picture of" (screen readers already announce that), and leave alt text empty ( only) for purely decorative images so they're ignored by assistive tech. For more on link and reference patterns that pair with images, see our guide to links.
Local vs Remote, Relative vs Absolute URLs
Where your image lives changes how portable your document is.
Remote URLs point to a file hosted somewhere on the web:
These work anywhere, but they depend on the external host staying up — if the CDN goes down or the file is moved, your image breaks.
Local / relative URLs point to a file inside your own repository:
This is the safest choice for project docs and READMEs, because the image travels with the file. Prefer relative paths like ./assets/... over absolute paths like /Users/you/project/assets/..., which only exist on your machine.
Absolute local paths (like file:///Users/... or C:\images\...) almost never render for anyone but you, and they'll show up as broken images for everyone else. Avoid them.
Making an Image a Clickable Link
A common pattern is wrapping an image inside a link so clicking it opens another page. You nest the image syntax where the link text would normally go:
[](https://example.com)Read it from the inside out: the inner  is the image, and the outer [ ... ](https://example.com) turns it into a link. This is the exact technique used for badges and "View on GitHub" buttons in READMEs — covered in depth in our README guide.
How to Resize Images in Markdown
Here's the catch that surprises everyone: standard Markdown has no built-in syntax for setting image width or height. The  form gives you no size control at all. To do a markdown resize image, you have to reach for one of the workarounds below.
| Approach | Syntax example | Works where? | Pros | Cons |
|---|---|---|---|---|
Raw HTML <img> |
<img src="logo.png" width="200"> |
Almost everywhere (GitHub, most static-site generators) | Full control over width/height/style | Not "pure" Markdown |
GitHub #w=N / #h=N hint |
 |
GitHub only | Stays in Markdown syntax | Proprietary; ignored elsewhere |
| CSS class (static-site generators) | {: .small } |
Hugo, Jekyll, Astro, etc. | Reusable styles | Needs configured pipeline |
| Pre-sized image file | Upload a 200px-wide file | Anywhere | No code tricks needed | Manual re-export for each size |
The HTML <img> tag is the most reliable cross-platform option. Here's a full example with width, height, and alignment hints:
<img src="/assets/screenshot.png"
alt="Results dashboard"
width="600"
title="Click to enlarge">If you publish on GitHub specifically, the custom #w=200 / #h=100 hint can be handy, but remember it's a GitHub-flavored markdown extension — your image will render full-size everywhere else. See our GFM guide for more GitHub-specific quirks.
Image Alignment Workarounds
Alignment is the other thing standard Markdown doesn't give you. In practice you have three options.
Use HTML with inline styles — the most portable approach:
<div align="center">
<img src="/assets/banner.png" alt="Banner" width="500">
</div>Use an HTML <img> with a style attribute:
<img src="/assets/portrait.png" alt="Author" style="float: right; margin-left: 12px;">Use a table as a crude two-column layout, which still works in plain Markdown environments:
| Left | Right |
|------|-------|
|  |  |None of these is elegant, but together they cover almost every real-world case.
Common Image Mistakes (and How to Fix Them)
Most broken images come from a small set of avoidable errors:
- Broken path. The URL doesn't match where the file actually is. Double-check the case, the extension (
.jpgvs.jpeg), and that the file is committed to the repo. Relative paths like./assets/x.pngshould be checked against the location of the.mdfile, not the repo root. - Missing or empty alt text.
works, but it gives screen readers and search engines nothing. Always add a meaningful description unless the image is purely decorative. - Spaces in filenames.
my photo.pngbreaks the URL parsing. Rename tomy-photo.pngormy_photo.png, or URL-encode the space as%20. - Hotlinking fragile URLs. Linking to an image on someone else's server means it can vanish without warning. Download the image and host it yourself whenever the license allows.
- Huge unoptimized files. A 6 MB screenshot slows the whole page. Resize and compress before committing.
- Expecting size control from pure Markdown. Remember — there's no native way to markdown resize image, so reach for the
<img>tag instead of being surprised when nothing changes.
Frequently Asked Questions
Can I set image width in pure Markdown?
No. The original Markdown spec has no syntax for width or height, so  always renders at the image's natural size. Use an HTML <img> tag with a width attribute, or one of the platform-specific tricks listed in the table above.
How do I add a local image to a GitHub README?
Commit the image into the repository (a folder like /assets or /docs/images is conventional) and reference it with a relative path:
Relative paths travel with the repo and keep working after forks and clones. See our README guide for the full setup.
Why is my image showing a broken link icon?
It's almost always the path. Check the exact filename (case-sensitive), the file extension, and whether the file is actually committed. Also confirm there are no spaces in the filename, and that you're not using an absolute local path like /Users/.../x.png that only exists on your machine.
How do I make an image act as a link?
Wrap the image inside a link — put the whole  expression where the link's text would go:
[](https://shop.example.com)This is the standard pattern for clickable badges, buttons, and logos.
Wrapping Up
Working with images in Markdown is mostly about mastering one tiny syntax —  — and then learning a handful of HTML escape hatches for the things Markdown itself doesn't handle, like size and alignment. Write clear alt text, keep paths relative, host the files alongside your document, and reach for an <img> tag whenever you need real layout control. Drop a few lines into the editor to practice, and your next README or doc will look as good as it reads.
Try it in your browser
Open the homepage editor to view, edit, and export Markdown instantly — no install required.