Displaying code on Medium: The DO’s and DON’Ts

Photo by Glenn Carstens-Peters on Unsplash

For someone who has never posted on Medium options to display code— apart from usual code blocks — might not be that obvious. It gets even worse when you see copy-pastes of IDE screenshots.

Which brings us to the first don’t of this post:

Don’t insert screenshots of code as images

If you absolutely must know why.

It may seem very convenient but keep in mind your readers, after all, you are writing for them. Some people have dark themes in their IDEs and while your theme might be OK for you it is not necessarily so for others.

People also have different resolutions on their screens and different font sizes in their IDEs. Ever saw a non-scaled screenshot made on a 4K display while reading an article on an FHD monitor, or even worse, a mobile phone?

If you’re not comfortable with writing code directly in your browser window, then copy it from your IDE and paste as a code block

Another argument against screenshots is that someone might want to copy a piece of your code to try it out. And copying from a screenshot is not that easy. Of course it’s not good to copy-paste code, but let’s face the reality, everyone does that. So instead of pasting screenshots…

…do use code blocks

Code blocks are very useful for displaying bigger parts of code. To create a code-block you need to start from a new line and insert three backticks ``` which will create a code-block where you can paste code from your IDE, for example, or write it from scratch in the browser like so:

class Person(val firstName: String, val lastName: String) {
    val fullName = firstName + lastName
    
    fun walk() {
        // do some walking
    }
}

You can also use medium’s formatting options inside the code blocks if you want to emphasize some parts of it:

class Person(val firstName: String, val lastName: String) {
    val fullName = firstName + lastName
    
    fun walk() {
        // do some walking
    }
}

If you like keyboard shortcuts, then Medium has something to offer here as well. Simply select your code and press Ctrl+Alt+6 (on Linux and Win) or Cmd+Option+6 on Mac and your text will be formatted as a code block.

Sometimes you want to format a word or two as inline code as I have in the paragraph above, therefore…

…do use inline code to highlight your text

Same as bold or italics, inline code is a good way for emphasizing parts of your text that belong to the code you’re describing. Just like with markdown, inline code starts with a backtick symbol ` and ends with one.

If you want to write the the text first and then mark some pieces of it as inline code, then selecting the text you want and pressing the backtick ` key once will do the trick. You can’t, first write something and then surround it with backticks like this: `something`, the formatting won’t apply.

Copy-pasting also does not work and if you try to paste a text inside the inline code the formatting won’t apply to the pasted text, which is quite obvious since inline code follows the same rules as bold and italics formatting.

Don’t abuse inline code

On the other hand something like this:

public class Main { public static void main(String[] args) { CarJ car = new CarJ("Ford", "Mustang", 1968, null, nunll)} }

does not look good at all. Keep it simple and keep it short for inline code.

Although this one is very obvious and I’m not sure why would anyone do such a thing, but just for the sake of it I thought I’d mention this point as things like this sometimes pop-up.

Do use embedded code

Another great way to display code is by using embeds of github gists.

The advantage of this approach is that the embed is synchronized with the gist and if you make some changes in the gist they will automatically reflect in the article.

You also see line numbers and the code is even highlighted just as it is on github.

For me this is a preferable way to display code if there is more than a few lines that I want to show, otherwise I would stick to code blocks.

Note that gists are embedded as a whole, hence…

…don’t (usually) paste gists with more than one file

This might not be that obvious but if your gist contains multiple files you can’t select only one of them to be displayed, therefore you might end up with something like:

In most cases it is better to keep to 1 file per gist if you’re planning to add those gists to a publication. It can be a bit annoying to create multiple gists but it’s much more readable and you rarely want to show more than one file at a time.

As an alternative to github gists…

…do use embeds of runnable code

This is a great way not only to display your code but give your readers an opportunity to run it directly in the browser.

One online IDE that I know of which can be used for this is repl.it. Visit https://repl.it/languages/ and see if they support your language (if not try finding an alternative, there are many other online IDEs out there that allow you to share code), write some code, click on share and copy the link, then paste it as embed in your post.

Note that if your browser has DNT (do not track) enabled most likely you won’t be able to see these kinds of embeds.

To recap:

• Don’t use screenshots, ever, even if they seem easy to use.
• Use inline code wisely — with great power comes great responsibility.
• Use code-blocks
• Use embeds of github gists, preferably with 1 file per gist
• Use embeds of working code examples from online IDEs