> For the complete documentation index, see [llms.txt](https://docs.morpht.com/convivial-for-govcms/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.morpht.com/convivial-for-govcms/content-editing/media.md).

# Media

Images, documents, videos and audio are stored as media and reused across the site. Upload once, use anywhere; replace the file and every page using it updates.

See responsive media and a gallery on the demo site:

* <https://govcms.convivial.io/demo/responsive-media>
* <https://govcms.convivial.io/demo/components/gallery>

## Media types

| Type                  | Use it for                                                                         |
| --------------------- | ---------------------------------------------------------------------------------- |
| **Image**             | Photos and graphics. Uploaded at full size; the site generates the sizes it needs. |
| **Document**          | PDFs, Word and Excel files for download.                                           |
| **File**              | Any other file, including CSV data for charts and datatables.                      |
| **Video**             | An uploaded video file. Prefer **Remote video** where possible.                    |
| **Remote video**      | A YouTube or Vimeo URL.                                                            |
| **Audio**             | An uploaded audio file.                                                            |
| **Model**             | A 3D model.                                                                        |
| **Font** and **Icon** | Used by Themers; see [Theme settings](/convivial-for-govcms/theme-settings.md).    |

## List media

*Manage → Content → Media* (`/admin/content/media`) lists all media in a table. Filter by name, type or published status. Media is shared, so check here before uploading something that may already exist.

![The media list](https://3733701002-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3fBWwpuJPUqPpT2ulMXp%2Fuploads%2Fgit-blob-725c3cec923200e638aa22b0529ef846df78302d%2Fmedia-overview.png?alt=media)

## Add media

*Manage → Content → Media → Add media* (`/media/add`) lists the types; pick one to open its form.

![Choosing a media type](https://3733701002-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3fBWwpuJPUqPpT2ulMXp%2Fuploads%2Fgit-blob-2d7dbfc4e6aec419baae19fcb4322ea178ad131f%2Fmedia-add.png?alt=media)

For an image:

![Adding an image](https://3733701002-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3fBWwpuJPUqPpT2ulMXp%2Fuploads%2Fgit-blob-1976da921e593ec3bacfd60381c88b7ecce38623%2Fmedia-add-image.png?alt=media)

* **Name** — how the image is listed in the media library. Make it searchable: *Minister opening the bridge, March 2026*, not *IMG\_4021*.
* **Image** — upload the file, then fill in **Alternative text**. Describe what the image shows for someone who cannot see it. Drag the focal point marker onto the key subject so automatic crops keep it.
* **Tags** — optional keywords to help find the image later.

## Upload in bulk

On the media list choose **Upload media in bulk** (`/media/bulk-upload/upload_media`). Drop several images, videos, audio or other files at once and a media item is created for each, with the type chosen from the file extension. Documents are not included — add those one at a time.

![Bulk upload](https://3733701002-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3fBWwpuJPUqPpT2ulMXp%2Fuploads%2Fgit-blob-9e821f90f0edcf618f130d04fc604f90d2f9c08b%2Fmedia-bulk-upload.png?alt=media)

Bulk-uploaded images have no alternative text. They appear in the **Images missing alt text** report; edit each one and add it.

## Edit media

Open a media item from the list. You can rename it, change the alternative text, retag it, or use **Replace file** to swap the file while keeping everything else — the new file appears everywhere the media is used.

![Editing media](https://3733701002-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3fBWwpuJPUqPpT2ulMXp%2Fuploads%2Fgit-blob-c5b57a090ebfb93fcbe6ec26771ff88f44749245%2Fmedia-edit.png?alt=media)

## Delete media

Expand the operations button in the media list and choose **Delete**, or use **Delete** on the item's edit form. Authors can delete only media they uploaded; Approvers can delete any. Deleting a media item breaks every page that uses it, and there is no usage list editors can see — unpublish it first and watch for pages that lose an image, or ask a Site administrator to check the files list. On the confirmation, choose whether to delete the file from the file system as well as the media item.

![Deleting media](https://3733701002-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3fBWwpuJPUqPpT2ulMXp%2Fuploads%2Fgit-blob-e43211fba42d83954fa6e222d13c497af23eaff7%2Fmedia-delete.png?alt=media)

## Choosing existing media

Every **Add media** button on a form opens the media library. Search by name, filter by type, tick one or more items and choose **Insert selected**. The **Add file** field in the same dialog uploads a new item without leaving the page.

![The media library](https://3733701002-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3fBWwpuJPUqPpT2ulMXp%2Fuploads%2Fgit-blob-29e1f1fc67c0203ca951c41250089e00d3242184%2Fmedia-library.png?alt=media)