Easily Post Code Snippets In WordPress

Palehorse Information Services invites you to celebrate the Grand Opening of our new location on the web! The reconstruction of the Palehorse Information website saw the move from a hand-coded site to WordPress, in order to leverage the simplicity of the blogging platform. We would like to mark this occasion by offering a door prize to all those who stop by.

Testing our new WordPress theme design revealed what many others have, no doubt, found; the publishing platform just hates raw code in a post. The WordPress Codex puts it thusly:

…putting code in your post that “looks” likes code, but “doesn’t behave” like code, is a frequent challenge for bloggers.

Well, we just couldn’t let the finicky filters have the last word, and we didn’t want to have to rely on an externally written plug-in. Besides, most of the plug-ins we saw, despite all of their author’s hard work, were either too bloated, too cumbersome to work with easily, or simply didn’t work.

After a little brainstorming, we came up with a simple solution–a set of functions based on php’s native htmlentities() function to convert any applicable characters into HTML character entities of any content wrapped in <code> or <pre> tags. We will get to the functions we came up with in a moment, but if you would like to use this technique, a couple of things need to be turned off in your setup before the functions can be added.

In a default WordPress installation, the pesky WYSIWYG editor and “wpautop()” filter are always inserting <p> tags whenever a double line-break is entered. If you are like us, those were the first things on the list that just had to go. So, if you haven’t disabled these “features” yet, turn off the WYSIWYG editor in the admin control panel, and then drop this next bit of code in your theme’s functions.php file to turn off the wpautop() filter:

/* Disables WordPress automatic paragraph formatting */
remove_filter('the_content',  'wpautop');
remove_filter('the_excerpt', 'wpautop');
remove_filter('comment_text', 'wpautop');

Remember, you’ll now need to wrap your paragraphs with <p></p> tags again. You should be used to this anyway if you’ve done any amount of HTML coding. It was actually more troublesome for us to omit them than to have to add them. (Yes, we are aware that we are a bunch of geeks.)

What we needed then was something to “scrub” the code of characters that could possibly cause markup to be executed when the page is called. Namely the '<' and '>' characters. We could use a converter like Elliot Swan’s app Postable, but that requires a trip to the converter, copy, paste, convert, copy and paste. Call us lazy, but we’d rather just write the damn code in the post and have it convert automatically.

To acheive this automatic conversion, we whipped up this set of functions, which will convert any troublesome characters, anytime they are wrapped in <code> or <pre> tags. Again, just drop these “code scrubber” functions into your theme’s functions.php file:

/**
*  This converts any applicable characters into HTML entities in content marked
*  with <code> or <pre> in order to allow for posting pure code, with minimal fuss.
*  Styles should be set correctly in the CSS file (re: whitespace, overflow, etc.).
**/
function code_scrubber($content) {
	return preg_replace_callback('!<code([^>]*)>(.*?)</code>!ims', 'code_scrubber_callback', $content);
}

function code_scrubber_callback($matches) {
	$scrubbedContent = $matches[2];
	$scrubbedContent = htmlentities($scrubbedContent, ENT_NOQUOTES, 'UTF-8', false);
	$result = "<code>$scrubbedContent</code>";
	return $result;
}

function pre_scrubber($content) {
	return preg_replace_callback('!<pre([^>]*)>(.*?)</pre>!ims', 'pre_scrubber_callback', $content);
}

function pre_scrubber_callback($matches) {
	$scrubbedContent = $matches[2];
	$scrubbedContent = htmlentities($scrubbedContent, ENT_NOQUOTES, 'UTF-8', false);
	$result = "<pre>$scrubbedContent</pre>";
	return $result;
}
add_filter('the_content', 'code_scrubber', '1');
add_filter('comment_text', 'code_scrubber', '1');
add_filter('the_content', 'pre_scrubber', '1');
add_filter('comment_text', 'pre_scrubber', '1');

Now, make sure that your theme’s style.css file has entries for ‘pre’ and ‘code’, and style them appropriately. The whitespace value for <pre> should be something like this, in order to retain the formatting:

pre {
	white-space: pre;
	}

You’ll probably want to fiddle with the rest of the CSS values to suit your tastes and conform to your theme, so we’ll consider the CSS formatting outside the scope of this article.

Now, anytime you wrap your code in either <code> tags or <pre> tags, all characters which have HTML character entity equivalents will be translated into these entities automatically.

Bear in mind, though, this is not a perfect solution, and there are a couple of caveats. First, don’t wrap a single <code> or <pre> tag without manually converting the wrapped tag’s angle brackets, or it may mess up your layout. You may also run into a snag if you need to wrap a closing <code> tag or <pre> tag (e.g. </pre>), so you’ll need to manually convert any angle brackets that give you trouble. But for the most part, the code scrubber should do the trick in most circumstances.

Ironically, the only trouble we’ve had so far was posting the code for this function, due to the closing </pre> tags near the end of the function. But a quick manual replacement of the opening brackets of the two closing tags, and all was right again. You don’t need to worry about double encoding of existing HTML entities (reconverting existing entities, e.g. &), because that feature has been set to false, as explained in the PHP Manual’s htmlentities() entry.

Also, wrapping one set of tags inside another is not necessary (e.g. <pre><code>…</code></pre>), nor is it advised. The <code> tag should be used for small, in-line bits of code, whereas the <pre> tag should be used for larger, multi-line blocks of code.

Second, automatic “smiley” conversion may also cause you trouble. You may need a more comprehensive solution than this one if you need to have smilies in your posts and comments–that is unless you know how to un-convert smilies for just the code blocks. In that case, leave a comment below on how to achieve this, we would appreciate it very much. We avoided it here by simply turning off smiley conversion altogether. We didn’t want them anyway (sledge-hammer mechanics to the rescue).

Another less defined caveat is the optional quote_style parameter, set here to ENT_NOQUOTES, which leaves both double and single quotes unconverted. If you would like to also convert quotes, change ENT_NOQUOTES to ENT_QUOTES. This will convert both double and single quotes, or use the default, ENT_COMPAT, which will convert double-quotes and leave single-quotes alone. We haven’t seen any reason to turn it on here; the wptexturize() filter seems to leave code blocks alone, but you can turn it on if you find you need it in your situation.

Our “Code Scrubber” approach may not be perfect, but it’s transparent to the end user (you), and is fully automatic. It may also be a good starting point for more ambitious projects in the future. We hope you find this useful, and, if you have any improvements, leave a comment and share your expertise with the rest of us. Happy coding!