The problem with code snippets... and how to fix it!

So you decided to write a tutorial about a topic you know extremely well. You are very familiar with the topic, so much so that you know all the code like the backside of your hand.

This tutorial has a lot of code, and you need it to look good! So you either screenshot your code editor which colours your code, or you use a tool like Carbon to generate some great-looking code snippets as PNGs.

This is awesome as now you can get away from using bland, ugly code snippets.

console.log("Hi!")

The problem(s)

While pasting a picture or screenshot of code might look good on your blog, it presents 2 major issues:

1. Your users can't copy your code

Imagine you're running into a problem while coding. You search on Google and stumble upon a great tutorial. Clear and concise explanations with code examples. You want to try the code for yourself to see if it's fit for your purpose, but to your frustration and horror, the code you've been reading is actually a screenshot. How would you feel? You'd rub your temples, or scream at the screen and move away from the article to find something else.

That's exactly what your users will do.

But there's another, more major issue:

2. Code images are inaccessible

For screen reader users, an image is only as good as its alt text. So what are you going to do? Write the entire code snippet as alt text? No, you shouldn't. So anyone with a screen reader is unable to read your code.

The solution

The solution to both these problems is pretty simple:

Use proper Markdown

The first thing to do is to use proper Markdown for code snippets. So if you're adding code, you should use this syntax:

```
console.log("Hi!")
```

Blogging platforms like DevTo and Hashnode have excellent code snippet colouring support:

console.log("Hi!")

So if you just include the language next to your top backticks (`), then they should be automatically coloured:

```
javascript console.log("Hi!")
```

But what if I'm writing on my own blog?

Use HighlightJS

If you want to make your code look beautiful on your own website or blog, without the need for inaccessible screenshots or Carbon images, you can use Javascript libraries like HighlightJS. Here's a tutorial to get started.

Conclusion

You work hard on your blog and you want everything, including your code to look great! Code snippets as images or screenshots might sound like the easy way towards this but you also need to think of your visitors. Visitors who would want to copy your code for later use and users who are only able to read your posts using screen readers. Be inclusive. Be human.

Thank you for reading.