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.

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

Sorry for the delayed reply. I have always regarded Discourse development as both thoughtful and thorough, and my perception from other threads as also led me to believe that accessibility is a priority.

Which is why I am frankly struggling to understand the reluctance here. I would describe the current situation for users as “nearly impossible to add, even if they want to / remember to” and the situation for admins as “completely impossible to remind / encourage”. Making alt-tags simpler and easier seems like incredibly low-hanging fruit that would benefit accessibility on every Discourse instance. It should be built-in, everywhere. $0.02

You could certainly build a blocking interstitial which prevents posting… I think you could do this with watched words – since we know the default image description is equal to the filename?


1 Like