Working with Code in WordPress

Whether you’re a tech blogger, web developer, WordPress ninja or simply run your own personal blog, there are times when you’d like to share code samples in your posts, like CSS snippets, PHP scripts or HTML. There are numerous of ways of dealing with code in WordPress, and in today’s post, we’ll try to cover some of them, including generic ways, code inserts and syntax highlighting plugins as well as third-party services with embed options.

Which of the ways you pick is totally up to you, they all have pros and cons. Generic inserts are difficult to “syntax highlight”, while code plugins might have updates, compatibility and visual editor issues. Third party services, while looking good might not give you the SEO benefits you’re looking for and require extra maintenance work when it comes to editing your code snippets.

Let’s start by looking at what I mean by generic code inserts.

Generic or Standard Code Blocks

When I say generic I mean a standard way of inserting code blocks in WordPress. A way that could later be styled and even syntax highlighted accordingly, without having to return back and edit each code block. I’m quite sure you’re familiar with this way, since it actually involves two HTML tags — code and pre, inline code snippet and block code snippet respectively. There are other tags available, but the two mentioned are used most and available in the WordPress content editor.

Inline code is when you don’t really refer to a code snippet, but rather a tiny piece of it, when perhaps explaining what one or two variables mean in a larger code block. They’re generally used within the text itself and most of the time don’t have any extra styling options, except of course a fixed-width (or monospace) font family, such as Consolas.

Inline Code Editor in WordPress

Inline code is surrounded by the opening <code> and closing </code> tag which is available in the editor toolbar in HTML mode. Note that the two tags I mentioned have been inserted that way.

Multi-line code blocks are more common when inserting relatively large chunks of code, which sometimes doesn’t even fit on screen, requires a horizontal or vertical scroll bar. These types of code blocks are inserted using the pre HTML tag which stands for “preformatted” and is available in the format drop down in the visual content editor.

Multiline Code in WordPress

Interesting fact, that the new version of the TinyMCE editor shipped with WordPress 3.2 can actually recognize code blocks when pasting from code editing software such as TextMate and TextWrangler, automatically giving them the preformatted style.

Note that when working with the standard inline and multi-line code blocks, you sometimes have to encode certain entities, such as the less than and greater than symbols, single quotes and double quotes and others. Otherwise you might end up with with the contents of your code blocks being parsed as HTML. The visual editor does this for you while the HTML editor doesn’t. More about using both tags in the Writing Code in Your Posts article in the codex.

Code Blocks and Syntax Highlighting Plugins

The advantage of these is that you’ve got lots of different styling options as well as full-blown syntax highlighting for the most popular programming and scripting languages. Such plugins often come with a shortcode that you can use both in the visual editor as well as the HTML editor.

The disadvantage is the maintenance needed to switch from one plugin since they might be using different shortcodes or tags, therefore breaking your existing posts upon plugin deactivation or error. Another disadvantage is that some of them work with the HTML editor only, meaning that your code will be messed up when switching to the visual editor, even if it’s for one second.

Most of the output is still that very same pre tag, but with some JavaScript and HTML magic they’ll give you line numbering, syntax highlighting, copy to clipboard, raw view and line wrapping at no extra cost.

There are quite a few plugins for dealing with code in WordPress. I’ll list some of my favorites and ones I’ve worked with myself. You can search the plugins repository for “code” or “syntax highlight” to find out and give others a try too. Make sure that you’re working on a local WordPress installation or one for testing purposes. Such plugins can easily break a few existing posts of yours.

Preserve Code Formatting

This plugin is available in the WordPress repository and has recently got an update for version 3.2.1 support. It basically states that it will preserve all the text that you have typed in your editor, removing some of the filters used to convert single and double quotes, dashes and double-dashes and others. Although something you might be asking for, this plugin does not work with the visual editor, so watch out for that.

Syntax Highlighter Evolved

One of my favorite syntax highlighting plugins, written by Viper007Bond and Automattic, available for download at WordPress.org and based on Alex Gorbatchev’s JavaScript solution for Syntax Highlighting. Supports a wide range of programming and scripting languages, several different views and skins, with the ability to create your own. The WordPress plugin allows a new shortcode where you can specify the language you’re about to write code in.

Syntax Highlighter Evolved for WordPress

Again, this plugin is best suited for HTML editing rather than visual editing, although I have noticed that it works fine to a certain point — the point when it comes to using the opening and closing PHP tags. The visual editor automatically encodes the symbols into HTML entities, while the syntax highlighting plugin prints them out as is, thus you’ll see the entities code, rather than the symbols. Hoping for this to be fixed in a future update.

Another alternative, based on the same JavaScript libraries is Syntax Highlighter for WordPress by @wokamoto.

WP-Syntax

Another favorite, with a recent update, WP-Syntax is based on the GeSHi highlighter, supporting a wide of programming languages. Lovely thing about WP-Syntax is that it’s integrated directly into the pre tag, requires no extra shortcodes or maintenance. The additional lang attribute will not cause anything strange, should WP-Syntax fail to load or is deactivated.

WP-Syntax Plugin for WordPress

My suggestion is that if you’re using the generic way of inserting code without highlighting, take a second to add the additional language attribute to your pre blocks, you might consider using this plugin in the future. The downside is that your language attribute might not be W3C valid.

I’m sure you’ll find other plugins for code highlighting in WordPress, but again, test them locally, read the reviews, read about the author and take note of the update frequency. You can’t risk to have to edit all your hundreds (or thousands) of code snippets if your favorite plugin does not get a compatibility update with the next WordPress release.

Third Party Code Hosting Services

Before diving into this, note that third party services have a lot of benefits, but one major drawback, and that is maintenance. By using third party services to host your code, you’ll have to go back and forth from your post to the service, even for the slightest code changes. Other disadvantages include possible service downtime (if you can’t afford that) and SEO, since your code will not get indexed by search engines.

Code hosting services generally work like YouTube videos, they’ll ask you to provide them with your code snippet, and then give you an embed code that you can paste on your website to insert that snippet. Such services will most likely give you syntax highlighting, line numbering and styling options at no cost, but will most probably leave a credit link when embedding the code. Credit links might be annoying, especially if you’ve got several code blocks in your post content.

My favorite in this category is of course Gist by Github which really takes “pastebins” to the next level by providing file naming, several files in one paste, easy embed option and the ability to modify your code snippets at any given time with a list of revisions. When embedding code from Gist to your WordPress blog, you’ll have a nice looking block of code, with view and raw view options, plus a Gist view that will take you to the Gist’s page. This is very useful when you’re working with several files in one post.

Gist Embedded in WordPress

Gists (like most of the other services) are embedded via JavaScript, plus there are numerous WordPress plugins that allow you to work with Gists in a shortcode manner (although I don’t see much reason behind those).

Alternatives to Gist with embed options are Pastebin.com, Code Tidy and Snipplr. You can find other options in this Wikipedia entry called comparison of pastebins.

Keep in mind that by using such services, you’re hosting your code snippets on a third party. So make sure they’re reliable, read about the service and it’s history. Read about how long your code snippets will be hosted, least you can agree for is “forever” and try it out in action before making your choice. I’d also suggest you backup your code snippets somewhere so you don’t end up loosing it all.

Conclusion

So we’ve covered working with code in WordPress. Generic HTML ways for inline and block code snippets, syntax highlighting and code management plugins and finally third party code hosting services (or pastebins) with embed capabilities. It’s up to you which one you go with but try them all out before making your final decision.

Personally I used to love the WP-Syntax plugin for a copule years, then switched over to the Syntax Highlighter Evolved plugin. Nowadays I’m quite okay with generic ways of inserting code, especially since there’s no hassle with the visual editor code glitches, but starting to think of adopting Gist embeds in some of my works.

Thanks for reading and hope you enjoyed it. Tell us how you manage your code in WordPress, what services and plugins you’re using and how you’re dealing with the visual editor. What options do you mostly look for? Highlighting and line numbering or simplicity and bullet-proof performance? Use the comments section below to post your thoughts and don’t forget to stay tuned to our RSS feed.