Alt text in Confluence: how to add it, and how to write it well
Pasting a screenshot into Confluence takes one second and never asks you for a description. That is the whole reason this is the most common accessibility failure in documentation.
Adding it in the Cloud editor
- Click the image in the editor. The image toolbar appears above it.
- Choose the Alt text option in that toolbar.
- Type the description and confirm. Publish the page.
The alt text is stored on the image in the page body, so it travels with the page through copies, exports and page moves. It is not stored on the attachment, which means the same image used on two pages can carry two different descriptions — and it should, because the right description depends on what the image is doing on that page.
What makes a description useful
The test is not “what is in the picture”. It is: if the image vanished, what would the reader need in its place to keep going?
| Image | Weak | Useful |
|---|---|---|
| Screenshot of a settings page with one field circled | “Settings screenshot” | “The Notifications settings page, with the Daily digest toggle highlighted” |
| Architecture diagram | “Diagram” | “Requests reach the API gateway, which calls the auth service before the orders service; both write to the shared Postgres cluster” |
| Chart of ticket volume | “Chart showing ticket data” | “Support tickets fell from about 900 a month in January to about 300 in June” |
Three habits carry most of the quality:
- Say the point, not the pixels. A chart's alt text should contain the finding, not a description of the axes.
- Do not start with “image of”. A screen reader already announces that it is an image. “Screenshot of…” is fine, though — that the content is a captured interface is real information.
- Keep it to a sentence or two. Alt text is read in one uninterrupted run. If the image needs a paragraph, put the paragraph on the page — where sighted readers get it too — and keep the alt text short.
Filenames are not descriptions
Some editors fill alt text with the filename by default, which produces
Screen Shot 2026-01-04 at 10.11.12.png read aloud, character by character.
That is worse than empty, because a checker sees alt text present and a listener gets
noise. Anything that looks like a filename, a hash, or the word “image” with a number
after it should be treated as missing.
When empty alt text is correct
Not every image carries information. A divider line, a repeated brand mark in a page
template, a decorative flourish beside a heading that already says the same thing — these
should be skipped by a screen reader rather than described. In HTML that is
alt="". The judgement to make is simple: if this image were removed,
would the reader lose anything? If not, it is decorative.
The practical problem is that a checker cannot tell a decorative image from one whose description was forgotten. That is why marking images as decorative needs to be a deliberate act you record, not a silent omission.
Doing it across thousands of pages
One page at a time, this is easy. The reason alt text stays broken is that nobody knows which pages are missing it, and the images were pasted by forty different people over six years. The only approach that finishes is: measure the whole space, work the list by owner, and put a check in front of the author while they are still writing.