---
title: Fix images that do not show on the built site
description: Use markdown image syntax with a page-relative path. Root-relative paths and a local img src produce broken images.
---

## Symptom

A page renders, but an image on it is broken — an empty box or the alt text in its place.
The browser's network panel shows a 404 for the image URL. `reed build` succeeded.

Or the build fails instead, with `DS-A01` naming an image on the page.

## Cause

How an image reaches the output depends entirely on how you reference it. These results
come from a probe build of a page with an image at `content/guides/images/x.png`:

| You wrote | What the build produced | Result |
|---|---|---|
| `![Diagram](./images/x.png)` | the image processed into `_astro/` under a hashed name, possibly converted (a PNG came out as `.webp`) | **works** |
| `![Diagram](/docs/guides/images/x.png)` | no image file in the output at all | broken |
| `<img src="./images/x.png" alt="Diagram" />` | the tag emitted unchanged, `src` not resolved | broken |
| `<img src="https://cdn.example.com/x.png" alt="Diagram" />` | the tag emitted unchanged | works |

The reasons:

- **Reed does not serve your content directory at the site root.** Content files are
  copied into the project Reed generates, not into the output. A root-relative path, even
  one with the correct base prefix, points at a file that is never written.
- **Only markdown image syntax is processed.** A page-relative path in `![...](...)` is
  resolved against the page file, optimised, and rewritten to the hashed `_astro/` URL.
- **A raw `<img>` tag is passed through as HTML.** Its `src` reaches the browser as you
  wrote it, and the browser resolves `./images/x.png` against the page URL, where nothing
  exists. `<img>` only works with an absolute `https://` URL.

An image with no alt text, or an empty `alt`, is a different failure: it is `DS-A01`, an
accessibility error, and it fails the build on purpose.

## Fix

### Local images: markdown syntax, page-relative path

Keep the file inside the content directory, near the page, and reference it relative to
the page file:

```mdx
![The Settings page with the API keys section expanded](./images/api-keys-settings.png)
```

For a page at `content/guides/media.mdx`, that file lives at
`content/guides/images/api-keys-settings.png`. From a page one directory deeper, go up
with `../images/...`.

Replace any root-relative image path such as `/docs/guides/images/x.png` with the
page-relative form. The base prefix rule that applies to links does **not** apply here —
images must not be root-relative at all.

### Raw `<img>`: convert it, or use an absolute URL

Rewrite a local `<img>` as markdown:

```mdx
![Architecture overview](./images/architecture.png)
```

Keep `<img>` only for images hosted elsewhere, with an absolute URL:

```mdx
<img src="https://cdn.example.com/architecture.png" alt="Architecture overview" width="600" />
```

### Do not link to the processed file by its name

The output name is hashed and the format may change, so a link to `x.png` in the output
will not resolve. If readers need to download the original, host it at an absolute URL
and link to that.

### Give every image real alt text

Describe what the image shows, in a phrase:

```mdx
![Build log showing the orphan page error](./images/build-error.png)
```

`alt=""` does not satisfy `DS-A01`. If an image carries no information, remove it.

## Verify

Build, then confirm the image was processed and the page points at it:

```sh
reed build --out dist
ls dist/_astro | grep -E '\.(webp|png|jpe?g|avif|gif|svg)$'
grep -o 'src="[^"]*_astro/[^"]*"' dist/guides/media/index.html
```

Expect the page's `src` to reference a hashed file under `_astro/`, and that file to exist.
An `<img>` whose `src` still reads `./images/...` in the built HTML is the raw-tag case.

Then open the page from a real build or deploy and check the network panel for 404s.

## Related

- [How to use images, screenshots and videos](/docs/guides/media)
- [Build output](/docs/ship/output) — what `_astro/` contains
- [Diagnostics](/docs/reference/diagnostics) — `DS-A01` and the other accessibility errors