This is intended for anyone operating a Wordpress site, with reason to display code snippets in their posts. And no worries if you’re a little fuzzy on what that means.
This is a code snippet that I’m looking at right now in my second monitor:
Code, or source code, is an artifact that programmers use in their day to day to, well, tell computers what to do. It tends to have very precise and specific formatting, wording, and structure – much more so than normal prose. In that snippet, there’s a good reason that some words are blue and others orange, and there’s a reason that some lines are indented and some aren’t.
Because of all of these nuanced (and, for many, inscrutable) rules, displaying code snippets in a blog post tends to be more of an adventure than the normal fare of paragraphs, bullets, and the occasional screenshot.
For most Wordpress blogs, here is how I’d recommend handling code snippets, in preferred order.
1. Install a Code Snippet Plugin
For my money, your best bet is to install a Wordpress plugin to help with this. A good syntax highlighter plugin will show up in your post editing tools and furnish you with options to insert source code into the post. Ideally, find a versatile one that handles lots of programming languages and lets you specify which language the code is in (unless, say, all of your posts are about a specific language).
I don’t have a specific recommendation offhand, because I’ve used a lot of them over the years and the landscape tends to change and shift.
But the general goal is that when you put code into the post, in preview mode, it should automatically look like my screenshot (minus the dark mode background). That is, the syntax highlighter should take care of making the code look like code and coloring the different words and symbols in the code.
Benefits: Makes the code looks good, favorable for SEO and user experience.
Challenges: If you’re not technical and/or your website admin, you’ll need to have that person do it for you.
2. Carefully paste using the <pre> tags
If you don’t have a syntax highlighter and can’t get one, you can roll up your sleeves and get ever so slightly into code yourself. I’m talking about clicking on this button in Wordpress, which lets you actually look at the HTML of the blog post.
When you do that, you’ll lose the pretty “WYSIWG” editor and find yourself using HTML. I generally don’t recommend anyone edit this way, let alone non-techies. But this does give you access to the “pre” tag, which is a decent option for displaying code.
All the pre tag really does is cause whatever you paste within it to be rendered exactly as pasted, preserving tabs, spaces, line breaks, etc. And, remember, with source code, all of those things matter to your readers.
public static void doStuff() {
}
vs
public static void doStuff()
{
}
The distinction between these things may seem trivial to you, but ask your developers which one of these is correct and watch the fireworks. Oh, and capitalize public and the whole thing completely breaks, and they’ll all just yell at you instead of each other.
Aside from having a little fun, I mention this because it’s important to get the code exactly right. So what you want to do is take from a valid source like a source code editor or something a programmer has created for you, and paste it, exactly as-is, in between the <pre> and </pre> tags in your editor.
This won’t give you fancy coloring, but it will at least look like proper code, if plain.
Benefits: Preserves the code from its original source, some CMS-es might format it in a visually appealing way, doesn’t require any additional plugins or work from other people, favorable for SEO and user experience.
Challenges: Forces you into the “code” editor where mistakes are easier, no pretty syntax colors.
3. Paste the Code into the Normal Editor and Do Your Best
In an instance of “do as I say, not as I do,” what I did in the last section is actually what I’m recommending you do in this section. My excuse is that this is a Webflow site, not a Wordpress one, and not that I’m just lazy, and that’s what I’m sticking with.
In the section above, I just hand-typed C source code into the normal editor and relied on the fact that neither example depended on tabs and precise, specific spacing. And that’s what we’re talking about here. You’re going to hand-type in spaces all of the code yourself, doing your best to make it look like the source you got it from.
If you do this, you’ll absolutely want to double check in preview mode, because it may look different live than in your WYSIWYG editor.
Benefits: No additional work from anyone, no need to go in the “code” section of the editor, favorable for SEO and at maybe slightly favorable for user experience.
Challenges: Forces you into the “code” editor where mistakes are easier, no pretty syntax colors, usually looks pretty janky, especially to developers.
4. Screenshot the Code
The worst option, in my opinion, can actually be the prettiest and easiest, depending on how you’re receiving the source code. And, that’s what I did in the intro to this post – I took a pretty screenshot of my own code from VS Code and pasted it.
The reason this is an issue, in my mind, is that your readers are engineers. And generally engineers reading a blog post about code are going to copy the code and paste it into their own version of VS Code to try it out. Unless you screenshot the code, of course, in which case you’re forcing them to hand type the entire thing, instead. Also, for anyone using a screen reader, womp-womp.
In addition, you lose out on the code existing as text in the post for crawlers to pick up and process. I really don’t think that’s the end of the world, exactly, but it’d be a lot better if search and AI crawlers had the whole picture instead of most of it, plus some screenshots they can’t parse.
If you’re going to do it, definitely turn off any kind of spell or grammar check or anything else that shows squigglies or distractions before taking the screen shot. You could consider typing out the code as alt text, which solves the screen reader and crawler issue, but is, of course, pretty labor intensive and if you’re not a programmer you might mess it up.
Benefits: Easiest option of all, tends to be the prettiest option if coming from a code editor.
Challenges: Unfavorable for UX/SEO.