# Images and files

Images and files are **assets**: they belong to your team, not to one page, so the same screenshot can appear in several libraries. **Assets** in the top bar lists them all.

## Placing an image

Choose **Image** in the `/` menu, or upload from the image panel in the editor. The Markdown that goes into your page looks like this:

```markdown
![The parking card settings](asset:15f6c8ef-0001-4b71-b79b-7153acb5bb73)
```

The `asset:` reference names the asset, never its address. If an asset's file changes, every page that shows it follows.

## Sizes

An image on its own line is shown full width. Add a size after it for something smaller:

```markdown
![Dashboard](asset:…){size=half}
An icon ![gear](asset:…){size=inline} inside a sentence.
```

Readers get an image sized for their screen: we make smaller versions of every image when it is uploaded.

## Alt text

The text between `[ ]` is the image's alt text: what screen readers say, and what shows when the image can't load. Describe what the image tells the reader. An image that is pure decoration gets `{decorative}`, so screen readers skip it:

```markdown
![](asset:…){decorative}
```

The editor's Accessibility panel lists images without alt text.

## Light and dark versions

An image can have a light and a dark version, for example a screenshot of an interface in both themes. Readers see the version that matches their theme. One version is used for both.

## Files

Any file that isn't an image (a PDF, a spreadsheet) is offered as a download. On its own in a [file block](https://docsahoy.docsahoy.eu/docs/writing/blocks) it becomes a card with its name, type and size; inside a sentence it is a download link.

## Limits

An image can be up to 10 MB, any other file up to 20 MB. SVG images are accepted: they are cleaned of scripts and served in a way that keeps them harmless.