Markdown cheatsheet · Image size
Markdown image size
Markdown has no syntax for resizing an image. Every method that works is either an HTML tag or a flavor-specific extension, which is why the answer you copied works in one place and does nothing in another.
The one that travels furthest
An img tag with a width attribute. Set only the width and the height follows on its own, keeping the aspect ratio.
<img src="logo.svg" alt="The maxdown logo" width="120">
This works anywhere inline HTML is allowed, which covers GitHub, GitLab, most static site generators, Jupyter and Obsidian. It does nothing where HTML is stripped, such as a strict CommonMark renderer with HTML disabled.
Which syntax works where
This is the whole problem in one table. Pick the row that matches where the file will be read, not the one you saw first on a forum.
| Where you're publishing | What actually resizes |
|---|---|
| GitHub (README, issues, wiki) | <img src="x.png" width="300"> |
| GitLab | {width=300} or an img tag |
| Obsidian |  or ![[x.png|300]] |
| Pandoc | {width=50%} |
| Jekyll / kramdown | {: width="300"} |
| Azure DevOps wiki |  |
| Jupyter notebook | <img src="x.png" width="300"> |
| Strict CommonMark | Nothing. No size syntax exists. |
 is the single most copied answer to this question, and it is Obsidian-specific. Paste it into a GitHub README and you get an image at full size with a literal alt|300 as its alt text. The pipe form and the {width=300} form are extensions, not markdown.Sizing by percentage
A pixel width breaks on narrow screens. A percentage scales with the container, which is usually what you want for a screenshot in a README.
<img src="wide.png" alt="A chart" width="50%">
(the image renders at half the width of its container)
In Pandoc the equivalent is {width=50%}. Note that GitHub accepts a percentage in the width attribute, but it resolves against the content column, not the window.
Both dimensions, and why you usually shouldn't
You can set width and height together, but unless the numbers match the image's real aspect ratio, the picture is squashed. Setting one and letting the other follow is almost always the right call.
<img src="logo.svg" alt="Squashed" width="120" height="40">
The exception is when you know the ratio and want to reserve the space before the image loads, which stops the page from jumping. That's a web performance concern, not a markdown one.
Centering a resized image
Size and alignment are separate problems, and markdown has no syntax for either. Where HTML is allowed, wrap the tag:
<p align="center"> <img src="logo.svg" alt="Centered" width="80"> </p>
GitHub strips most CSS but honours the deprecated align attribute, which is why every polished README uses it. <div align="center"> works the same way. Alignment on its own, without resizing, is its own topic: centering and aligning.
Why your image didn't resize
You used the pipe form outside Obsidian
See the trap above. ![alt|300] only means something to Obsidian and a few wikis.
The renderer strips HTML
Comment fields, some chat apps and strict CommonMark configurations remove img tags entirely. If the image vanishes rather than staying full size, HTML is being stripped and there is no sizing method available at all. Resize the file itself before uploading.
You put the tag inside a code fence
Inside backticks, HTML is displayed rather than rendered. That's the point of code fences.
Markdown inside the HTML stopped working
Once you open an HTML block, most renderers stop parsing markdown inside it until the block closes. That's expected, not a bug.
Common questions
Can I resize an image in a table cell?
Yes, the same img tag works inside a cell, since inline HTML is allowed there. Block elements are not.
Does resizing shrink the file?
No. width only changes the display size; the reader still downloads the full file. For a 4 MB screenshot shown at 300px, resize the actual image before committing it.
Is there a way that works everywhere?
Only one: resize the image file itself. Every in-document method is renderer-specific. If a document has to look right in three places, that's the reliable answer.
width is obvious immediately instead of after a commit.