Trials and tribulations of using WordPress to display code syntax


Have you ever tried to display HTML, PHP or JavaScript code as part of a WordPress article? It’s not fun is it? Yet there are a few steps we can take to make code render exactly how we want it to.

First of all we need to understand what WordPress is doing wrong and why it is happening.

What you see is not what you get

WordPress’ WYSIWYG editor does a great job of making it a user friendly blog platform but unfortunately it is virtually useless when trying to write code. It tries to render HTML tags as HTML and it does some completely weird stuff to more advanced PHP and JavaScript code that defies rational explanation. It rewrites certain characters and just generally makes a mess of everything.

One solution is to switch the WYSIWYG editor off and write using the plain text editor. However, even using this method you still need to prevent HTML tags being rendered as actual HTML by replacing certain characters with their character codes.

How the hell are you supposed to write using complicated character codes – it’s just far too fiddly? And besides, what if you like using the WYSIWYG and don’t want to switch it off?

Not-so smart quotes

WordPress has a nifty little feature that turns a straight apostrophe or double quote mark into a typographically correct ‘curly quote’. Just like how your favourite word processor automatically curls quotes in to the words you wrap them round, WordPress does the same when it renders the page.

Curly quotes

Most of the time this is a pretty cool feature. However, when you want to display code (which is usually chocker-block with single and double quote marks) we want those quotes straight, not curly.

This is a separate issue to the WYSIWYG editor: this behaviour happens when the article is viewed and page is rendered. WordPress is converting straight quotes to curly quotes on the fly. It is caused by a function called wp_texturize() which we could hack out of the core code. But that is a bit of a sledgehammer and nut way of solving things. Curly quotes are quite nice most of the time so why kill them entirely?

Hakan Carlstrom’s Codeviewer plugin

There are many plugins that attempt to solve WordPress’ code rendering issues, but most involve disabling the WYSIWYG editor and writing your articles through the text editor.

Hakan Carlstrom’s Codeviewer is different in that it grabs the code from an external text file, so WordPress can’t have its wicked way and change characters and mess up your code. Codeviewer also displays the code with line numbers and automatically wraps long non-breaking lines.

Some might find it more fiddly having to upload and refer to external text files (not unlike you already do for images), but trust me: if you want to continue using the WYSIWYG editor, this is your only option.

GeSHi – Generic Syntax Highlighter

This isn’t actually a WordPress plugin, GeSHi is a generic text highlighter that can be used on any blog, forum, Joomla installation etc. It cleverly highlights code for ease of viewing and also automatically links to references on the or W3C sites.

Fortunately, the aforementioned Codeviewer plugin integrates brilliantly with GeSHi meaning you just need to bung the GeSHi files into your plugins folder and the two combine to offer you hassle-free colour-coded visuals for any script language you can possibly think of.

Alex King’s WP Unformatted plugin

We’ve got WordPress displaying some beautiful colour coded syntax but, dammit, WordPress is still turning all those single and double quotes in my code into curly quotes. Smart quotes indeed!

Fortunately Alex King’s simple WP Unformatted plugin allows smart quotes to be turned off on a post-by-post basis. This allows you to keep the curly quote thing going on any non-code related blog article.

For me this isn’t an ideal solution. I’d love a plugin that would disable smart quotes only when code is rendered, and not throughout the rest of the article. I found one or two plugins that claimed to do this, but they didn’t work with my Codeviewer and GeSHi combination. So for now, Alex King’s plugin does the job.

Code beautiful code

I think this combination of plugins works very well. For an example of how they combine have a look at my article on improving WordPress’ the_excerpt() function.

There are other ways of displaying code and it may be you find alternative ways more convenient. Please let me know if you do. One thing’s for sure: it’s not as easy as it should be!

Do you display code on your WordPress blog? If so, how do you get it done?