Google SyntaxHighlighter is a simple tool that allows bloggers to easily display code
in a format that is familiar end users. The tool renders the code in a very consumable
fashion that includes colored syntax highlighting, line highlighting, and line numbers.
/*
This is an example of how Google
SyntaxHighlighter can highlight and display syntax
to you, the end user
*/
public void HelloWorld()
{
// I have some comments
Console.WriteLine("Hello, World!");
}
It is purely a client-side tool, as all of the processing is done strictly within
the browser through JavaScript. There is no server-side processing. Since it is all
JavaScript, you don't need special Copy/Paste plugins and macros installed to your
favorite IDE or your blog authoring tool. (I am leery of random plugins and installing
them into the software that I use to feed my family.) To including code in your blog
post, copy your code from Visual Studio, Notepad, Flash, Firebug, or any tool that
displays text, and paste it in to your post. As of v1.5.1, Google SyntaxHighlighter
supports C, C++, C#, CSS, Delphi, HTML, Java, JavaScript, PHP, Pascal, Python, Ruby,
SQL, VB, VB.NET, XML, XSLT, and all of this is just what comes out of the box.
Setting Up SyntaxHighlighter
To get SyntaxHighlighter running on your blog, download the
latest version of the RAR archive and extract the code. The archive contains a parent
folder, dp.SyntaxHighlighter, with three child folders:
dp.SyntaxHighlighter
\Scripts //Production-ready (Compressed) scripts
\Styles //CSS
\Uncompressed //Human-readable (Uncompressed/Debug) scripts
Once the archive is extracted, upload dp.SyntaxHighlighter to your blog.
Feel free to rename the folder if you like, though I did not. It is not necessary
to upload the Uncompressed folder and its files; they are best used for debugging
or for viewing the code, as the files in the Scripts folder have been compressed
to reduce bandwidth by having most of their whitespace removed.
After you have uploaded the files, you will need to add script and style references
to your site's HTML. This is code is not for your posts, but rather for your blog
template. In DasBlog, I place this code in the <HEAD> block of my homeTemplate.blogtemplate file.
Remember to change the file paths to match the path to where you uploaded the code.
<link type="text/css" rel="stylesheet"
href="dp.SyntaxHighlighter/Styles/SyntaxHighlighter.css"></link>
<script language="javascript" src="dp.SyntaxHighlighter/Scripts/shCore.js"></script>
<script language="javascript" src="dp.SyntaxHighlighter/Scripts/shBrushCSharp.js"></script>
<script language="javascript" src="dp.SyntaxHighlighter/Scripts/shBrushXml.js"></script>
<script language="javascript">
window.onload = function () {
dp.SyntaxHighlighter.ClipboardSwf = 'dp.SyntaxHighlighter/Scripts/clipboard.swf';
dp.SyntaxHighlighter.HighlightAll('code');
}
</script>
To make the tool most efficient, including minimizing the code download by the client
browser, highlighting is only enabled for the languages that you specify. The highlighting
rules for each language is available through a file referred to as a Brush. The code
sample above enables only C# and XML/HTML by including the core file, shCore.js,
the C# brush, shBrushCSharp.js and the XML/HTML brush, shBrushXml.js.
A unique brush file is available for each of the supported languages, and only the
core file is required. These brushes are located in your Scripts directory
(the human-readable version is in the Uncompressed folder). Include only
the brushes that you like; if you forgot a language brush, the code will still display
on your page, but as unformatted text.
<!-- Unformatted HTML Code / No Brush -->
<p id="greeting">Hi, mom & dad!</p>
<!-- Formatted HTML Code -->
<p id="greeting">Hi, mom & dad!</p>
Making SyntaxHighlighter Go
Now that the application is deployed to the site, how does it get applied to a post?
Paste the code into the HTML view of your post, inside of a <PRE> tag. Create
a name attribute on your tag with a value of code, and a class attribute
set to the language and options you are using.
<pre name="code" class="c-sharp">
public void HelloWorld()
{
Console.WriteLine("Hello, World!");
}
</pre>
One catch is the code must be first made HTML-safe. All angle-brackets, <tag>,
must be converted to their HTML equivalent, <tag>, as well
as ampersands, & to &. I also find it helpful if your
code-indentation uses two-spaces, rather than tabs.
<!-- Pre-converted code -->
<p>Hi, mom & dad!</p>
<!-- Converted code -->
<pre name="code" class="html">
<p>Hi, mom & dad!</p>
</pre>
The class attribute is made up of both language and option aliases. These
aliases consist of one language followed by your desired options, all in a colon delimited
list.
class="language[:option[:option[:option]]]"
The value of language is any of SyntaxHighlighter's defined language aliases, such
as c#, csharp, or c-sharp for C#, or rb, ruby, rails,
or ror for Ruby. See: full
list of available languages.
Options allow for such things as turning off the plain text / copy / about controls
(nocontrols), turning off the line number gutter (nogutter), or
specifying the number of the first line (firstline[n]). A JavaScript code
block with no controls header, and starting the line numbering at 34 would have a class attribute
value of class="js:nocontrols:linenumber[34]". See: full
list of available options.
Extending SyntaxHighlighter
Because Google SyntaxHighlighter is entirely in JavaScript, you have access to all
of the code. Edit it however you like to suit your needs. Additionally, brushes are
very easy to create, and include little more than a list of a highlighted language's
keywords in a string and an array of language aliases. Creating a brush for ActionScript
or QBasic would not take much time. Language brushes exist in the wild for Perl, DOS
Batch, and ColdFusion.
In a future post I plan on discussing Brush Creation in depth through creating a brush
for ActionScript.
Comparing SyntaxHighlighter to Others
I am a fan of this tool, though that should be obvious considering it is what I use
on this blog. I like how readable the code is, how extendable it is, and how easy
it is to use. I don't like its compatibility--or lack thereof--with RSS; since all
of the work is done in JavaScript, and RSS doesn't do JavaScript, there is no syntax
highlighting, numbers, or options within a feed, though the code formatting is still
maintained. Other tools, like the CopySourceAsHtml plugin
for Visual Studio or Insert
Code Snippet for Windows Live Writer convert your code into formatted HTML,
where all of the syntax highlighting is applied through HTML attributes and embedded
CSS. Their methods are much easier than SyntaxHighlighter, since there are no stylesheets
or JavaScript files to include in your HTML, and you don't have to worry about making
your code HTML-safe. Also, their method works in RSS feeds. However, there isn't the
same level of control. Through SyntaxHighlighter's extendibility, I can theme my code
views, such as if I wanted them to look like my personal Visual Studio theme. Through
SyntaxHighlighter, I can also make changes at a later time, and those changes will
immediately reflected in all past posts, whereas making modifications to the HTML/embedded
CSS pattern is much more difficult.
Final Thoughts
I like CopySourceAsHtml in Visual Studio. I used it for years on this blog. But I
code in more languages than VB.Net or C#, and the plugin isn't available within the
Flash or LoadRunner IDE. I was also frustrated with pasting my code in, only to find
that it was too wide for my blog theme's margins, and would have to go back to Visual
Studio, change my line endings, and repeat the process. I'm sticking with Google SyntaxHighlighter.
It works for all of my languages (as soon as I finish writing my ActionScript brush),
and when my line endings are too long, I simply change my HTML. And in my HTML, my
code still looks like code, rather than a mess of embedded style. I have to sacrifice
RSS formatting, but as a presentation developer that is very particular about his
HTML, I am glad for the customization and control.
