Markdown Images: Syntax, Alt Text, and Sizing
How to add images in markdown with proper alt text, sizing, captions, and links. Covers inline images, reference-style, and platform-specific behavior.
Last updated: March 4, 2026
Images in markdown use a syntax almost identical to links, with an exclamation mark prefix: . The alt text describes the image for screen readers and displays when the image fails to load.
This guide covers the full image syntax, sizing options, captions, linked images, and how different platforms handle each feature.
Basic Syntax
The three parts:
!signals this is an image, not a link[alt text]describes the image content(url)points to the image file
You can add a title (tooltip) after the URL:
Local vs Remote Images
Local (relative path):
Relative paths work when the markdown is rendered from the same project or repository. The path is relative to the markdown file or the project root, depending on the renderer.
Remote (absolute URL):
Remote URLs work everywhere, but the image depends on the external server being available. For documentation that might be read offline or archived, local images are more reliable.
Reference-Style Images
Like reference-style links, you can separate the URL from the content:
![Editor screenshot][editor-img]
[editor-img]: /images/editor.png "The markdown editor"This keeps paragraphs clean when you have many images. The definition can go anywhere in the document.
Alt Text Best Practices
Alt text serves two purposes: accessibility (screen readers read it aloud) and fallback (shown when the image cannot load).
Good alt text:
- Describes what the image shows, not what it is
- Is concise (under 125 characters)
- Adds context that the surrounding text does not provide
<!-- Weak -->
<!-- Better -->Decorative images that add no informational value can use empty alt text:
Screen readers skip images with empty alt text, which is correct behavior for decorative elements.
Image Sizing
Standard markdown has no syntax for image dimensions. When you need to control size, you have two options.
HTML img tag:
<img src="/images/logo.png" alt="MDtoLink logo" width="200" />This is the most widely supported approach. You can set width, height, or both. Use only one dimension and let the browser calculate the other to preserve aspect ratio.
Some extended markdown syntaxes:
Obsidian supports a pipe-based size syntax:
This is Obsidian-specific and will not work on GitHub, VS Code, or other platforms.
Kramdown (used by Jekyll) supports attribute lists:
{: width="200" }For portable documents, stick with the HTML <img> tag.
Linked Images
Wrap the image syntax inside a link to make the image clickable:
[](https://mdtolink.com)Structure: [ + image syntax + ] + (link url).
This is commonly used for badges in README files:
[](https://github.com/user/repo/actions)Image Captions
Markdown has no native caption syntax. Here are the common workarounds:
Italic text below the image:
*Figure 1: Monthly active users from January to June 2026*HTML figure element:
<figure> <img src="/images/growth.png" alt="Chart showing monthly growth" /> <figcaption>Figure 1: Monthly active users from January to June 2026</figcaption></figure>The HTML approach is semantically correct and works well with screen readers. Some markdown processors (like Pandoc) support caption attributes, but this is not standard.
Images in Other Elements
Image in a table cell:
| Preview | Description ||---------|-------------||  | The default dark theme |Keep table cell images small. Large images can break table layout.
Image in a list:
1. First step 2. Second stepIndent the image line to match the list continuation (3 spaces for ordered lists).
Image in a blockquote:
> > "Markdown is the best writing format." - John GruberPlatform Differences
| Feature | GitHub | VS Code | Obsidian | MDtoLink | CommonMark |
|---|---|---|---|---|---|
Basic  | Yes | Yes | Yes | Yes | Yes |
| Reference-style images | Yes | Yes | Yes | Yes | Yes |
| Title attribute (tooltip) | Yes | Yes | Yes | Yes | Yes |
HTML <img> tags | Partial | Yes | Limited | Yes | Parser-dependent |
Custom sizing (width) | Via HTML | Via HTML | Pipe syntax | Via HTML | No |
| SVG images | Rendered | Rendered | Rendered | Rendered | Parser-dependent |
| Lazy loading | Automatic | N/A | N/A | Automatic | N/A |
| GIF/animated images | Yes | Yes | Yes | Yes | Yes |
<figure> + <figcaption> | Stripped | Yes | No | Yes | Parser-dependent |
GitHub strips many HTML tags for security, including <figure>. The <img> tag with width and height attributes is allowed.
Common Mistakes
Missing the exclamation mark. Without !, you get a link instead of an image:
<!-- This is a link, not an image -->[Logo](/images/logo.png)
<!-- This is an image -->Broken relative paths. When you move a markdown file, relative image paths break. Use absolute paths or keep images in a predictable location like /images/ or ./assets/.
Empty alt text when alt text is needed. Every informational image should have descriptive alt text. Only use empty alt text (![]()) for decorative images like dividers or backgrounds.
Copy-Paste Templates
Basic image:
Image with title:
Linked image:
[](https://example.com)Sized image (HTML):
<img src="/images/filename.png" alt="Description" width="400" />Image with caption:
*Caption: Explanation of the image*Reference-style image:
![Description][img-ref]
[img-ref]: /images/filename.png "Optional title"FAQ
How do I add an image in markdown?
Use . The alt text goes in square brackets and the image URL goes in parentheses. Example: .
How do I resize an image in markdown?
Standard markdown does not support image sizing. Use an HTML <img> tag instead: <img src="/images/photo.png" alt="My photo" width="300" />. Set one dimension and the browser preserves the aspect ratio.
How do I make an image a link in markdown?
Wrap the image syntax inside link brackets: [](https://example.com). The image becomes clickable and navigates to the URL.
What is the difference between markdown images and links?
The only syntactic difference is the ! prefix. Links: [text](url). Images: . Links create clickable text; images embed a visual element in the document.
Try It Out
Add images to your markdown and preview them live in the MDtoLink editor. When your document is ready, publish it to a shareable URL with one click.
For the full syntax, see the markdown cheat sheet. To learn about links (which share a similar syntax), check the markdown links guide.
Founder, MDtoLink
David builds developer tools and writes about markdown workflows, documentation, and AI-assisted publishing.
Publish your markdown to a shareable URL
One command. Free to start. No credit card.