---
title: "Markdown images: relative paths, alt text, broken images"
slug: markdown-images
excerpt: "How to add a Markdown image by relative path, write alt text that helps, and fix an image that will not show in a file your agent wrote."
quickAnswer: "To add an image in Markdown, write an exclamation mark, then alt text in square brackets, then the path in parentheses, like ![Login screen](images/login.png). You can add an optional title in quotes after the path. The path can be a relative file path or a full web address. How a relative path is resolved, and whether remote images load at all, depends on the viewer. If an image does not show, check the path, the case of the file name, any spaces, and whether the viewer blocks remote images."
keyTakeaways:
  - An image is written as `!`, then bracketed alt text, then the path in parentheses.
  - CommonMark sets no base folder for a relative path, so check how your viewer handles one.
  - Wrap a path that has spaces in angle brackets, or rename the file without spaces.
  - Alt text should say what the image tells the reader, in one short sentence.
  - "Sashmark, still in development, is planned to render local images in v1 and leave remote ones unfetched."
publishedDate: 2026-10-20
dateModified: 2026-10-20
author: Bobby Huang
cluster: B
role: post
status: published
faq:
  - q: What makes a Markdown image show as text or a broken icon?
    a: Check the path first. The file may sit in a different folder, the name may differ in case, or the path may hold a space. If the image is a web address, the viewer may block remote images.
  - q: Can I set the size of a Markdown image?
    a: Plain Markdown has no size syntax. Some tools accept an HTML img tag with a width, but many viewers ignore or strip raw HTML. Resizing the image file itself avoids viewer-specific size syntax, though how big it shows still depends on the viewer.
  - q: Should I use a relative path or a full web address?
    a: For images that live with your notes, use a relative path. The file and its images then move together, and showing them may not need a network at all.
related:
  - markdown-syntax-guide
  - what-is-a-md-file
  - how-to-review-markdown-your-ai-agents-write
  - markdown-cheat-sheet
---

A test run might save a screenshot, or a report might embed a chart the agent just made. When the image works, you barely notice the syntax. When it breaks, what you get depends on the viewer, such as an icon, the alt text or the raw line.

Image trouble often starts with the path, so paths fill the middle of this page. Alt text and remote images follow. Images sit right after links in the [guide to Markdown syntax](markdown-syntax-guide.md), since the two are written almost the same way.

## The basic image syntax

An image line has three parts in a fixed order. It opens with `!`. A bracket pair comes next, holding the alt text. Last is a parenthesis pair holding the path.

```markdown
![Login screen with an error banner](screenshots/login-error.png)
```

Many viewers show the picture in place of this line when they can find the file. Once it loads, many of them hide the words in brackets. In HTML output, those words become the image's alt attribute.

You can add a title after the path, in double quotes. It is optional.

```markdown
![Login screen with an error banner](screenshots/login-error.png "Taken after the test run")
```

Many viewers show the title as a small tooltip when you hover over the image. Some show nothing. Leave it out unless it adds something the alt text does not.

## Reference-style images

A long path can make a line hard to read. Reference style moves the path out of the sentence. You give the image a label, then define that label on its own line.

```markdown
![Build pipeline diagram][pipeline]

[pipeline]: diagrams/build-pipeline.png "Current pipeline"
```

The output matches the inline form. Nothing from the definition line shows in the output. It can sit above or below the image, so you can collect all definitions at the bottom of the file. That makes paths easy to update in one place.

## Relative paths

A relative path names a file by where it sits compared to something else. CommonMark doesn't name a starting folder. Many viewers resolve relative paths from a base folder, often the Markdown file's own folder.

Say your notes look like this:

```markdown
project/
  notes/
    report.md
    images/
      chart.png
  assets/
    logo.png
```

From the folder that holds `report.md`, the chart is one folder down:

```markdown
![Weekly error count chart](images/chart.png)
```

The logo is in a sibling folder. Use `../` to go up one level, then down into `assets`:

```markdown
![Project logo](../assets/logo.png)
```

In many viewers, each `../` climbs one folder. Stick to `/` between folder names, even on a PC. Many viewers accept them on every system, and a backslash in Markdown can act as an escape character.

> An absolute path such as `/Users/janedoe/project/notes/images/chart.png` may work on one machine and fail on every other. An agent may write one because that is the path it saw. Ask for relative paths instead.

## File names with spaces

A bare space inside the parentheses breaks the image syntax. The line is no longer read as an image, so the raw line stays on the page as text. You have three ways around it.

Wrap the whole path in angle brackets:

```markdown
![Sprint board photo](<images/sprint board.png>)
```

Inside angle brackets, the path may hold spaces, and the parser keeps it as one path.

Or replace each space with `%20`, the way web addresses do:

```markdown
![Sprint board photo](images/sprint%20board.png)
```

Many viewers decode this back to a space. Not all do. The safest fix is to rename the file to `sprint-board.png` and skip the problem for good.

## Writing alt text

Write alt text for a reader who can't see the picture at all, such as someone using a screen reader. In many viewers it also fills the gap when the picture fails to load.

A few habits help:

- **Say what the image tells you.** "Chart showing errors dropping after the fix" beats "chart".
- **Keep it short.** One sentence is often enough. Put longer details in the text around the image.
- **Skip "image of".** Many screen readers announce the image role.
- **Leave formatting out.** Only the plain text of the brackets becomes the alt text, so formatting is dropped and only the words stay.

If an agent writes alt text like `![screenshot](shot1.png)`, that tells a reader almost nothing. A quick edit to name what the screenshot shows makes the file useful even when the picture is missing.

## Why remote images may not load

A remote image is one whose path is a web address, such as `https://example.com/chart.png`. Showing it means a viewer may need to contact that server. That has a few side effects, and any of them can stop a remote image from loading.

- **Privacy.** Fetching the file can tell that server someone opened the page, plus when and from what network. Some viewers won't fetch remote images unless you allow it.
- **Offline.** Without a network connection, a remote image that is not cached may not load. A file that looked fine at your desk may show blanks on a train.
- **Moved or expired links.** The server may have deleted the image, or the link may have needed a login that has since timed out.
- **Viewer policy.** Some viewers never fetch remote content. Others ask first. Each viewer sets its own rule.

If an image must show up offline, store the file beside your notes and point to it with a relative path. That works in viewers that load local images.

## How to fix a broken image in a file your agent wrote

1. **Read the raw line.** Look at the Markdown source, not the rendered page. Check that the line starts with `!` and that the brackets and parentheses are all closed.
2. **Find the image file.** If your viewer reads paths from the Markdown file's folder, start there. Follow the relative path from there and check that the image is really at that spot.
3. **Check the spelling and case.** `Chart.png` and `chart.png` are different files on many systems. Check the extension too, such as `.png` versus `.jpg`.
4. **Look for spaces.** If the file name has a space, wrap the path in angle brackets or rename the file.
5. **Replace absolute paths.** If the path starts with a drive letter or a home folder, rewrite it as a path relative to the Markdown file.
6. **Check for a web address.** If the path starts with `http`, the viewer may be blocking it or the link may be dead. Save the image locally and point to the copy.
7. **Give the agent a standing rule.** Something like "Save images in an `images` folder next to the file and link them by relative path" fits well in its project notes. For where rules like that belong, see [docs an agent can act on](write-markdown-docs-your-ai-agent-can-follow.md).

After any later agent pass over the file, check the image lines once more. A changed path is easy to miss in a long diff. The [review guide for agent-written files](how-to-review-markdown-your-ai-agents-write.md) shows how to review just the changed lines.

## Where Sashmark fits

An app called Sashmark is in the works, aimed at reviewing Markdown that agents write and rewrite. It is in development and has not been released. Local images are planned to render in v1, while remote images are planned to stay unfetched. Links and block quotes are on that v1 render list as well. The app itself has no AI features. See the [planned features](/features), the [help pages](/help) and the [roadmap](/roadmap) for where each part stands.

To see what Sashmark is and follow along, visit [sashmark.com](https://www.sashmark.com/).