I’m in the process of moving my technical blog from my personal site to this site, and as part of that move, I wanted to improve the look of code in the articles I write. I started with a Microsoft Live Writer plugin called Paste As Visual Studio Code. It’s a decent plugin, but it has some display quirks and it embeds a lot of raw HTML in my posts. So, I continued my search.
Today I stumbled upon a WordPress plugin called SyntaxHighlighter Evolved by Alex, aka Viper007Bond, at Automattic (the folks who develop WordPress). It uses the SyntaxHighlighter JavaScript package by Alex Gorbatchev do the highlighting. This is the same plugin that is used on the wordpress.com site for posting source code.
This plugin makes adding source code to your blog post extremely simple. It uses WordPress shortcodes to allow you to indicate language and a host of other settings, like this:
[sourcecode language="css"] your code here [/sourcecode]
You can abbreviate the shortcode to just the name of the language, like so:
[css] your code here [/css]
For example, this code will display the following C#:
[csharp]foreach (string name in Names)
Console.WriteLine("Name = {0}", name);[/csharp]
foreach (string name in Names)
Console.WriteLine("Name = {0}", name);
The plugin provides a rich settings page for specifying defaults as well as various styles.
You can find the set of language aliases on Alex Gorbatchev’s website. Note that only language aliases with letters, numbers, and dashes are supported by the plugin.
Additionally, you can override parameters for a particular instance of code right in the shortcode, like so:
[text light="true"]Fatal error occurred when blah blah blah[/text]
The parameters that can be specified this way are listed on the settings page for the plugin. Here is a summary:
| Parameter | Description | Examples |
|---|---|---|
autolinks |
Toggle automatic URL linking. | autolinks="false" |
classname |
Add an additional CSS class to the code box. | classname="samplecode" |
collapse |
Toggle collapsing the code box by default, requiring a click to expand it. Good for large code posts. | collapse="true" |
firstline |
An interger specifying what number the first line should be (for the line numbering). | firstline="152" |
gutter |
Toggle the left-side line numbering. | gutter="false" |
highlight |
A comma-sperated list of line numbers to highlight. | highlight="13,21" |
htmlscript |
Toggle highlighting any extra HTML/XML. Good for when you’re mixing HTML/XML with another language, such as having PHP inside an HTML web page. The above preview has it enabled for example. This only works with certain languages. | htmlscript="true" |
light |
Toggle light mode which disables the gutter and toolbar all at once. | light="true" |
padlinenumbers |
Controls line number padding. Valid values are false (no padding), true (automatic padding), or an integer (forced padding). | padlinenumbers="false" padlinenumbers="3" |
toolbar |
Toggle the toolbar containing the helpful buttons. | toolbar="false" |
wraplines |
Toggle line wrapping. | wraplines="false" |
Notes and Room for Improvement
All in all, this is a very rich plugin that does what a plugin should do – make the creation of posts easier. However, it isn’t perfect. There are two issues I’ve run up against, but neither one is a showstopper.
- The prescribed method for including examples of the shortcode in a post is to just do it. Viper007Bond says that the plugin won’t parse instances of the shortcode within another instance of a different shortcode. This will typically only be a problem for the text shortcode. What you can do is something like this:
[code lang="text"][text]Some text you want to show as code.[/text][/code]
- The plugin modifies the behavior of the Visual Editor to recognize its shortcode and modifies the look of text within its shortcodes. This is a very nice feature. However, when you switch from Visual mode to HTML mode, you cannot see why the text looks different between the two modes. One of the things I really like about HTML mode is that it allows me to check the actual HTML. I know, WordPress adds its own HTML before actually displaying a post or page, but the rules are few and fairly well understood. Maybe I’ll just add another rule and stop whining 🙂
Even with these issues, I’ll be adding this plugin to my stable of plugins I routinely add to any blog on which code is published.
Resources
- SyntaxHighlighter Evolved WordPress Plugin
- SyntaxHighlighter JavaScript package by Alex Garbatchev
- Paste As Visual Studio Code @ Windows Live Gallery