The syntax is . It is a link with an exclamation mark in front. So  shows that picture wherever the line sits, at its natural size, with no upload step and no HTML.
The alt text in the brackets describes the picture for screen readers and search engines. It also appears in place of the image when the file fails to load, so write it properly rather than leaving it empty.
Everything else about images varies by platform: sizing, hosting, and whether you can drag a file in. The sections below take each one in turn, and our editor renders the result as you type.
At a glance
| Syntax |  |
|---|---|
| Alt text | Optional in the syntax, expected in practice |
| Sizing support | None in core Markdown, use an HTML img tag |
| Local vs hosted | Relative paths travel with a repo, https works anywhere |
| Drag and drop | Supported by GitHub, GitLab, Notion and Obsidian |
The syntax, piece by piece
- Write
. The exclamation mark is what turns a link into a picture. - Alt text is optional in the syntax and expected in practice, because it stands in when the file fails.
- Relative paths travel with a Git repository, while an https URL works anywhere the document opens.
- Markdown has no width setting, so resizing means an HTML img tag or a smaller file.
Add an image by writing . The exclamation mark, the alt text in square brackets and the path in parentheses are the three parts, in that order:
What each part does
- The exclamation mark says "embed this", not "link to it". Drop it and you get a text link. That is the most common typo in the whole syntax.
- The square brackets hold the alt text.
- The parentheses hold the URL, plus an optional quoted title that some browsers show on hover.
Both lines above turn into an <img> tag. The first becomes <img src="images/bike.jpg" alt="A red bicycle leaning against a brick wall">. Nothing is copied or embedded, because Markdown only ever holds a reference. That is why a broken image nearly always means a broken URL.
Add an image in four steps
- Put the image file where it will live, either beside the document or on a host you control.
- Copy its address. On GitHub, open the file and take the
rawlink, not theblobone. - Type
, all on one line. - Check the result. Dropping the file into the Markdown viewer renders it without changing anything.
Two patterns are worth stealing from READMEs. To make a picture clickable, nest it inside a link: [](target-url). To keep long CDN addresses out of your prose, use a reference: write ![Chart][chart] in the body, then [chart]: https://cdn.example.com/chart.png once at the bottom, exactly the way reference-style links work.
Alt text that earns its place
Good alt text describes what the picture shows in a phrase or a short sentence. "Screenshot of the export menu with the .html button highlighted" beats "screenshot". Both beat an empty pair of brackets. Screen readers announce it, search engines index it, and readers on a slow connection see it first.
Three habits worth copying
- Describe the content, not the file. "Quarterly revenue rising from 2 to 5 million" tells a reader something. "chart.png" tells them nothing.
- Skip the words "image of". Assistive software already announces that it is an image.
- Leave the brackets empty for decoration. A divider or a spacer needs no description, and silence beats noise.
When the picture holds the information
Sometimes an image carries something the text around it does not, such as a diagram, a chart or a screenshot of a table. Sum it up in the alt text, or repeat the point in the paragraph nearby. An image is the one part of a Markdown file that cannot be read as plain text, so anything shown only in the picture is invisible to part of your audience.
Relative paths, absolute URLs and hosting
An absolute URL that starts with https works anywhere the document is opened. It breaks on the day the remote host removes the file. A relative path such as images/diagram.png is resolved against the Markdown file itself.
 relative: repo-friendly
 absolute: works anywhere
Relative paths are ideal inside a Git repository. The images travel with the document, and reviewers see them in every branch. Paste that same Markdown somewhere the folder does not exist and you get nothing at all.
Hosting is really a question of who controls the file. Inside a project, commit images next to the docs so they stay versioned. For blogs and shared notes, use your own media storage or a proper image host. Hotlinking from a site you do not control is a slow-motion accident.
Watch out: a space in a URL stops the parser dead, so encode it as %20. And on GitHub, the link copied from a file page is a blob address that returns a web page rather than an image.
Resizing an image needs HTML
Markdown has no width or height option. An image renders at its natural pixel size, which is why an untouched phone screenshot can swallow a whole screen. There is no colon trick and no clever workaround. Sizing means dropping down to an HTML tag.
<img src="images/screenshot.png" alt="Settings page" width="420">
Set width on its own and the height scales with it. GitHub accepts a percentage too. Nearly every renderer honours the tag, including this site's preview pane.
What the HTML fallback costs you
- A few strict renderers ignore inline HTML, and sanitizing content systems strip it out entirely.
- Nothing inside an
<img>tag is processed as Markdown, so keep the tag on its own line. - The document stops being portable plain text, which is half the point of choosing Markdown over HTML.
The better fix is usually a smaller file
Resize the picture before you add it. A PNG that is 400 pixels wide loads faster, prints cleanly and needs no HTML at all. The images reference goes further into formats, folders and hosting habits.
Image support across platforms
The syntax is standard. What surrounds it is not. This is how the common destinations behave.
| Platform |  syntax | Drag and drop upload | HTML width sizing |
|---|---|---|---|
| GitHub | Yes | Yes, into issues and the editor | Yes |
| GitLab | Yes | Yes | Yes |
| No | Yes, as an image post | No | |
| Discord | No | Yes, as an attachment | No |
| Notion | On paste | Yes | Drag the corner instead |
| Obsidian | Yes, plus wiki-style embeds | Yes, into the vault | Yes |
| VS Code preview | Yes | Yes, with a modifier key | Yes |
The pattern behind the table
Developer platforms give you the full syntax. Chat apps give you uploads instead. On Discord and Reddit, a bare image URL on its own line is embedded for you, which is the working equivalent. Obsidian adds a wiki-style embed on top of the standard form, as the Obsidian guide explains.
Four mistakes that break an image
Broken images nearly always come from one of four small slips.
Broken Fixed
[Logo](logo.png) 
![Logo] (logo.png) 
 
 
Reading those four lines
- Line one forgot the exclamation mark, so it renders as a plain text link.
- Line two has a space between
]and(, and the parser will not bridge it. - Line three has an unencoded space in the filename.
- Line four points at one particular computer, so it works for one person and fails for everyone else.
When the syntax is right and the image still fails
Open the URL in a browser tab on its own. A 404, a login wall and a hotlink block all produce the same silent empty box in the document. Pasting the file into the editor separates a syntax problem from a hosting problem in seconds.
From there the reference pages take over. The complete Markdown guide covers images beside links, the cheat sheet keeps the syntax one glance away, and converting to HTML explains what happens to image paths on export.
Related questions
Try the Editor
Open Editor