Basic image syntax
The alt text describes the image for screen readers and shows when the image fails to load, so never leave it empty.
Clickable images
Wrap the image syntax inside a link to make the image clickable.
[](https://github.com/usmankhan045/mdtool/actions)Resizing images
Markdown itself cannot set width or height. When your renderer allows inline HTML (GitHub does), use an img tag instead.
<img src="screenshot.png" alt="Editor screenshot" width="480" />Image size by platform
Some editors add their own size syntax on top of Markdown. Obsidian takes a width after a pipe in the alt text or the embed, optionally with a height; GitLab accepts an attribute block after the image. These only work on their own platform. For anything shared, the HTML img tag with a width attribute is the portable choice. Set only the width so the height scales proportionally.
<!-- Obsidian -->
![[screenshot.png|300]]
![[screenshot.png|640x480]]
<!-- GitLab -->
{width=300}
<!-- GitHub and everywhere HTML is allowed -->
<img src="screenshot.png" alt="Screenshot" width="300">GitHub strips the style attribute, so style="width: 300px" has no effect in a README. Use the width attribute instead.
Images inside tables
Inline images work in GFM table cells exactly like text. To keep a grid of screenshots or logos even, switch to img tags with a fixed width, since a table cell cannot hold Markdown size syntax.
| Light theme | Dark theme |
|-------------|------------|
|  |  |
| <img src="light.png" alt="Light" width="200"> | <img src="dark.png" alt="Dark" width="200"> |Linked images with a fixed size
The [](url) pattern above makes an image clickable but cannot resize it. When you need both, wrap an img tag in an anchor tag.
<a href="https://www.mdtool.dev">
<img src="logo.png" alt="MDTool logo" width="120">
</a>Local PNG files vs image URLs
A relative path such as images/diagram.png is resolved from the location of the Markdown file, which is what GitHub recommends for images stored in a repository; a path starting with / resolves from the repository root on GitHub. A full https:// URL works from anywhere. Paths on your own disk (C:\Users\… or /home/…) only work in local previews, and browser-based converters can only load images they can reach by URL. Encode spaces in file names, or wrap the path in angle brackets.
Frequently Asked Questions
How do I resize an image in Markdown?
Standard Markdown has no size syntax. Use an inline HTML img tag with a width attribute. GitHub, GitLab, and most static site generators render it.
How do I resize an image in Obsidian?
Add a pipe and a width: ![[image.png|300]] for embedded files, or  for external images. Use 300x200 to set width and height together.
Why is my local image not showing?
Usually the path is wrong relative to the Markdown file, the file name contains spaces that are not encoded, or the image was never committed to the repository. Absolute paths on your own computer never work once the file is published or uploaded to an online converter.
Can I put an image in a Markdown table?
Yes.  works inside a table cell on GitHub and other GFM renderers. Use <img width="…"> in the cell if you need to control the size.
Try it live
Paste this syntax into the free markdown to pdf converter and see the rendered output instantly. No signup, and everything runs in your browser.
Open Markdown to PDF Converter →