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.
Top comments (7)
Agreed. FYI carbon has an iframe embed option too which you can use to embed an accessible copyable version. Also a useful option.
Pretty pointless if you ask me and only makes things needlessly complicated. Just use a code block instead...
That's what I do in my articles here. But on Medium the code block looks awful and this looks pretty great.
Medium supports iframes? That’s new
They have a specific thing for medium in the pull down. Haven't tried it myself. It does support embedding gists though.
HighlightJS is the best. I use it on a few projects and it looks so good!
It is amazing!