Sunday, September 5, 2010

Syntax Highlighting in Your Blog

This article describes about how syntaxHighlighter javascript can help you to add code snippets to your blog and how wro4j can help you with it.

There are plenty of sites which helps you to start bloging. But when your blog posts contains some code, suddenly you are not sure anymore which suites you better. Some of them accepts markdown markup language, which allows you to insert code easily without bothering about formatting. Unfortunately markdown has its own disadvantages. For instance,  its hard to define code boundaries or if you want to add xml code, you have to manually escape it. That can be annoying and time consuming.

While searching for an alternative, I have found a javascript widget which solves my problem. It is called SyntaxHighlighter was developed by Alex Gorbatchev and it fits perfectly for my needs. It is very easy to install and it doesn't have the problems I had with markdown.

Below is the example of how the markdown syntax looks like: And this is the example of syntaxHighlighter usage:
For more examples, visit documentation about syntax highlighter installation.
Syntax Highlighter is a great javascript widget, but in order to support formatting for different languages, you have to include a lot of js & css resources. For each language, syntaxHighighter with a dedicated javascript file of the following format: shBrush<language>.js (ex: shBrushJava.js). That means that if you want to support formatting for 10 different programming languages, you have to include more than 10 resources (besides those). This can damage your blog page loading performance. And this is why I decided to use wro4j to fix this problem.

Wro4j maven plugin seemed to be a natural choice to solve this use-case. I have downloaded the syntaxHighlighter distribution and added it to wro4j-examples project which has the maven infrastracture ready. You can checkout the wro4j code from github and play yourself with it.

The first step was to create the configuration file which describes how to group the resources into the bundles:


The next step is to configure pom.xml of the project and instruct it to use wro4j maven plugin

Replace the ${wro4j.version} placeholder with actual wro4j version.
This is the simplest way to make it work. The wro4j maven plugin is very easy to configure, so that instead of default js & css compressor we could use others, like YUI or Google closure compressors. This can be done this way:

If you want to use google closure compressor, use the following value for wroManagerFactory configuration: ro.isdc.wro.extensions.manager.standalone.GoogleStandaloneManagerFactory
In order to run it, we have two options:
1) As a part of the build process of the project. (run mvn install command)
2) Explicitly run wro4j maven plugin: mvn wro4j:run

As a result, you should see the groups bundled under the target/wro folder (the destination folder is also configurable)

To make the resources public available, these resources were copied to google code repository, under the following path:
1) http://wro4j.googlecode.com/svn/wiki/static/syntaxHighlighter/3.0.83/syntaxHighlighter.js
2) http://wro4j.googlecode.com/svn/wiki/static/syntaxHighlighter/3.0.83/syntaxHighlighter.css

One small note regarding the committing these resources to google code repository: by defualt the files commited with svn client have text/plain mime type. This could cause a problem if you expect a different mime type. If you need a different mime type, you have to specify it with your preferred svn client by adding svn:mime-type property with expected value (ex: text/css). Thus, when you will include this resource into your page, it will be served with correct content type in response header.

The installation of the syntaxHighlighter javascript widget is trivial. Just add the resource to the head of the blog template:

    <script src='http://wro4j.googlecode.com/svn/wiki/static/syntaxHighlighter/3.0.83/syntaxHighlighter.js' type='text/javascript' />
    <link href='http://wro4j.googlecode.com/svn/wiki/static/syntaxHighlighter/3.0.83/syntaxHighlighter.css' rel='stylesheet' type='text/css' />