I always knew image alt-text existed. I knew about it from learning HTML - it’s the text that shows when the image doesn’t load. And it’s also on XKCD as the extra pun (TIL that’s actually title= and not alt=). It’s only recently, when Twitter added image descriptions1 and my feed started talking about them, that I realized how important they are for accessibility.

Since then, I’ve been making an effort to describe the images in all my tweets to the best of my ability. It’s not always easy (try describing control-flow graphs and explaining the differences between them,) but it is definitely worth it.

Yesterday I blogged for the first time in a long while. As I added images to the post, I realized that I don’t know how to properly describe images in Markdown. Until that day - I’ve never really done that.

Markdown Alt Text

The Markdown2 image syntax consists of 3 parts:

1

![alt text](url "title")

That will (usually3) be rendered as:

1

<img src="url" alt="alt text" title="title"/>

This is simple enough, and even allows us to write long-form alt text:

1
2
3
4
5
6

![This image doesn't exist.
I am only writing this to show that we can have really long alt-text.
It can even span multiple lines as long as there are no blank lines in it.][long-alt-text]


[long-alt-text]: my-image-url

This also benefits us as we’re writing - we have a description of the images we use, in our text-only editors!

And we should all use it to improve our posts and make them more accessible. I still need to go over my past posts and properly describe the images in them.

Future Ideas

While learning a bit on this, I searched for “markdown accessibility”. This lead me an article about improving the accessibility of my markdown. It seems that there’s quite a lot I need to fix in my blog. So that’s one thing I need to figure out.

Generally, the things to fix fall into 2 categories: authoring and rendering. Rendering is purely a technical fix - I need to ensure my blog theme is accessible by changing the templates. The authoring part is a bit tricker. It’s too easy for me to miss alt-text here and there, or have multiple links with the same name. So for this - I think I’ll have to write a linter.

  1. From the Twitter docs, saved to the archive.org so that it doesn’t disappear:

    1. How to add image descriptions
    2. How to write great image descriptions
     ↩︎

  2. When talking about Markdown I’ll try to refer to CommonMark unless stated otherwise. ↩︎

  3. In this blog, for example, I display the title using <figure> and <figcaption> tags. ↩︎