How to add a description for uploaded images?

I think Discourse is already support this feature…

The filename should describe the image. If it does not, rename the image and re-upload it.


could be anything, but …



Do you mean something like this?


I tried that, but there isn’t have any effect.


That’s because the method described by @tomtjes only changes the <img alt="…"> attribute – the text used by screenreaders and other devices that cannot display the image.

What you are looking for is something to change the “Discourse Welcome.jpg” text in your example picture. That is not possible with the Markdown image syntax in the current version of Discourse. You’d have to rename the image on your computer and upload it again, as Jeff said.

But you can use HTML

When you use HTML syntax to embed the image, changing the description is possible without re-uploading, by specifying the <img title="…"> attribute. For example:

<img src="/uploads/default/original/2X/6/621….jpg" width="200" height="60" alt="Test Alt Text" title="Test Title"/>

I cover this technique here in a Discourse manual I wrote, in sub-section “Using HTML”.

The HTML syntax for images was the default in older versions of Discourse and is still possible to use, but be aware that there could be unintended side effects as it is no longer the default. For example, I don’t know if Discourse detects image usage for images referenced in <img …> HTML tags, so that the “clean up uploads” config setting does not accidentally delete such images.


So, given the accessibility requirements that are (rightly, IMO) being enforced these days, I’m finding it hard to believe that the only way to add an image description is by renaming the file before uploading, or futzing with markup or html code. No problem for me, but if you think any of my routine forum users are going to bother doing any of this stuff you’re spending far too much time with tech-oriented people. I’m an admin on a medical support forum, with some members who use “blind browsers,” and while most of our members would be happy to add an alt-description if the upload process included a field for that, there’s just no way to expect them to remember to rename the file or fiddle with the markup, let alone code in an html src tag with all the trimmings. Surely there’s some way to do this via a field in the upload path??? I’m so hoping to be told I just missed the obvious post about that.


At the moment you either have to edit the filename, or edit the markdown/html

I agree with this perspective. Even if someone knows that they can edit the markup or HTML, they’ll likely forget to. An add description link in the modal that exposes an input would be a good addition for accessibility, and also serves as a light reminder.

I think in most cases you’ll still have to call attention to the feature and specifically request that everyone fills it out. People still forget to add attachments to emails even after writing an email about the attachment, after all.

This still wouldn’t cover the cases where someone copies and pastes an image or drags one into the composer. Maybe adding a link to the image preview similar to the resize controls would help in those cases? Just thinking out loud at this point.


Adding to that as well :slight_smile: Namely, whatever the mechanism will be to enter the image description in a user-friendly way, it would be great if the final HTML output would use the semantic HTML5 tag for an image caption:

  <img src="…" alt="…">
  <figcaption>Image caption, shown below the image.</figcaption>

Putting that HTML code right into the Discourse editor is not possible right now – it will be filtered out at post cooking time. Adding that capability is however possible with a simple plugin, giving “proper” captioning abilities at least to the powerusers.


Supporting this at the HTML level should be straight forward but I worry about diverging from CommonMark here.

Perhaps open a topic to discuss it there?


This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.