What’s the best way to add image descriptions?

We have a practice of always adding image descriptions in order to make Discourse accessible to people who use screen readers. What are some best ways to support adding image descriptions?

For example, is it possible for help text to show up that tells people to add an image description?

“You’ve added an image! Please add an image description before you create the topic.”

And, how do we add alt-text?

More on image descriptions


Good question… I’ve wondered about this myself. It appears that the filename is used to create a description for the image. Then after uploading, you can tweak it in the markdown. When viewing a post with an image, you can mouse over it or click on it to look at the image bigger, and it includes the description at bottom. But I don’t know how that description works in screen readers.

If this can work, then for communities where this is especially important you can develop a culture around improving these descriptions, and moderators can also keep an eye out and edit posts to improve descriptions or send PMs to educate users.

![Irish Stout after a week in the fermenter, ready for pouring into bottles|375x500](upload://rW0hzxtwAluwFC6TAY07KT7J8IK.jpeg) 


I’d like to bump this.

@codinghorror is there a place to make specific requests for technical improvements here? Requiring users to rename files or supply markup is simply a non-starter. Those techniques are completely non-discoverable, but even if they weren’t, are also a bigger hurdle than most users will climb. Adding alt text need to be obvious, simple, and (critically) part of the normal process for uploading images, so that users who rely on assistive technologies can participate. IMO the best solution would be to have a pop-up on image upload that asks for descriptive text to be supplied. And at least for our forum I would even like a configuration to make supplying non-empty text mandatory.


OK, I think you’d need a plugin for that, perhaps start in #marketplace ?

@codinghorror I meant to convey that accessibility needs to be a first-class concern that is built directly in to Discourse, not bolted on as an afterthought. (Apart from that, after a recent very bad experience with a non-official plugin and a botched upgrade, we only install official plugins).

1 Like

pop-ups rarely improve usability, so I am not sure I agree with that.

At the moment when pasting from clipboard we do this:

A theme component could be built (no need for a plugin here)

  • That adds a big red popup
  • That highlights the word image after upload
  • That introduces an interstitial page.

I suggest starting with a theme component here prior to considering any core changes.


Could you point me to a theme component that has these elements? I’d like to play around with one so that I can perhaps sketch out what an alt text / image description theme component workflow would be like.

I do think a plug-in like how events works would be best though, where you insert an image and a form opens up where you type in the alt text and the image description. Then when you hit submit the image is automatically properly formatted.