Sharing Code Snippets on Social Media, the accessible way! [Quicka11y]

Welcome to the first "quick accessibility" post to quickly (quicka11y 😁) improve the accessibility of your content, websites etc.

Today's tip is all around improving the accessibility of some of your social media posts, in less than 30 seconds! Let's jump right in!

Edit / note!

There was a little confusion in the comments.

Just for clarity, what I am suggesting here is targeted for social media. This is due to the lack of flexibility you have in terms of markup and tools to make things accessible.

Please, if you are displaying things on a site where you control the markup and or CSS, use properly marked up code blocks and use CSS to make them as pretty as you want (as long as you don't ruin the accessibility of course!).

For example, on DEV, just use triple backticks and state the language used to get properly marked up code snippets...not images.

For example, this markdown:

``` js
const array1 = [1, 4, 9, 16]; 
// Pass a function to map 

const map1 = array1.map((x) => x * 2); 
console.log(map1); 

// Expected output: Array [2, 8, 18, 32]
```

will look like this:

const array1 = [1, 4, 9, 16]; 
// Pass a function to map 

const map1 = array1.map((x) => x * 2); 
console.log(map1); 

// Expected output: Array [2, 8, 18, 32]

and that is far more accessible and looks good enough!

Hopefully that is clear, now on with the article!

What are we trying to improve?

Loads of developers and companies share amazing, beautiful code snippets on social media every day!

The problem is, the way that they share them is not accessible...and it provides a poor experience for everyone.

Let me explain...

How most people / companies share snippets

[Note: alt description deliberately omitted as an example]

People share code snippets like the one in this above, using tools like "carbon" to create pretty code snippets.

But an image of code is not as useful as actual code (and is not accessible).

You see, anyone using assistive technology (for example a screen reader), cannot access the code in your image as they need the code as actual text for a screen reader to work!

One way that people attempt to fix this is to add all of the code to the alt description on the image. 👎🏼

Adding code to the alt description

[note: the alt description in the above image is not accessible]

It is well intentioned, but still not very accessible.

You see alt text is a single line text attribute.

So when you add all of that code to an alt description it gets "smushed" onto one line and is read as plain text, which is nearly impossible to understand.

It ends up being like this (this is the alt of the above image):

const array1 = [1, 4, 9, 16]; // Pass a function to map const map1 = array1.map((x) => x * 2); console.log(map1); // Expected output: Array [2, 8, 18, 32]

As you can imagine, it is very difficult to understand that code and know where comments end and being etc!

So screen reader users cannot really use your snippet, even with the code in the alt.

On top of that, everybody who wants to try your snippet will have to retype it, character by character into their IDE.

Time consuming, prone to errors and a terrible User Experience (UX).

A better way

So can we do better?

You bet we can!

Here is a straight-forward way to make your code snippets top-tier, easy to copy and super accessible!

• Step 1: create your code image (same as before).
• Step 2: add a description of what the code does (not the actual code) in the alt description.
• Step 3: Link to a GitHub Gist,CodePen or web page containing the code.

That is it!

Let's look at our earlier example!

The template we will use is:

[Explanation of code]

[link to Gist]

[image of code with alt description explaining, briefly, what the code is for]

Let's see what that would look like.

Better way example

The map() method of an Array instance creates a new array, populated with the results of calling a provided function on every element in the calling array. [MDN]

Here is a demo: https://gist.github.com/GrahamTheDevRel/9ba078625dd07acaee2765c86f43f911

[Note: The alt text in the above image reads "Code example for using the map function in JavaScript."]

Quick notes:

First of all, above I have included the full URL as that is how social media tends to handle URLs. If sharing on a platform that allows you to change the text of a hyperlink, then please make your text more descriptive like "GitHub Gist demo for JS Map".

Secondly, if you do use GitHub Gists, as I have here, don't forget to change from "secret gist" to "public gist" before sharing.

Finally, if your code snippet URL is too long (for example if a long URL takes you over your character limit on X / Twitter) you can handle that slightly differently.

In that case, it's acceptable to say "Code example in next post" and then post the URL as the first reply under the original:

Post 1: explanation + "Code example in next post" + image (with alt!)

Post 2: "Code snippet for JS map: [link]"

That way, you can protect your character count while still providing an easy to find and use code example.

A quick win, with huge impact!

So with all that in mind, how much extra time do you think that took me?

It took about 30 seconds!

I had to copy paste the code into a Gist, give it a title and a file name, grab the URL and paste it into my post.

Very little work, but look at what we have achieved:

• ✅ Millions of people using Assistive Tech (Screen Readers) can now access the code snippet.
• ✅ People who want to try your code snippet can follow the link and copy and paste it.

A wider audience, inclusive practices and better UX?

That is a great return on time invested!

What now?

• Create more accessible snippets going forward!
• If you see someone (particularly Companies!) sharing inaccessible code snippets on social media...share this post with them!

It only takes a few of us to make a huge impact on inclusion...I hope you join us! 💪🏼💗

Comments

[Vincent A. Cicirello]

On a site like DEV that supports code blocks in Markdown, are there any accessibility issues with such code blocks? Obviously for sites without such support, using gists or codepen, etc as you describe is the way to go. Are there any reasons to do it that way here on DEV as well instead of using code blocks?

[GrahamTheDev]

No not really on DEV, code blocks are far better and because we can set language I think the syntax highlight looks pretty enough.

It was more for social media and sites where codeblocks are not supported, I perhaps didn't make that clear.

I will try and remember to make an edit in the morning to make that clear! 💗

[Vincent A. Cicirello]

When I see code on other sites in images I usually stop reading, and I don't have accessibility needs. So I can only imagine how bad it is for those who do.

[Andrew Bone]

I'm not sure why "A quick win, with huge impact!" reminded me of the Lion King but it did.

[GrahamTheDev]

Haha, I kind of like the idea of my accessibility tips being "slimy, yet satisfying"! 😱😁💗

[lionel-rowe]

Kinda surprised and disappointed to learn that assistive technology doesn't support line breaks in alt attributes at all. What would be the proper accessibility-friendly way to do this if you have full control of the markup and don't want to link out to another page but still wanted to use an image (e.g. it's an image showing a formatted stack trace or including some text editor UI)? I guess aria-labelledby?

<pre id="code-block" class="sr-only"><code>
for (let i = 0; i < 10; ++i) {
    console.log(i)
}
</code></pre>

<img src="code.png" aria-labelledby="code-block">

I guess automated a11y checkers might yell at you for omitting alt though... but is it necessary to still include it if aria-labelledby is provided?

[GrahamTheDev]

So to be clear, the reason assistive tech doesn't include line breaks in alt attributes is because alt attributes are not intended to be used to describe things like code "word-for-word".

This post is targeted at social media as you have no where near the same flexibility as you do in a website you build / control.

What you suggested is "not bad" (better than putting it in the alt attribute), but at the point where you are creating a properly formatted code block...just display the code block.

That way you get the benefits I said within the article, such as being able to copy and paste it!

And if you are at the point where you can use sr-only classes, you have full control of visual appearance and the underlying code, so you can always use CSS to make a code snippet look just like one of the images you would create via carbon etc. (In fact, you just gave me a great idea!).

I guess automated a11y checkers might yell at you for omitting alt though... but is it necessary to still include it if aria-labelledby is provided?

A good accessibility checker would not, as technically what you did is correct and provides accessible alt text. But yet again, the odds are if you are using aria-labelledby as you need multi-line text...then you have probably not got the accessibility quite right.

If anything isn't clear here, please do say and I will try to elaborate more. 💗

[Francisco Zapata]

Brilliant!!!
I agree with you bro. I try to use the triple backticks when I can, but your proposal is beautiful. I buy it and I'll do it that way.

(function thanks() {
  console.log('Thanks a lot for sharing it')
})()

Blessings from Venezuela.

[Ben Sinclair]

I wrote something similar a while back about embedding code in posts.

[GrahamTheDev]

Nice! Thanks for adding this article to it!💗

I see you struggled with backticks like I did. 😂 The trick is <pre> tags in case you didn't ever find the workaround!

``` content ```

[Vincent A. Cicirello]

If you want to show the backticks in a code snippet, you can put 3 tildas ~~~ on the line before the opening backticks and then again on a line after the closing backticks.

```Markdown
## Example markdown block
Blah, blah, blah...
```

Which produces:

## Example markdown block
Blah, blah, blah...

[GrahamTheDev]

oh nice, didn't know that! 💗💗

[Ben Sinclair]

I never did find the workaround, but I never needed to do it again either :)

[Harendra Kumar Kanojiya]

console.log("I am sharing like this")

[sharc]

Very well structured post!

It reads like a (tiny) research paper:

1. Define problem
2. Give examples of WHERE the problem occurs
3. Propose a solution
4. Showcase the solution
5. End with conclusion on why the solution is needed.

These are basic principle of good writing, but I rarely see a good execution of this online. Good job!

Also, thanks for mentioning the Github Gist. It went over my head for some reason, but now I will try it.

[GrahamTheDev]

Thanks! 💗

[Sumit Saurabh]

Thank you for writing this, Graham!

I'll try to employ this in my posts going forward ✨

[Vuong]

Sharing code snippets on social media should have customization options, themes, and links to repositories or gists..

[GrahamTheDev]

Yeah, that would be amazing! 💪🏼💗

[Shawn2208]

connect-codechat-4c2d444b36df.hero... my real time chat app supports code in markdown.