# Images and media

> Add images, video and downloads to your Viralistic Astro site so they look sharp, load fast and are accessible to every visitor.

Source: https://viralistic.nl/help/astro/images-and-media

Images make or break how a website feels, and they are also the most common reason a site is slow. This article is for anyone who adds images, video or files to a Viralistic Astro site. You will learn where each kind of file belongs, how to add an image to a page, which sizes to export and how to write alt text that helps people and search engines.

## Where files go

There are two places for files, and the difference matters.

- **`src/assets/`** is for images shown on pages. Astro optimises everything here during the build: it creates smaller versions for small screens, converts to modern formats and adds width and height so the page does not jump while loading.
- **`public/`** is for files that must keep an exact, fixed address, such as PDFs in `public/downloads/`. Nothing in `public/` is optimised.

> **Tip:** If you are unsure, use `src/assets/`. Only use `public/` when someone needs a stable link to the file itself.

## Add an image to a page

1. Export the image at a sensible size (see the table below) and give the file a descriptive name, such as `new-website-on-laptop.jpg`.
2. Place it in a folder inside `src/assets/`, for example `src/assets/cases/your-client/`.
3. Open the page's markdown file and point the image field to it with a path relative to that markdown file. The field name depends on the page type; a case page uses `heroImage`:

```yaml
heroImage:
  src: ../../../assets/cases/your-client/new-website-on-laptop.jpg
  alt: The new website for Your Client shown on a laptop and a phone
```

4. Check the page in the dev server or the deploy preview.

The path counts folders up from the markdown file. From `src/content/pages/cases/your-client.md` you go up three folders (`../../../`) to reach `src/`. From `src/content/pages/about.md` you go up two (`../../`).

> **Tip:** Every page also accepts an optional `image` field. That image is used when the page is shared on social media or in chat apps.

> **Note:** If the path is wrong or the file is missing, the build stops with an error. That is deliberate: a broken image never reaches the live site.

### Images inside body text

You can also place an image in the body of a page with markdown. The path works the same way as in the frontmatter, and the image is optimised too. From a post in `src/content/pages/insights/`:

```md
![Diagram of the three phases of a website project](../../../assets/insights/project-phases.png)
```

## Sizes and formats

Astro creates smaller copies automatically (Viralistic sites use widths from 640 to 2560 pixels), so you only supply one large version.

| Where the image appears   | Export width            | Format      |
| ------------------------- | ----------------------- | ----------- |
| Full-width hero or banner | 2560 px                 | JPG or WebP |
| Image in a text column    | 1600 px                 | JPG or WebP |
| Card or thumbnail         | 1280 px                 | JPG or WebP |
| Logo or icon              | Any                     | SVG         |
| Graphic with transparency | Double its display size | PNG or SVG  |

Keep source files reasonably small. A photo of several megabytes makes the repository and every build slower without making the website look better.

## Write useful alt text

Every image on a Viralistic site needs an `alt` field; the schema requires it. Alt text is read aloud by screen readers and helps search engines understand the image.

- Describe what matters in this context, in one sentence.
- Do not start with "Image of" or "Photo of".
- Mention the brand, place or product when it is relevant.
- For a purely decorative image, use `alt: ""` so screen readers skip it.

## Video

- **Longer videos** such as showreels and interviews belong on YouTube or Vimeo. Where a layout has a video field, you can usually paste a YouTube or Vimeo link, or a link to an `.mp4` file.
- **Short background loops** work best as a few seconds of muted MP4, compressed before you upload it. Astro does not optimise video, so the file size is up to you.
- Add captions to any video with speech.

## PDFs and downloads

1. Put the file in `public/downloads/`, for example `public/downloads/price-list.pdf`.
2. Link to it as `/downloads/price-list.pdf`.
3. For a download button, add `download: true` to the button in the frontmatter:

```yaml
buttons:
  - label: Download the price list
    href: /downloads/price-list.pdf
    download: true
```

## Next steps

- [Edit text and pages](https://viralistic.nl/help/astro/edit-content)
- [Score high on Lighthouse](https://viralistic.nl/help/astro/performance)
- [Make your Astro site rank well](https://viralistic.nl/help/astro/astro-seo)