Markdown Syntax · Images

Markdown Images
How to insert one, and why it's not showing

Adding an image in Markdown is one line: ![alt text](path) — an exclamation mark, the alt text in brackets, the path in parentheses. Simple, until the image doesn't show up.

When a Markdown image is blank or broken, it's almost always the path: a local path is resolved relative to the .md file, and many tools can't reach local files at all. This article covers the syntax, web vs local images, why they fail, and how to fix them.

New to the syntax in general? Start with How to Write Markdown.

The syntax

An image is a link with a leading !:

Web image (URL):
![A cat sleeping](https://example.com/cat.png)

Local image (relative to this .md):
![Project diagram](images/diagram.png)

Alt text shows if the image can't load:
![Quarterly revenue chart](charts/q3.png)
  • ! — marks it as an image, not a text link.
  • Alt text (in [ ]) — describes the image; shown if it can't load, and read by screen readers and search engines. Always write it.
  • Path (in ( )) — either a web URL (https://…) or a path to a local file.

Web image vs local image

The path is where most confusion starts:

  • Web URL: ![](https://example.com/pic.png) — loads anywhere with internet; nothing to keep track of locally.
  • Local path: ![](images/pic.png) — points to a file on your disk, resolved relative to the .md file's own location. It keeps the image together with your notes, but whatever opens the .md has to be able to read that local file.

That last point is the crux of "my image won't show."

Why your Markdown image isn't showing

Reason What's happening Fix
Wrong relative path The path is relative to the .md file, but you wrote it relative to the project root Fix the path so it points from the .md to the image
Viewer can't read local files A web-based tool can only load web URLs, not files on your disk Open the .md in an editor that can read your local folder
Typo / wrong case Filename or extension differs (Pic.PNG vs pic.png) Match the real filename exactly, including case
Missing alt text Not an error, but bad for accessibility and SEO Always write meaningful alt text in the brackets

The single most common one: the relative path is written from the wrong starting point. Remember it's relative to the .md file — if the note is in notes/report.md and the image is in notes/images/pic.png, the path is images/pic.png, not notes/images/pic.png.

Keep the image with your notes

A tidy, portable setup: put images in an images/ subfolder next to the .md, and reference them relatively. Move the note and its folder together and the paths keep working. For organizing a folder of notes and assets, see How to organize .md files.

Editing the image markdown with NoteLoom

NoteLoom is an editor that reads and writes local .md files right in the browser. You mount a local folder, so your notes and your image files sit in the same place, which is exactly the setup relative image paths are made for. Because the folder is mounted, NoteLoom can actually display those local images: its reading and live views resolve a relative path like images/pic.png and render the picture inline, where a viewer that cannot reach your local files would leave a blank. You write and fix the ![alt](path) references in the live or source view, and save straight back to the local file.

To be clear about the boundaries: NoteLoom has no AI — it won't generate images, fetch them, or write the alt text for you. It opens, edits, and saves the local Markdown; the image references are yours to write.

How you use it: open app.noteloom.cc in Chrome / Edge / Arc → mount the folder that holds the note and its images → open the .md → write or fix the image path in source → save back 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 shrink an oversized image? The other case: the image renders but is too big, and how to set its width. How to Write Markdown? Headings, lists, links, code — the basic syntax every beginner needs. Why aren't my Markdown line breaks working? The other classic "why doesn't it render" Markdown gotcha. How do you write Markdown tables? Table syntax, alignment, and breaks inside cells. How do you organize .md files? Keep notes and their images tidy so relative paths keep working. Online Markdown Editor Read and write local md files right in your browser.

FAQ

How do I insert an image in Markdown?
Use an exclamation mark, square brackets for the alt text, and parentheses for the path: ![alt text](path). The alt text describes the image (shown if it can't load); the path is either a web URL or a path to a local image file.
Why isn't my Markdown image showing?
Usually one of three things: the path is wrong (a local path is relative to the .md file's own location, not your project root), the viewer can't reach the file (many web-based Markdown tools can only load images from a web URL, not from your disk), or there's a typo or wrong capitalization in the filename. Check the path first.
What's the difference between a web image and a local image?
A web image uses a full URL, like ![](https://example.com/pic.png) — it works anywhere with internet. A local image uses a path to a file on your disk, like ![](images/pic.png), resolved relative to the .md file. Local paths keep the image with your notes, but the tool opening the .md has to be able to read that local file.
Can I set the image size in Markdown?
Not in standard Markdown — the plain ![alt](path) syntax has no width or height. Some renderers accept an HTML <img> tag instead (e.g. <img src="pic.png" width="300">), and a few flavors add their own size extension, but none of that is universal. If portability matters, keep to plain Markdown and size the image file itself.
Where should the image file go?
Keep it near the .md and reference it relatively — a common pattern is an images/ subfolder next to the note, referenced as ![](images/pic.png). Move the .md and the folder together and the paths keep working; that's the point of relative paths.
Can NoteLoom help with images?
Yes. Because NoteLoom mounts your local folder, it can actually display your local images: the reading and live views resolve a relative path like images/pic.png and show the picture, where many online tools just show a broken image because they cannot reach your local files. It has no AI and won't generate or fetch images for you; you write and adjust the ![alt](path) references yourself, in the live or source view.
Can I do this with NoteLoom on my phone or in Safari?
Not for now. NoteLoom relies on the browser's File System Access API, which currently works in Chromium-based desktop browsers like Chrome, Edge, and Arc; Firefox, Safari, and mobile aren't supported yet.

Edit your notes and images in one local folder

Open NoteLoom in Chrome / Edge / Arc, mount the folder with your note and its images, and write or fix the ![alt](path) references in the source view — saved straight back to your disk. No software to install and no account to sign up for.

Open NoteLoom and try it