Markdown Image Syntax
How to insert images in Markdown. Covers the core  syntax, clickable and reference-style images, relative paths, resizing and centering, GitHub dark-mode images, and which platforms render images at all.
Short answer
Type an exclamation mark, alt text in square brackets, and the image URL in parentheses: . Markdown has no size or alignment syntax. To resize an image on GitHub and most renderers, use HTML instead: <img src="image.png" width="300">.
Basic Syntax
A Markdown image starts with an exclamation mark, followed by alt text in square brackets, followed by the image URL in parentheses.
Image Titles
Add a quoted title after the URL. It renders as a tooltip on hover in most browsers and is useful for extra context. It is not a visible caption.
Reference Images
Reference-style images keep long URLs out of your paragraphs. Use ![alt][id] inline, then define [id]: url on its own line later in the document.
![MarkdownFormatting logo][logo]
[logo]: https://markdownformatting.com/favicon.svg "Site logo"
Clickable Images
Wrap the image syntax in link syntax to make the image itself clickable. This is common for banners and thumbnails.
[](https://markdownformatting.com)Relative Paths
Use relative paths for images stored with your Markdown files. ./ and ../ resolve from the file that contains the image; a leading / resolves from the site root, which on GitHub is the repository root. These previews show broken images because the files only exist in your project.
Resize & Center Images
Standard Markdown cannot set width, height, or alignment. Use an HTML <img> tag when the renderer allows it. GitHub keeps width, height, and align but strips style, so CSS sizing does not work there. Set only the width to keep the aspect ratio.
<img src="https://placehold.co/600x300?text=Example+Image" alt="Example image" width="300" /><p align="center">
<img src="https://placehold.co/600x300?text=Example+Image" alt="Centered image" />
</p>
Image size syntax by platform
| Platform | Syntax | Notes |
|---|---|---|
| GitHub, VS Code, most renderers | <img src="img.png" width="300"> | HTML only. GitHub keeps width, height, and align but strips style. |
| GitLab | {width=300} | Attribute list after the image; px (default) or %. |
| Obsidian |  or ![[img.png|300]] | Width in pixels; add x200 for a height. |
| Pandoc | {width=50%} | Attribute syntax, also used by Quarto. |
| CommonMark / Discord / Slack / Reddit | None | No size syntax. Resize the file itself. |
More centering options, including badges and tables, are in the center text guide.
Dark Mode Images on GitHub
A dark logo disappears on GitHub's dark theme. Use the HTML <picture> element: the <source> with prefers-color-scheme: dark is used in dark mode, and the <img> is the light-mode default and the fallback everywhere else. The preview follows your device's color scheme.
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://placehold.co/400x100/18181b/fafafa?text=Dark+mode+logo">
<img alt="Project logo" src="https://placehold.co/400x100/fafafa/18181b?text=Light+mode+logo">
</picture>GitHub made <picture> theme switching generally available in August 2022. The older trick of appending #gh-dark-mode-only or #gh-light-mode-only to an image URL is GitHub-specific and no longer in GitHub's docs. Everywhere else it shows both images.
Alt Text
Alt text describes the image for screen readers and search engines, and shows when the image fails to load. Keep it short and specific. Skip "image of", since screen readers already announce an image. Formatting inside the brackets is flattened to plain text, and a decorative image can have empty alt text: .
Good: ![A crescent moon over a dark ocean]
Bad: ![image]
Common Mistakes
The five most common reasons a Markdown image fails. Each row shows the broken version and the corrected one side by side.
Broken
[Alt text](https://example.com/image.png)Fixed
Broken
Fixed
Broken
Fixed
Broken
Broken
![Alt text][logo]
[logo] https://example.com/image.pngFixed
![Alt text][logo]
[logo]: https://example.com/image.pngQuick Reference
| Syntax | What it does |
|---|---|
|  | Inline image |
|  | Inline image with tooltip |
| ![alt][id] | Reference image marker |
| [id]: url "title" | Reference image definition |
| [](url) | Clickable image |
|  | Relative-path image |
|  | Path with spaces |
| <img src="" alt="" width="300" /> | HTML fallback for sizing |
| <p align="center"><img ...></p> | Centered image (works on GitHub) |
| <picture><source media="(prefers-color-scheme: dark)" ...> | Separate dark-mode image |
|  | Obsidian: set width |
| {width=300} | GitLab: set width |
Platform Support
Document renderers all support images. Chat apps mostly do not: Discord and Slack have no image syntax, and Reddit only renders typed images on wiki pages. Everywhere else, the differences are in HTML attribute handling and relative-path resolution.
| Platform | Supported? | Notes |
|---|---|---|
| GitHub | Yes | Inline, reference, and HTML images. Relative paths resolve in the repository. <img> keeps width, height, and align; style is stripped. <picture> works for light/dark images. |
| GitLab | Yes | Same core syntax, plus {width=…} and {height=…} after an image. |
| Partial | Typed image syntax does not render in posts or comments. Upload through the editor instead. Community wiki pages do render it. | |
| Discord | No | No image syntax. Upload the file or paste a direct image URL, which Discord embeds as a preview. |
| Slack | No | No image syntax. In an app's markdown block,  becomes link text. Upload the file or use an image block. |
| Notion | Partial | Use /image, drag the file in, or paste from the clipboard. Notion's shortcut list has no Markdown image syntax. |
| Obsidian | Yes | Standard syntax works, plus ![[image.png]] embeds for vault files. Resize with |300. |
| VS Code preview | Yes | Renders Markdown and HTML images. Relative paths resolve from the open file. |
| CommonMark | Yes | Inline and reference images are core syntax. No size or alignment syntax. |
| Docusaurus / VitePress / Astro | Yes | Relative paths resolve according to the site config; HTML img also works. |
Frequently Asked Questions
How do you add an image in Markdown?
Type an exclamation mark, the alt text in square brackets, and the image URL or path in parentheses: . The ! is what makes it an image; without it you get a link.
How do I resize an image in Markdown?
Standard Markdown has no size syntax, so use an HTML tag where the renderer allows it: <img src="image.png" alt="Diagram" width="300">. GitHub keeps width and height but strips style attributes. Some renderers have their own syntax: GitLab accepts {width=300}, Obsidian accepts , and Pandoc accepts {width=50%}.
How do I center an image in Markdown?
Wrap an HTML image in a block with the align attribute: <p align="center"><img src="image.png" alt="Logo"></p>. This works on GitHub because align survives its sanitizer, while style="text-align:center" does not.
How do I add an image to a GitHub README?
Commit the image to the repository and reference it with a relative path, such as . GitHub recommends relative paths for images stored in the repo. In issues, pull requests, and comments you can also drag, drop, or paste an image, and GitHub uploads it and inserts the Markdown for you.
Can I show a different image in dark mode on GitHub?
Yes. Use the HTML <picture> element with a <source media="(prefers-color-scheme: dark)" srcset="dark.png"> and an <img> fallback for light mode. GitHub has supported this since 2022. The older #gh-dark-mode-only URL fragment is GitHub-only and no longer in GitHub's docs, and other renderers show both images.
What is alt text in a Markdown image?
Alt text is the text inside the square brackets. Screen readers read it aloud, and browsers show it if the image fails to load. Describe what the image shows: . For a purely decorative image, leave it empty: .
Can you add a title or caption to a Markdown image?
You can add a title in quotes after the URL: . Browsers show it as a tooltip on hover; it is not a visible caption. For a caption, put a line of italic text directly under the image, or use HTML where it is allowed.
How do you make an image a link in Markdown?
Put the image syntax inside link syntax: [](https://example.com). The image becomes the clickable element. This is how most README badges are built.
Do relative paths work for images in Markdown?
Yes. ./image.png points to the same folder as the Markdown file, and ../images/diagram.png goes up one folder first. A path starting with / resolves from the site root; on GitHub that is the repository root. Encode spaces in file names as %20.
Why is my Markdown image not showing?
Check that the ! comes right before the [, the closing parenthesis is there, spaces in the URL are encoded as %20, external URLs start with https://, and the relative path is right for where the file lives. If the syntax is correct, the platform may not render images at all: Discord, Slack, and Reddit comments do not.
Can I use Markdown inside image alt text?
You can type it, but the formatting is flattened.  produces alt="A very large file". Write alt text as plain words.
Does Discord support Markdown images?
No. Discord has no image syntax. Upload the image, or paste a direct link to an image file and Discord embeds a preview of it.