More detailed guidance about alt tags for screenshots?

[vickytnz]

I am playing with adding screenshots and ideally want more detailed alt tag descriptions.

It turns out that this is possible but not documented:

      - text: "Design changes"
        src: design-changes.png
        alt: "Normally the image will use the 'text' variable as the default alt text. However if you want a more descriptive alt tag you can specify it here"
        caption: |
          You can include captions with each image, and each caption can include markdown. This is a screenshot of the [index page](/).

I wonder if this should be formally added to the documentation so that people can find it?

[frankieroberto]

@vickytnz ooh good point. Must admit, I’d forgotten about this feature (I tend to prefer inline images rather than images-at-the-bottom).

It is sort-of documented in the there’s an example of it in the example post in the template repository, and it’s also listed in the options for the Post layout on the govuk Eleventy plugin.

However perhaps it’s worth including elsewhere too?

Also possibly worth trying to explain the distinction between alt text and captions (which is kinda subtle!). I don’t think it’s necessarily about "more detailed", as I think you can have quite long alt text if needed (eg I had really long alt text on this post) - instead the caption might add additional context?

[vickytnz]

The example in the design history is for a caption but not alt text? I agree that they are different use cases, an alt text gives people who can't view the image an equal experience whereas captions give context (though GDS is starting to move away from alt text at all - but that's another story).

[frankieroberto]

Oh, you're right, I misread your comment somehow and thought you were pointing to the caption feature, sorry!.. 🤦

I also hadn't realised that the alt text defaulted to "Screenshot of [title]" which I guess is reasonable, but agree we should also document the ability to set alt directly. Let me do that now.