Use Alt-text for Accessibility & SEO

Created by Margie Wylie-Petruzziello, Modified on Thu, 19 May 2022 at 02:20 PM by Margie Wylie-Petruzziello

Why Alt-Text?

A little alt-text (alternative text) can go a long way in making websites more accessible and more searchable. Alt-text is read aloud for visually impaired website visitors, displayed if an image is broken or loads slowly, and used by search engines, including Google and Search.gov (our internal search provider), to index both the image and the page it appears on. So, alt-text plays an important role in search engine optimization, as well.

Tips for creating alt-text

Name your image descriptively before you upload it. By default, SilverStripe fills the alt-text field with the filename. So, if you name a photo of a person that person’s name, e.g. John-Smith.jpg, your alt-text will automatically be filled in as John Smith. Of course, this requires some planning, but it confers a second benefit: Your image is more searchable!
Rename Screenshots! "Screen Shot 2022-05-18 at 2.48.15 PM.png" is not only inaccessible, it causes search engines to ignore the image completely. Please, please, please, rename screenshots before uploading them to the CMS!
Describe what you see. (examples: "John Doe standing in front of Shyh Wang Hall" or “Saul Perlmutter posed in front of a background of stars.”)
Keep it short. A dozen words or less is a good rule of thumb.
For decorative images, leave an empty alt tag. (alt=“ ”) Don’t delete the tag itself, but leave it empty. This signals to screen readers and search engines that the alt-text wasn’t forgotten, but purposefully omitted.

Where to enter alt-text in the CMS

The easiest way is to type it in when you embed the image on a page.

When you select “Edit,” from the Insert Media window (to adjust the display size and position and maybe add a caption) just fill in the first field labeled, “Alternative text (alt)”.

How to edit the HTML of existing embeds

If you miss this step, you can still edit the HTML. Just select the HTML button and search (cmd-s) for alt= (or just scan for it). Edit or add text between the “ ”.

NOTE: For decorative images, delete only the text, leaving the empty tag alt=“ ” to indicate the omission was purposeful to screen readers and search engines.

Select the “Update” button, which inserts the change into the content. You must still “Save” or “Save & Publish” the page to retain your changes.

“Main Image” Alt-Text

Article-type pages (Documentation and Documentation Wide, too) each have a “Main Image” element. By default, that alt text is filled in with a filename, which is rarely adequate alt-text.

To add or edit alt-text, upload an image in the “Main Image” tab; select the “Edit” button (see screenshot below) and fill out the “Alt Text” field.

(Depending on the version of SilverStripe you are using, this field may be labeled at "Alt Text" or "Title (alt text)".