Where media lives

Images and documents live in a shared library, not attached to a single page. Upload once, use in as many places as you need. Replacing the file later updates every place it appears — which is the main reason to upload properly rather than pasting images into rich text.

Before you upload

Three things are much easier to get right up front than to fix later:

  • Size the image for the web. A photo straight off a phone or camera can be several megabytes. Resize it to roughly the largest size it will ever display at. Oversized images are the single most common cause of slow pages.
  • Give it a real filename. team-photo-2026.jpg is findable in six months; IMG_4471.jpg is not.
  • Pick the right format. Photographs as JPEG, graphics and screenshots with flat colour or text as PNG, logos and icons as SVG where supported.

Alt text

Set alt text when you upload. It is what screen readers announce, and what displays if the image fails to load.

Describe what the image conveys, not what it literally contains: "Support team on a video call" beats "photo of four people". If an image is purely decorative, leave the alt text empty rather than writing "decorative image" — empty alt text tells a screen reader to skip it, which is exactly right.

Documents

PDFs and other documents work the same way. Two courtesies for anyone linking to them: keep the filename meaningful, and mention the format and size in the link text, so "Annual report (PDF, 2 MB)" rather than a bare "download".

Replacing a file

Replacing the file behind an existing record updates it everywhere at once. That is powerful and occasionally surprising — if a file is used on pages you do not own, check before swapping it. When the new version is meaningfully different, uploading it as a new file is often safer than replacing.