How to Display Code on Your WordPress Website the Proper Way
If you run a development website, project documentation, product help section or anything similar from a WordPress website, chances are you’ve needed to display code at one time or another. Depending on the language used this can be a small pain or a really big pain.
In this Weekend WordPress Project, I’ll explain why this is such a bother and explore some of the options you have for displaying code beautifully and easily on your WordPress site.
Why Displaying Code is Difficult
To understand why displaying code is difficult you need to know some basic HTML. The code for making some bold text is to surround it in a tag. To create the bold text in that sentence I actually wrote
<strong>bold text</bold> into my WordPress editor.
So far so good, but now for the hard part: What if I want to show you how I did it?
Any time I type <strong> into the editor it gets interpreted as HTML code, which means it will disappear and instead be used to embolden the text.
The other problem that we have is syntax highlighting. Even if the code is displayed correctly it may be difficult to read without the correct styling.
Making Code Show Up
The best way to make code show up is to convert characters with a special meaning to HTML entities. You may already be aware that sometimes you’ll need to type
& instead of just a regular ampersand to make it show up properly. This is because
& is the HTML entity for the ampersand sign.
HTML entities are not interpreted as code but display just like their non-entity counterparts. In order to show me how to create bold text you would need to type:
< is the HTML entity for the lower than sign (hence the lt) and
> is the HTML entity for the greater than sign – hence the gt.
Adding Code to a WordPress Post the Simple Way
The simplest way to add code to your posts is to use the HTML entities and wrap everything in
<pre> tags. This tag is for displaying code and most themes will contain appropriate styling. A quick example of what I mean, straight out of a post:
This works just fine but it is a nightmare to maintain. If you have a lot of tags in there, not just the odd paragraph it becomes a jumble of HTML entities making it very difficult to edit the code. If I need to resort to this method I actually use my text editor to create the HTML entities.
I write normal code and then use my text editor to convert all HTML entities all at once. If you need to modify the code you can paste the converted version and decode them into their proper characters. If you use Atom.io you can use the HTML Entities package, if you use Sublime you can use the
HTML: Encode Special Characters command.
Even if you get a good workflow going it just looks so unruly in the WordPress post editor and – let’s face it – this is far from a quick workflow.
A Better Code Workflow
Grab Prism WP, install it and start writing code, following the guidelines below.
- Wrap your code in
<code>tags as well
- The code may receive a special class which designates the target language, this is used for highlighting
- If you’d like line numbers you need to enable this in the plugin settings and add the
line-numbersclass to the pre element.
Our code example above now looks like this in the code editor:
That looks much better doesn’t it? It has a lovely output as well, by default it looks like the screnshot below When using the Twenty Fifteen theme.
There are a number of other themes you can use, take a look on the Prism homepage. Themes can be changed in the right with the round thingies. The plugin allows you to change the theme in the settings of the plugin.
There are tons of services which allow you to paste your code such as Gist, JSFiddle and Pastebin. Each of these services has WordPress plugins that allow you to embed them into WordPress posts, like we do here at WPMU DEV with Gists.
I recommend going to the plugins search page on WordPress and searching for your preferred provider, you’ll find a great plugin in seconds.
I always like to come up with DIY solutions to problem, so let’s try and do some of this for ourselves. Let’s not get into the whole highlighting area – which is really very complex – but we can do a lot to make code insertion a lot easier in WordPress.
The biggest issue we face is the HTML entities problem. What we’d like is to write code as-is on the backend and get it to display as-is on the front-end as well without being interpreted as tags. The way we can do this is by adding a filter to
The idea is that before the content is displayed we’ll look through our content for any text within code tags and replace all the special characters in it with HTML entities.
I actually wrote a tiny plugin named Smart Code Escape to do just that a few months back. It’s a perfect example of something useful that uses all of 15 lines of code. Let’s take a look now.
The first thing you’ll want to do is create a plugin. We have a handy creating a plugin guide for you if you don’t know how.
In a nutshell: Create a folder in your plugins directory named
smart-code-escape and a file within that folder named
smart-code-escape.php. Add the following content to the file, I’ll explain everything in a moment.
The actual plugin has inline code documentation, if you’re interested download it from the repository and take a look. The first thing to notice is that I’ve added a filter to
the_content. This filter calls a callback function on content found between
The callback function (
smart_code_escape_pre()) takes care of the conversion. It checks if the content is wrapped in a
<code> tag first. I thought I’d add this to make sure the plugin doesn’t conflict with existing code plugins like the Prism one I mentioned earlier. I assume that if someone adds their code by wrapping it in a
<pre> and a
<code> tag they’re serious about code insertion and have a system in place already.
If the contents of the
<pre> tag is not in a code block the function replaces all special characters with their HTML entities.
As you can see, adding code to your website is not that difficult, you just need to know the basics of why characters get encoded and you’re all set.
If you have some great ways of adding code to your website let us know in the comments below.
Image credit: Pixabay.