Encoding your code
HTML has special handling for characters like < and > symbols, which can lead to some weird effects – blocks of text not appearing, broken formatting, and generally just not seeing what you expect to see.
This can all be fixed by “escaping” those characters. This process involves scanning the text for those characters, and replacing them with a special character-code that browsers can interpret as the correct symbol.
Depending on which kind of code you want to display, you might have to encode it so it won’t get “eaten” by WordPress. Basically, the characters leading to display problems are < and >, as those characters are used to open and close HTML tags.
Unless you’re using a plugin that takes care of encoding your code, you need to do so manually. Otherwise, the HTML tags such as <div> will be rendered as HTML by your browser, and will mess up your layout.
I’m using a handy tool called HTML Encoder to convert HTML special characters into escaped characters which will display correctly with a WordPress blog post.
Displaying code in your blog posts
There’s basically two ways to display code: the first one is to display a short snippet such as a HTML tag or a PHP function name. In that case, you should use a <code> tag, as shown below:
This is a paragraph and some PHP <code><?php echo "test"; ?></code>
Some other times, you want to display a block of code, as I often do on some of my posts. In those cases, you should embed your code within <pre> and </pre> tags:
This is a block of text/code embed within <pre> and </pre> tags.
If you’d like more information about using the aforementioned tags to display code in your blog posts, check out the page dedicated to the WordPress Codex.
Styling the <pre> tag
In order to make sure that your code will display nicely when embedded within <pre> and </pre> tags, there’s a few of things to consider:
- Always use a monospaced font. Popular monospaced with good browser compatibility are Consolas, Monaco and the widespread Courier.
- Avoid line breaks: your code won’t be readable if the lines are breaking all the time. To do so, use
white-space:pre;in your CSS code. - Make your <pre> horizontally scrollable, using the
overflow-x:auto;CSS property.
Here’s, for example, how the <pre> tags are styled on my blog:
article pre{
background:#f5f5f5;
border:1px #eee solid;
border-top:20px #eee solid;
font-family:Consolas, courier;
font-size:0.9em;
white-space:pre;
overflow-x:auto;
}
WordPress plugins to display code
When displaying lots of code on a WordPress blog, a plugin can be an option to consider. The main feature of code display plugins is generally syntax highlighting, which provides a way more readable code to your readers. But another very interesting aspect is the automatic encoding of HTML characters.
That being said, I’ve used that kind of plugins in the past and I always ended up using the good old “manual” way to display my code as many plugins are either too slow or demanding on resources, or require you to manually update your existing content. However, I’ve briefly tested three fresh plugins which seemed quite promising, so here’s the list:
- Code Prettify is a handy and lightweight plugin that uses the Prettify library. It doesn’t require you to use shortcodes, class names, or such. It fully supports the display of code snippets within both
<pre>and<code>tags. - Crayon Syntax Highlighter: Built-in PHP and jQuery, this plugin supports customizable languages and themes. It can highlight code from a URL or within a WordPress post. Definitely powerful and highly customizable, although not the fastest plugin around.
- WP-GeSHi-Highlight has been around for quite a while and is an interesting plugin with tons of features. It supports 240 languages, is fast and mobile friendly, and the outputted HTML is clean and valid.