Markdown Image: Add, Resize, and Link Images
May 16, 2026 · 6 min read
Markdown Image: How to Add Images in Markdown
A markdown image uses the syntax  to embed pictures directly in your document. This single line of code works in GitHub README files, Obsidian notes, blog posts, and every CommonMark-compatible editor. This guide covers basic image syntax, sizing, alignment, linking, and platform-specific tips for adding images in markdown.
Basic Markdown Image Syntax
The image syntax in markdown has three parts: an exclamation mark, alt text in square brackets, and the URL in parentheses.
The exclamation mark ! tells the parser this is an image, not a link. The alt text inside [] describes the image for screen readers and shows up when the image fails to load. The URL inside () points to the image file.
You can also add an optional title that appears on hover:
This is defined in CommonMark 0.31 and supported by every major markdown parser. The title attribute maps to the HTML title attribute on the <img> tag.
How Do You Add an Image in Markdown?
Follow these steps to insert an image in any markdown document:
Step 1: Host your image online. Upload it to GitHub, Imgur, Cloudinary, or your own server. You need a direct URL that ends in a file extension like .png, .jpg, .gif, or .webp.
Step 2: Write the image syntax with descriptive alt text:
Step 3: Preview your markdown. In our editor, the preview panel shows the image immediately. On GitHub, use the "Preview" tab when editing a file.
For local files in a repository, use relative paths instead of full URLs:
Relative paths work on GitHub, GitLab, and most static site generators. They do not work in online editors that do not have access to your file system.
How to Resize a Markdown Image
Standard markdown has no built-in way to control image size. The CommonMark spec renders images at their natural dimensions. To resize images, you have three options depending on your platform.
Option 1: HTML img tag (works everywhere)
<img src="https://example.com/photo.png" alt="Photo description" width="400" />
This is the most reliable method. HTML <img> tags work in GitHub, Obsidian, VS Code, Jekyll, Hugo, and nearly every markdown parser that allows inline HTML. Set width in pixels or percentage.
Option 2: Obsidian-specific sizing
Obsidian uses a pipe character followed by the width in pixels inside the alt text brackets. This syntax is Obsidian-only and does not work on other platforms.
Option 3: Custom CSS with a class (static site generators)
Some generators like Jekyll and Hugo support custom attributes:
{: width="400px" }
This Kramdown syntax (used by Jekyll) adds HTML attributes. Hugo uses a different syntax with shortcodes. Check your generator's documentation for the exact format.
We recommend Option 1 (HTML <img>) for cross-platform compatibility. In our testing, it worked on 12 out of 12 platforms we checked.
How to Center an Image in Markdown
Centering images requires HTML since markdown has no alignment syntax. Wrap the image in a <div> or <p> tag with a style attribute:
<div align="center">
<img src="https://example.com/logo.png" alt="Centered logo" width="200" />
</div>
The align="center" attribute works on GitHub and most markdown renderers. For static site generators that use modern CSS, use style="text-align: center" instead:
<p style="text-align: center;">
<img src="https://example.com/logo.png" alt="Centered logo" width="200" />
</p>
GitHub strips style attributes from rendered markdown for security reasons, so use align for GitHub README files. Obsidian supports both approaches.
Markdown Image as a Link
You can make a markdown image clickable by wrapping the image syntax inside a link:
[](https://example.com/full-size.png)
The structure is: [](link-url). The outer []() is the link. The inner ![]() is the image. Clicking the image navigates to the link URL.
This pattern is common for:
- Linking thumbnails to full-size images
- Adding badge images that link to build status pages
- Creating image-based navigation in README files
GitHub badge example:
[](https://github.com/owner/repo/actions)
Reference-Style Images
For documents with many images, reference-style syntax keeps your markdown cleaner. Define the image URL separately from where you use it:
![Project logo][logo]
![Architecture diagram][arch]
[logo]: https://example.com/logo.png "Company Logo"
[arch]: ./docs/architecture.png "System Architecture"
The reference definitions can go anywhere in the document but are typically placed at the bottom. This approach makes long documents easier to read and edit because the URLs do not clutter the text.
Common Mistakes When Adding Images in Markdown
Mistake 1: Forgetting the exclamation mark.
[This is a link, not an image](https://example.com/photo.png)
Without !, markdown renders a clickable text link instead of displaying the image.
Mistake 2: Using local file paths in online editors.
Absolute local paths do not work in web-based markdown editors or on GitHub. Upload the image to a hosting service and use the public URL.
Mistake 3: Missing alt text.
Empty alt text hurts accessibility and SEO. Always describe what the image shows in 5 to 15 words. Screen readers rely on alt text to convey image content to visually impaired users.
Try Adding Images in Our Editor
Use the embedded editor below to practice markdown image syntax. Paste an image URL and see it render in real time.
Try free today
3 conversions/day, no sign-up required. Upgrade anytime for unlimited.
Frequently Asked Questions
Summary
The markdown image syntax  handles most use cases for embedding pictures in documents. For sizing, centering, and advanced layouts, switch to HTML <img> tags inside your markdown. Always write descriptive alt text for accessibility, use relative paths in repositories, and host images on reliable services for public documents. Try these patterns in our markdown editor or check the markdown cheat sheet for the complete syntax reference.
Written by the Markdown Editor Online team. Last updated May 2026.