Inserting images

Insert image uses a file browser with a 20 MB ceiling, and the media library is where you see every article a file is attached to.

Images help where words are slow. Insert image on the toolbar uses a file browser with a 20 MB ceiling per file, and the media library is the other half of the job: it is where you can see every article a given file is attached to.

Insert one

1. Put the cursor where the image goes.
2. Click Insert image on the toolbar and choose the file. The limit is 20 MB.
3. Add alt text describing what it shows.
4. Save.

Work from the media library instead of uploading again

1. While editing, click the Article settings icon.
2. Expand the Placement card and scroll to Attachments.
3. Click Manage attached media.
4. From a file's menu, choose Attach media to add it to the article you have open.

Any file format is accepted, to the same 20 MB per attachment.

Why that matters when the interface changes

Uploading the same screenshot into six articles gives you six separate files, and when the interface changes five of them stay wrong with no way to find them.

The library's Replace media option lets you upload a new file and, just as usefully, view all articles that the media is attached to. That list is the thing you cannot reconstruct once you have six copies.

An image borrowed from another article breaks with that article

If you point at an image that is attached to a different article, your article depends on that one staying published and visible. Archive it, leave it in draft, or restrict it to a group, and your image shows as a broken link with the file name beside it, for everybody or for signed-out readers only.

Nothing warns you, and the article you broke is not the one you edited. That is the practical argument for the media library over copying an address out of another article.

Alt text is not optional

It is what somebody using a screen reader gets instead of the image, and what appears when the image fails to load. Describe what it shows, not what it is called: "The status field with the six options" rather than "screenshot".

Screenshots date

Every screenshot is a promise that the interface still looks like that, and interfaces change. Use them where they genuinely help: a screen someone must find, a setting easily missed. Not to illustrate a sentence that was already clear.

Crop tightly

A full-screen capture with one relevant corner makes the reader hunt. Crop to what matters, and highlight the specific element if it is small.

See also

• Working with the media library
• Writing accessible articles
• Inserting videos and embedded files