> Agent-readable docs index: /llms.txt. Download /docs.zip to grep all markdown files locally.

---
title: Images
description: Local and remote images with automatic sizing and placeholders.
icon: image
---

# Images

Holocron processes images at build time to prevent layout shifts and generate placeholders.

## Markdown images

Use standard Markdown image syntax:

```mdx
![Alt text](/images/screenshot.png)
```

Place image files in your `public/` directory and reference them with absolute paths. Public images keep their original URL.

## HTML img tags

You can also use `<img>` tags:

```mdx
<img src="/images/diagram.png" alt="Architecture diagram" />
```

Holocron's remark plugin converts `<img>` tags to its internal image component with dimensions when it can read the image metadata.

## Build-time processing

For local images outside `public/`, Holocron:

1. **Reads dimensions** from the file so the rendered `<img>` has explicit `width` and `height`, preventing layout shift.
2. **Generates placeholders** for a smooth loading experience.
3. **Copies images** to a generated Holocron image directory during build for consistent serving.

Images already in `public/` are served from their public path and are not copied again.

## Remote images

Remote image URLs (`https://...`) are supported. Remote URLs in JSX `<img>` tags can be fetched for metadata at build time. Markdown remote images still render, but they do not get build-time dimensions or placeholders.

```mdx
<img src="https://example.com/photo.jpg" alt="Remote photo" />
```

## Frames

Wrap images in a `<Frame>` component for a styled border and optional caption:

```mdx
<Frame caption="Dashboard overview">
  ![Dashboard](/images/dashboard.png)
</Frame>
```

See [Frames](/components/frames) for more options.


---

*Powered by [holocron.so](https://holocron.so)*