Astro / Content

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.

Beginner 8 min Updated 7 October 2026

# 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)

I am following a guide from the Viralistic Help Center (Astro). Use it as your source, walk me through it one step at a time, and wait for my confirmation before moving to the next step. If what I see does not match the guide (for example a renamed menu or a newer version), say so and suggest the closest current alternative. Ask me which device, plan or version I use when that changes the steps.

<guide source="https://viralistic.nl/help/astro/images-and-media">
# 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)
</guide>

Start by asking me what I want to achieve and where I am now.

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

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.
Place it in a folder inside src/assets/, for example src/assets/cases/your-client/.
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:

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

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/:

![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

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

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

Next steps

Still stuck?

Send us what you tried and a screenshot, and we will help you further. For new projects, book a strategic call.

Email support WhatsApp Strategic call