Markdown Syntax · Images

How Do You Set an Image's Size in Markdown?
Shrinking an oversized image

You have a Markdown image that renders fine but comes out huge, and you want to make it smaller. The honest starting point: standard Markdown has no way to size an image. The ![alt](path) syntax carries no width, so there is no pure-Markdown option.

So you use one of two routes: a bit of HTML, which works almost anywhere, or a shorthand your editor supports. Here is how each one works.

This page is about an image that is too big. If your image is blank or broken instead, that is a path problem, see how to insert an image and why it is not showing.

The portable way: an HTML img tag

Most Markdown renderers allow inline HTML, so the reliable cross-tool way to set a width is to write the image as an HTML <img> tag instead of Markdown, and give it a width:

<img src="images/pic.png" alt="A diagram" width="300">

That renders the image at 300 pixels wide in GitHub, most static-site generators, and most editors. The one caveat: a few strict or sanitized renderers strip raw HTML, in which case the tag will not apply. When you need one method that behaves the same everywhere, this is it.

In NoteLoom: a width shorthand, or just drag

If you are writing in NoteLoom, there are two quicker options that stay in the Markdown image itself.

A width shorthand in the alt. Add |300 (pixels) or |50% (a percentage of the image's natural size) to the alt text:

![A diagram|300](images/pic.png)     300 pixels wide
![A diagram|50%](images/pic.png)     50% of the image's natural size

Or drag to resize. In the editor, a standard inline image has a small handle at its lower corner. Drag it to change the width, and NoteLoom writes the new width back into the file, no number-typing required.

One honest caveat about the shorthand: the |300 form is a convenience NoteLoom supports, not part of standard Markdown. A tool that does not recognize it will just show |300 as literal text in the alt. So if the file will be read in lots of different tools, prefer the HTML <img> way above; if you are working inside NoteLoom, the shorthand and the drag handle are faster.

Which should you use?

Way How When
Portable HTML An <img> tag with a width Works in GitHub and most renderers; the safe cross-tool choice
NoteLoom shorthand Add |300 or |50% to the alt Fast, but not standard Markdown, so it may show as literal text elsewhere
NoteLoom drag Drag the image resize handle No typing; the width is written back into the file

Short version: if the file travels between tools, use the HTML <img> way. If you are editing in NoteLoom and just want the image smaller now, the |300 shorthand or the drag handle gets it done in a second.

Try it in NoteLoom

NoteLoom is an editor that reads and writes local .md files in the browser. It renders your images in the live and reading views, so you can add a |300 to the alt, or drag the corner handle, and watch the image resize on the spot, then save back to your disk.

To be clear about the boundaries: NoteLoom has no AI. It does not generate, fetch, or edit the image itself; it renders your Markdown and saves the file. The width you choose is yours to set.

How you use it: open app.noteloom.cc in Chrome / Edge / Arc, mount a local folder that holds the note and its image, and set the width in the source view or by dragging. Saved straight to your disk, no cloud, no account.

Related reading

Markdown not rendering? The common gotchas The diagnostic hub: renderer problem vs syntax slip, with the fix for each. How do you insert an image in Markdown? The other case: adding an image, and why it sometimes does not show at all. How to Write Markdown? The basic syntax, images included. How do you make a horizontal line in Markdown? Another syntax question, plus the --- heading trap. How do you open a .md file? Open your text in a renderer so the image actually shows. Online Markdown Editor Write and preview local md files in your browser.

FAQ

Can you set an image size in Markdown?
Not in standard Markdown. The ![alt](path) syntax carries no width or height option. To size an image you either drop down to inline HTML with an img tag, or use a width shorthand if the specific editor you are in supports one.
How do I shrink a Markdown image that is too big?
Give it a width. The portable way is an HTML img tag: an img with src and width="300". That works in GitHub and most renderers. In an editor that supports it, like NoteLoom, you can also add |300 to the alt text, or drag the image to resize it.
Does ![alt|300](path) work everywhere?
No. That |width shorthand is a convenience some Markdown editors support, including NoteLoom, but it is not part of standard Markdown. Tools that do not recognize it will show |300 as literal text in the alt. For something that renders the same everywhere, use the HTML img tag instead.
What does the percentage mean in NoteLoom (|50%)?
In NoteLoom, ![alt|50%](pic.png) sizes the image to 50% of the image’s own natural size, not 50% of the page width. Because it is worked out from the natural size, the image looks the same in the edit and reading views.
Can I resize an image by dragging instead of typing a number?
In NoteLoom’s editor, yes. A standard inline image has a small handle at its lower corner; drag it to change the width, and NoteLoom writes the new width back into the file. No number-typing needed.
My image is not shrinking, it is not showing at all. Is that the same thing?
No, that is a different problem. Sizing is for an image that renders but is too big. If your image is blank or broken, it is usually a path or reachability issue, covered in the guide to inserting an image and why it does not show.

Resize an image and see it, live

Open NoteLoom in Chrome / Edge / Arc, mount a local folder, and set an image's width by typing |300 in the alt or dragging its handle while the live view shows the result. Saved straight back to your disk, no software to install and no account to sign up for.

Open NoteLoom and try it