Markdown Images: Insert, Resize, Center and Caption
By the MDConverter team · Updated · 3 min read
Quick answer
Insert an image with an exclamation mark, alt text in square brackets and the image path or URL in parentheses: . Markdown has no syntax for size or alignment, so use an HTML <img> tag with width (and <p align="center"> on GitHub) when you need them. Always write meaningful alt text — it is what screen readers, search engines and AI tools see.
Image syntax
It is a link with a ! in front. The text in brackets becomes the image's alt text, and an optional title in quotes becomes the hover tooltip.
images/logo.png.Image paths: relative, absolute and hosted
- Relative path (best inside a repository or docs site):
— keeps working on forks, branches and offline copies. - Absolute URL:
— needed in places with no files of their own, such as issues, forums and emails. - GitHub issues and comments: drag and drop or paste an image into the editor and GitHub uploads it and writes the Markdown for you.
- Spaces in file names: wrap the path in angle brackets
or use%20.
How to resize an image
Standard Markdown cannot set a size. Use HTML — set only width to keep the proportions:
<img src="/logo.png" alt="MDConverter logo" width="80">![[image.png|200]] and ; Kramdown and MkDocs accept {: width="200"}.How to center an image
Again, HTML. On GitHub, CSS is stripped, so use the align attribute on a wrapper:
<p align="center">
<img src="/logo.png" alt="MDConverter logo" width="80">
</p>
align is obsolete HTML, but it is the method GitHub READMEs rely on because GitHub removes style attributes. On your own site, use CSS instead.Adding a caption
Markdown has no caption element. Common approaches:
- Italic text on the next line — works everywhere:
then*Figure 1: Revenue by quarter*. - HTML figure:
<figure><img src="chart.png" alt="…"><figcaption>Figure 1</figcaption></figure>where HTML is allowed. - Pandoc turns an image that is alone in its paragraph into a figure with its alt text as the caption — handy for PDFs and Word documents built with Pandoc.
Clickable images and badges
Wrap the image syntax in a link. README badges are exactly this: an image from a badge service wrapped in a link to the CI run or package page.
[](https://mdconverter.net)
Different images for light and dark mode (GitHub)
GitHub supports the HTML <picture> element, so you can serve a different image depending on the reader's theme:
<picture>
<source media="(prefers-color-scheme: dark)" srcset="logo-dark.png">
<img alt="Project logo" src="logo-light.png">
</picture>Writing good alt text
Describe what the image shows and why it is there, in a short sentence: , not  or . Leave decorative images with empty alt text  so screen readers skip them. Alt text is also what survives when Markdown is given to an AI model or converted to plain text.
Images when converting Markdown
Converters run in your browser and do not download remote images on your behalf, so Markdown to Word writes a short “[Image: alt text]” placeholder where an image was — insert the picture in Word afterwards. Markdown to PDF and Markdown to HTML display images that your browser can load. Going the other way, Word to Markdown keeps image alt text.
Image support by app
| App | Supported | Notes |
|---|---|---|
| GitHub / GitLab | Yes | Markdown and <img>; width/height/align kept, style removed; <picture> supported on GitHub. |
| Obsidian | Yes | Markdown images plus ![[embed]] with |width sizing. |
| VS Code preview | Yes | Relative paths resolve from the file’s folder. |
| Partly | Image uploads through the editor; external Markdown images are not embedded. | |
| Discord, Slack | No | Image syntax is not rendered; post the image or URL directly. |
| Notion | Partly | Imported Markdown images become image blocks if the URL is reachable. |
Common mistakes and how to fix them
| Problem | Fix |
|---|---|
| Image shows as a broken icon | Check the path is relative to the Markdown file (not your working folder), the case of the file name, and that the URL is publicly reachable. |
| Image shows as a link instead | You forgot the ! in front of the brackets. |
width is ignored | Your app strips HTML. Resize the image file itself, or use the app’s own size syntax. |
| Image centered locally but not on GitHub | GitHub strips style. Wrap the image in <p align="center">. |
Tools for this
Frequently Asked Questions About Images
Comprehensive answers to common technical, formatting, security, and compatibility questions.
Related reading
- Markdown Links: Every Way to Add a Link — Inline and reference links, links to headings and files, email links and new-tab links.
- How to Color, Center and Align Text in Markdown — Color and centered text in Markdown: the HTML, GitHub and app-specific options that actually work.
- Markdown vs HTML: What Is the Difference? — How Markdown relates to HTML, what each can do, and when to mix them.