Markdown Image Syntax Guide: Add Images Correctly
Markdown image syntax guide: learn how to add images, write alt text, link images, and handle sizing or centering across Markdown platforms.
Introduction
Markdown image syntax is simple: . The challenge is that the same syntax can behave differently in a README.md, a blog CMS, or a documentation site. This guide explains how to add images in Markdown, write useful alt text, link images, and handle sizing or centering when a platform supports them.
Markdown is source text; a renderer turns it into HTML. That renderer may follow CommonMark, GitHub Flavored Markdown, or platform-specific rules, so an image can display one way in GitHub and another way in a static site generator or editor. If you want a broader refresher, Markdown basics and Markdown for docs are useful starting points.
You will learn what Markdown image syntax is, how to add an image in Markdown, what alt text means, how to link an image, when to use HTML instead of Markdown, and why an image may not show up.
What Is Markdown Image Syntax?
Markdown image syntax uses the pattern . The exclamation mark turns a normal Markdown link into an image, while the alt text describes the image for screen readers and for cases where the file fails to load. A regular link uses [text](url) with no exclamation mark.
Behind the scenes, a Markdown renderer usually converts that syntax into an HTML img tag. That conversion is why images display in places that support Markdown, including many CommonMark and GitHub Flavored Markdown environments.
Support still depends on the platform and its Markdown flavor. Some systems allow captions, sizing, or raw HTML; others restrict them or ignore image syntax entirely. For a quick refresher on related syntax, see the Markdown cheat sheet and Plain text formatting with Markdown.
How Do You Add an Image in Markdown?
To add an image in Markdown, choose the file and decide whether it will live in your project or be hosted elsewhere. For a local file in README.md or documentation, use a relative path: . For an externally hosted image, use an absolute URL: .
In developer docs, verify the path from the Markdown file’s location, not from your computer’s desktop. Preview the rendered Markdown in GitHub, your CMS, or a local editor to confirm the image loads. Common failures come from wrong folders, typos in filenames, case sensitivity, and missing file extensions such as .png, .jpg, or .svg.
What Does Alt Text Mean in Markdown Images?
Alt text is the text alternative read by screen readers and shown when an image fails to load. In Markdown, it supports accessibility in docs, developer docs, and any Markdown for docs workflow. Write it to convey purpose, not pixels.
For a screenshot, use something like “GitHub pull request review screen with two unresolved comments” instead of listing every button on the page. For charts and diagrams, state the takeaway, such as “Line chart showing traffic rising after the site redesign,” rather than “bar chart.” Decorative images should use empty alt text when the platform allows it, or be omitted if they add no value.
For accessible screenshots, include the action, the key UI state, and the outcome the reader needs to notice.
How Do You Link an Image in Markdown?
To make an image clickable, wrap it in a normal Markdown link: [](https://example.com). That creates a linked image. A regular Markdown link and a Markdown image are different: a link sends the reader to another page, while an image displays visual content. If you need both behaviors, combine them as shown above.
Markdown does not have a universal caption syntax. Use surrounding text, an HTML figure/figcaption, or the title attribute when your Markdown style guide allows it. The title attribute can provide a hover label, but it is not a reliable replacement for a visible caption.
Can You Resize Images in Markdown?
Plain Markdown does not provide a standard way to resize images. Some platforms add extensions, but the portable option is to use the HTML img tag with width and height attributes when you need precise control. For example:
<img src="images/chart.png" alt="Sales chart" width="600">
If you are writing for GitHub, GitLab, Bitbucket, or a Markdown renderer used by a static site generator, check the platform’s rules before relying on resizing. In many documentation systems, HTML is the safest fallback when layout matters.
How Do You Center an Image in Markdown?
Markdown itself does not define centering. If your platform allows raw HTML, wrap the image in a centered container or use an HTML img tag with alignment styling. For example:
<p align="center">
<img src="images/diagram.svg" alt="System diagram" width="700">
</p>
This approach is common in GitHub README.md files, but support can vary in documentation tools and CMS editors. If centering is important to the layout, test it in the final renderer instead of assuming Markdown alone will handle it.
Image URLs, Relative Paths, and File Hosting
A relative path points to a file inside the same project, such as . It is usually best for GitHub README.md files and project docs because it moves with the repo and stays portable in version control. An absolute URL points to a full web address, such as , which works well for blogs, CMSs, and shared docs when images live on a CDN or media server.
For maintainable Markdown for documentation, keep local assets in the repo when you can; use hosted URLs when the image is managed outside the project or reused across sites. Be careful with hotlinking: some platforms block, rewrite, or cache external image URLs, so a link that works today can break later.
Static site generator workflows add another constraint. Jekyll, Hugo, MkDocs, and Docusaurus often expect images in specific asset folders or paths that match the build output. For Markdown docs best practices and a clean Markdown style guide, prefer the simplest path that survives repo moves, site builds, and long-term updates.
Linking, Captions, Resizing, and Platform Differences
Markdown image support varies by platform. GitHub Flavored Markdown on GitHub usually supports relative paths in repositories and README.md files, while GitLab and Bitbucket may differ in how they handle raw HTML, image previews, and external URLs. A Markdown renderer in a static site generator can also rewrite paths during the build.
Common image formats that usually work are PNG, JPG, JPEG, GIF, SVG, and WebP, but support can differ by platform and file extension handling. SVG is useful for diagrams and logos, while PNG and JPG are common for screenshots and photos. If an image is not showing, check the path, filename case, file extension, and whether the platform blocks external URLs.
For docs workflows, see Markdown cheat sheet, Markdown for docs, and Markdown for documentation.
Why Is My Markdown Image Not Showing?
If a Markdown image is not showing, the most common causes are a broken relative path, a typo in the filename, a mismatch in file extension, or a platform that does not allow the image source you used. Case sensitivity matters on many servers even when it does not matter on your local machine.
Other causes include hotlinking restrictions, a blocked absolute URL, or a Markdown renderer that strips raw HTML. If the image works in one place but not another, compare the platform rules for GitHub, GitLab, Bitbucket, or your static site generator. Preview the page in the final environment before publishing.
Should Markdown Images Use Local Files or Hosted URLs?
Use local files when the image belongs to the project and should travel with the repo. That is usually the best choice for documentation, developer docs, and README.md files. Use hosted URLs when the image is managed in a CMS, shared across multiple sites, or stored on a CDN.
Local files are easier to version with the codebase, while hosted URLs can simplify reuse and reduce repository size. The tradeoff is control: hosted images can break if the remote file changes, moves, or is removed. For image optimization, compress files before publishing and choose the smallest format that preserves quality.
What Image Formats Work in Markdown?
Markdown itself does not limit image formats; the renderer and platform do. In practice, PNG, JPG, JPEG, GIF, SVG, and WebP are the most common formats supported in documentation and developer docs. PNG is often best for screenshots, JPG and JPEG for photos, GIF for simple animation, SVG for icons and diagrams, and WebP for smaller modern image files where support is available.
Always check the target platform’s documentation if you rely on a less common format. Some Markdown renderers support the syntax but not every file type equally well.
When Should You Use HTML Instead of Markdown for Images?
Use the HTML img tag when Markdown is too limited for the layout you need. That includes resizing, centering, custom spacing, and some caption or figure patterns. HTML is also useful when a static site generator or documentation system needs explicit attributes that Markdown cannot express.
For example, if you need a centered image with a fixed width, HTML is more reliable than plain Markdown. If you need a visible caption, use figure and figcaption rather than assuming the title attribute will do the job.
Best Practices and Conclusion
The safest default in any Markdown image workflow is also the simplest: use Markdown first. Keep filenames descriptive, compress images before you commit them, and organize paths so they stay readable in a repo and easy to update later. Clear names like api-flowchart.png beat image1.png, especially in documentation and developer docs.
Accessibility should shape every image choice. Write alt text that explains the image’s purpose, not just what it looks like, and be especially careful with screenshots in developer docs where readers rely on the text to understand steps. If the image adds no information, leave the alt text empty so assistive technology can skip it cleanly.
Switch to the HTML img tag only when Markdown is too limited. Use HTML when you need width, height, centering, or layout control that plain Markdown cannot provide. That keeps your content maintainable while still giving you precision where it matters.
Before publishing, test how the image renders in the target platform. GitHub, a static site generator, and a CMS editor can each handle paths, sizing, and wrapping differently. Preview the page, click the image, and confirm it loads from the intended location.
Rule of thumb: use relative paths for project docs, hosted URLs when you need them, and always verify rendering before you publish. That approach keeps your Markdown portable, your images accessible, and your content reliable.