Images are a critical part of our docs. They show users what they'll get out of following a procedure. They can help orient users through a tricky UI path, illustrate complex concepts like config file overrides, or sometimes just add visual interest.
This doc describes best practices for creating and maintaining images. If you need help embedding them on our site, see Embed images. If you want to add image annotations, see Best practices for using image annotations.
Guidelines for image types
We have four major categories of images on our site.
Guidelines for explaining images
Supporting text can provide helpful context and explanation, especially for complicated screenshots and other images that may be tricky to understand on their own. While you should always include alt text for accessibility, the other types of supporting text are optional.
- Alt text (required)
- Title (required)
- Caption
- Surrounding text
Important
Avoid the use of text inside a screenshot, use captions instead. See Best practices for using image annotations
Alt text (Required)
Always include alt text in your image tags so visually impaired readers can use their screen readers to get useful information out of the images. This only applies to images that contain content or commands (for example, buttons).
Tip
Alt text doesn't apply to inline Feather icons.
When using alt text:
- Use concise image descriptions.
- Don't repeat surrounding text—screen readers already read that.
- Aim for clarity. Complete sentences aren't required.
- Identify the type of image in some way:
alt="Diagram showing the flow of data from client to server."alt="Screenshot showing how to select a server."alt="Photo of garden hose that serves as a metaphor for electrical amperage."
Caption
Captions appear below images and give supporting context to readers.
Keep the following in mind:
- Keep captions short and don't insert procedures.
- Only insert navigation paths in captions if navigation is a key part of the message.
- Insert complementary information not identical to surrounding text.
- Make captions that are easy to skim.
- Encourage readers to look at surrounding text.
- Don't put required information in captions that isn't available elsewhere.
- Captions aren't necessary in procedure screenshots because the procedure text should make things clear.
Surrounding text
If you're not using captions or annotations, be sure to add text before or after the image to give helpful context.
If you're relying on surrounding text to explain your image:
- Use intuitive images.
- Keep the surrounding text concise so it's easier to make sense of the image.
Delete or rename an image file
Our i18n translated .mdx files need to match the corresponding English .mdx files. When you delete or rename image files in English, you might cause a build error because there's now a mismatch between the English and translated files. Here are some tips when deleting or renaming an image file:
- To replace an image: If you're replacing an existing image, you should give the image file the same name. Delete the file you want to replace and add the new file. Doing this means you won't need to change any references to that image file.
- To remove an image: If you want to simply remove an image without replacing it, don't delete the image file. Instead, just remove the import statement for that image file. The docs team occasionally runs a script that removes image files that aren't referenced by mdx files. This means we don't have to delete image files and so therefore have no need to touch the mdx files in the i18n directory, as they will be automatically updated with our translation workflow.
- To rename an image file: First, question if that's necessary to do. The image file name is generally unimportant and trivial. If you do decide to rename an image file, you must go into any mdx file that references the image file (including the i18n directory files) and update that file name.