Skip to content
Reed Docs

Fix images that do not show on the built site

Use markdown image syntax with a page-relative path. Root-relative paths and a local img src produce broken images.

Symptom

Section titled “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

Section titled “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

Section titled “Fix”

Local images: markdown syntax, page-relative path

Section titled “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

Section titled “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" />
Section titled “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

Section titled “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

Section titled “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.

Section titled “Related”