Code Snippets, Syntax Highlighting, Source examples, Verbatim text, etc...
I'm sure I'm not the only one to need to display nice clean and compatible code snippets, source code examples, and similar stuff. I'm using Typepad as blog engine, but what I'll explain here should work with MovableType as well (as the former is a professional version of the open source latter one).First of all, the needs :
- I need a tool to display code snippets, examples,
- It has to be easy to use,
- It has to be nice
- It should have syntax highlighting and coloring
- It has to support Perl, Javascript, and ruby syntax
- It has to allow download and view as text
- It has to degrade properly, so that it works in RSS clients
The solution is of course SyntaxHighlighter, the well known tool by Alex Gorbatchev. This tool is used widely and some people have already written on including it in Movable Type, or even in Typepad.
But I thought I would write on it as well, because there are some subtleties, and both SyntaxHighlighter and Typepad evolved since these entries were created.
So, if you don't know this too yet, or are too lazy to check its description page, SyntaxHighlighter is a pure JavaScript + CSS tool that finds and renders content, from a specific standard HTML tag you specify.
Example
# Some Perl code
my $var = 42;
my @array = map { reverse }
grep { length }
@strings;
sub my_function {
my ($a, $b) = @_;
return ($a * $b);
}
Download
First of all, you don't want to download SyntaxHighlighter from it "official" google code home, because it's hosted by Google (sorry, just kidding) because only the version 1.5 is available there. What we want is version 2.0, which has more features, and includes a Perl syntax brush by default (so no need to get it from elsewhere).
Download SyntaxHighlighter from this page. I downloaded version 2.1.364 (local copy here in case the site is down)
Upload to your TypePad Account
Next, you need to upload the files to your TypePad File Manager. You'll find it in the Library Tab.
Then create a directory (I created mine as syntaxhighlighter at the root), and upload the following files. This list is the bare minimum to have it working, but you can (you should) add more brushes to support more languages highlighting, and also upload the icons (the .png files). You could as well upload all the languages brushes. And you can also use a different theme (I'll try the Emacs one, as I'm an Emacs addict).
Make sure your upload works by trying to access one of the file (of course replace your real site host name) :
http://YOURSITE.COM/syntaxhighlighter/shCore.js
If you can see or download the file, it means the files are properly uploaded.
Add some magic
For SyntaxHighlighter to work, you need to include some Javascript and CSS to the pages that will contain things you want to highlight. The best is to include it on every pages, as the tool is smart enough to find and apply styling only on what you specify to be highlighted.
Now, how do you add CSS and Javascript to your TypePad blog? There are two cases :
- Either you are using a simple TypePad design
- Or you are using an advanced TypePad design
All blog entries I've seen on this topic only handles the case of advanced design, because it's easier to do. But, people using advanced design don't need a tutorial to include SyntaxHighlighter on their blog, they are, you know, advanced enough to do it on their own... So I thought it would be more useful to describe how to do with a simple design.
With a simple design on TypePad, you don't have access to the templates of the pages, but luckily, you can add a module that allows you to add any HTML code in your page. So the idea is to this module to your design content, and add the needed javascript and CSS reference to it. Here is how you can do it.
- From your TypePad dashboard, go to Design -> Content
- Add a new module, called "Embed your own HTML" (see picture)
- Give it a name (it's not used in the page, it's just to see what this module is here for).
- Be sure that you move the module to be on the lowest part of your blog content (to be loaded last)
The content of the module will be used to load SyntaxHighlighter. Here is what I input in the module :
<!-- Include required JS files -->
<script type="text/javascript" src="http://YOURSITE.com
/syntaxhighlighter/shCore.js"></script>
<!-- At least one brush, here we choose Perl.-->
<!-- You need to include a brush for every language you want to highlight -->
<script type="text/javascript" src="http://YOURSITE.com
/syntaxhighlighter/shBrushPerl.js"></script>
<!-- Include *at least* the core style and default theme -->
<!-- You can choose a different theme -->
<link href="http://YOURSITE.com/syntaxhighlighter/shCore.css" rel="stylesheet" type="text/css" />
<link href="http://YOURSITE.com/syntaxhighlighter/shThemeDefault.css" rel="stylesheet" type="text/css" />
<!-- Important options, and finally the main call -->
<script type="text/javascript">
SyntaxHighlighter.config.tagName = "code" // use <code> tags
SyntaxHighlighter.config.stripBrs = true // disregard trailing <br>
SyntaxHighlighter.all()
</script>
The Options
As you can see, there are 2 options set at the end. These options are to make SyntaxHighlighter more compatible with the TypePad graphical editor. By default, SyntaxHighlighter looks for <pre> tags. But these are rebuilt each time you modify an entry in the graphical editor. So one of the option is to be able to use <code> tags, that are left untouched by TypePad. Well, almost untouched, TypePad tends to add <br> tags at the end of line, which is why the seconde option is there.
Include your code snippet in TypePad
Now that everything is setup, all there is to do to have a nice code example into TypePad is to create a new Post, write the text using the "Rich Text" view of the editor. Then when you want to include a code snippet, switch to the "HTML" view, and add this :
<code class="brush: perl"><br>
# Your code example goes here. For instance, some Perl :<br>
my %hash = { foo => 'bar' };<br>
</code>
Which will output on your blog page as :
# Your code example goes here. For instance, some Perl :
my %hash = { foo => 'bar' };
And inside the TypePad graphical editor, this is what you will see. Most of the Atom / RSS feeds client (like Google Reader) will also have it like this :
Which is in my opinion, not too bad !
Conclusion
So here it is : a nice, free and open source syntax highlighter in your TypePad posts, easily included, wich themes, colors, a lot of languages supported, and which degrades nicely for feeds readers. There is more customization possible, I suggest you go look at the SyntaxHighlighter documentation.
I have tried to make this post / tutorial as easy as I possible, but please let me know if you think I should clear ups things, or add more screenshots. If you try to do it on your TypePad account and it works, let me know in the comment. If it doesn't work, I'll try to help.
