Sunday, October 12, 2008

Blogger Syntax Highlighting

Since I intend to post code snippets here, I guess I had better figure out how to format code nicely in my blog. I am using Blogger, and from what I can tell in my vast 2 hours of Blogger experience, they don't have any simple built-in way to do nice code formatting and syntax highlighting.

I found a lot of references on how to use the very cool SyntaxHighlighter. Check out blogs on this topic from developertips and IdeaMonk -- that stuff helped a lot.

However, I think since these posts, the javascript code they describe to fix Blogger-specific issues with automatically-inserted <br/> tags has been rolled into the SyntaxHighlighter code, or is otherwise no longer necessary. Including it seems to break the formatting on my blog -- it was removing too many line breaks and putting all my code on one line. I didn't really dig into why that was the case. I just noticed that by removing the extra javascript code and adding the BloggerMode() call, everything worked out nicely.

So...here's a step-by-step walk-through of what I did to get this working:

Step 1: Get SyntaxHighlighter

  • Download the latest version of SyntaxHighlighter (1.5.1 as of this writing).
  • Uncompress the RAR file (download WinRar if necessary).
  • Place the contents of the scripts and styles directories onto a web server that can serve these files for your blog (more on that later). I put these files all in a flat directory structure in my example.

Step 2: Add SyntaxHighlighter to your template

On Blogger, go to Layout->Edit HTML and add the following code to your template, just before the </head> closing tag:


<link href="http://[YOURSITE]/SyntaxHighlighter.css" rel="stylesheet" type="text/css"/>
<script src="http://[YOURSITE]/shCore.js" type="text/javascript"/>
<script src="http://[YOURSITE]/shBrushCpp.js" type="text/javascript"/>
<script src="http://[YOURSITE]/shBrushCSharp.js" type="text/javascript"/>
<script src="http://[YOURSITE]/shBrushCss.js" type="text/javascript"/>
<script src="http://[YOURSITE]/shBrushDelphi.js" type="text/javascript"/>
<script src="http://[YOURSITE]/shBrushJava.js" type="text/javascript"/>
<script src="http://[YOURSITE]/shBrushJScript.js" type="text/javascript"/>
<script src="http://[YOURSITE]/shBrushPhp.js" type="text/javascript"/>
<script src="http://[YOURSITE]/shBrushPython.js" type="text/javascript"/>
<script src="http://[YOURSITE]/shBrushRuby.js" type="text/javascript"/>
<script src="http://[YOURSITE]/shBrushSql.js" type="text/javascript"/>
<script src="http://[YOURSITE]/shBrushVb.js" type="text/javascript"/>
<script src="http://[YOURSITE]/shBrushXml.js" type="text/javascript"/>


(You can delete the lines for languages you aren't going to use.)

Then, at the bottom of your template, just before the </body> closing tag, add the following code:


<script type="text/javascript">
//<![CDATA[
dp.SyntaxHighlighter.ClipboardSwf = "http://[YOURSITE]/clipboard.swf";
dp.SyntaxHighlighter.BloggerMode();
dp.SyntaxHighlighter.HighlightAll("code");
//]]>
</script>



Step 3: Markup your code snippets

Anywhere you want to stick a piece of code in your blog, put code like:


<pre name="code" class="ruby">
class Foo
def bar
puts "foo bar"
end
end
</pre>


That should give you something that looks like:


class Foo
def bar
puts "foo bar"
end
end


The name of the class you use specifies what language to format the code as, and directly corresponds to the names of those javascript files you included in your template.

What if I don't have a web server for these files?

Unfortunately, as far as I can tell, Blogger doesn't provide any static file storage that you can use to serve up these files. (It sure would be nice if they had them already installed somewhere we could all pull them from.) For a quick-and-dirty, free solution that I am not really happy with, try Google Sites. There is one catch: they don't let you store .js files. Here's what I did with Google Sites:
  • Create a new account and a new site.
  • Once you're in, create a new page called "SyntaxHighlighter", that is a "File Cabinet".
  • Rename all the .js files to end in .sj instead.
  • Update the .css file and all the .sj files to this new file cabinet.
  • Modify all the code in your Blogger template that points to these .js files to end in .sj.
  • From the Google Sites file cabinet, copy the link location to one of the files and use the relevant part of that to fix up all the css and js links in your template.
The main caveat to this approach is that it seems to be really slow. I am using the nice friendly URLs to the files on Google Sites, which all end up using HTTP redirects. It's less than ideal, but it's also quick to setup and free. Once you like the way this stuff works on your blog, you can probably find a better place to host those css and js files.

Caveats


I still have a couple issues that I didn't spend any time figuring out yet:

  • I think if you go back and forth between "Edit Html" mode and "Compose" mode, you may get extra <br/> tags inserted into your code.
  • This seemed to mess up the drag-n-drop layout editor. As far as I can tell, it only messed up the placement of the gadgets in the layout editor, but not the actual functionality, and the gadgets still appear on the blog posts in the correct place.
  • The SyntaxHighlighter, or at least the way I added it to my template, seems to break on IE6. It's way too late to care about IE6 users. Those people don't deserve to suck any more time from web developers than they already have.
  • Shit. I just found out it's broken on Safari too. Looks like its "too many redirects" for the ".sj" files. I am thinking that hosting these files on Google Sites is not such a good idea...

No comments: