Images make Markdown documents easier to understand and more engaging. Whether you're writing a GitHub README, project documentation, blog post, or notes, Markdown lets you insert images using a simple and consistent syntax.
This guide explains how to add images in Markdown, use image URLs, reference local files, write good alt text, and understand platform differences. Every example can be copied directly into your Markdown document.
Practice as you read: Open the Markdown Editor with live preview to test image syntax, or read the blog tutorial How to Add Images in Markdown for a step-by-step walkthrough.
The basic syntax is simple.
Example
This displays the image named logo.png with the alt text Project Logo.
If you're new to Markdown, start with Markdown Basics. For clickable images, see Markdown Links.
| Part | Description |
|---|---|
! |
Indicates an image |
[] |
Alternative text |
() |
Image path or URL |
The exclamation mark is what makes this different from a normal Markdown link.
You can display any publicly accessible image.
This is useful for:
If the image is inside your project folder:
Folder example
project/
│
├── README.md
└── images/
└── logo.png
Relative paths are recommended for GitHub repositories.
Relative path
Works inside the same project.
Absolute URL
Loads the image from another website.
GitHub supports normal Markdown image syntax.
Example
GitHub automatically renders the image inside README.md files.
For best results:
Alt text describes the image.
Benefits
Avoid
Better
Make an image clickable.
[](https://example.com)
Users click the image to open the link. This combines image and link syntax — the ! marks an image, and the outer [](url) wraps it in a link.
Standard Markdown does not support image resizing.
This does not work in most parsers:
{width=200}
Many platforms ignore this syntax entirely.
If your Markdown platform supports HTML:
<img src="logo.png" width="250" alt="Logo">
You can also specify:
widthheightloadingstyle (depending on platform)You can add a title attribute.
Some Markdown renderers display this as a tooltip when users hover over the image.
Most Markdown editors support:
Support may vary depending on the platform.
Repository logo
Screenshot
Remote image
Clickable image
[](https://example.com)
Check:
Wrong
Correct
Instead of
Use
Verify the image URL is publicly accessible before publishing.
| Platform | Image Support |
|---|---|
| GitHub | ✅ Full |
| GitLab | ✅ Full |
| Obsidian | ✅ Full |
| VS Code Preview | ✅ Full |
| Notion | Partial |
| Discord | Partial |
| Limited |
Continue learning Markdown with these guides:
Available now
Coming soon to MDConvertHub Docs
Open the Markdown Editor to test image syntax with live preview.
Use  and replace image.png with your image path or URL.
Yes. Use  with any publicly accessible image URL.
Standard Markdown does not support resizing. Use HTML <img> tags if your platform allows it.
Usually because of a wrong file path, incorrect filename, missing file, or broken URL.
Yes. Relative paths are recommended for GitHub repositories because they continue working when the repository is cloned.
Yes. GitHub fully supports Markdown image syntax in README files, documentation, issues, pull requests, and Wikis.