This blog is designed to fix that in two ways:
1) I'll write a summary of what I've learned, including code samples, that I can easily refer back to at a later date.
2) The act of writing down the summary should further cement the concept in my brain, and maybe I won't forget it in the first place.
SyntaxHighlighter
That said, my first task I'll be writing about is setting up Blogger / Blogspot for code snippets and syntax highlighting. For this purpose, I chose to use SyntaxHighlighter, which is a JavaScript solution created by Alex Gorbatchev. There are other options out there, but SyntaxHighlighter is popular and easy to use. Some blog sites even include SyntaxHighlighter as a built-in option. Let's see what it takes to get set up with a simple SyntaxHighlighter tutorial.
Setup
First, you need to decide if you want to host the SyntaxHighlighter files yourself, or simply link to the hosted version on the creator's website. For Blogger, we can't upload JavaScript files (as far as I know), so we'll be linking to the hosted files. If you want to host the files yourself, simply download them and replace the URLs below with relative URLs to your file location.
Now, we need to set the page up for SyntaxHighlighter. We need to add a bit of code to the <body> section of our HTML (I suggest adding it right before the </body> closing tag):
<link href='http://alexgorbatchev.com/pub/sh/current/styles/shCore.css' rel='stylesheet' type='text/css'/>
<link href='http://alexgorbatchev.com/pub/sh/current/styles/shThemeDefault.css' rel='stylesheet' type='text/css'/>
<script src="http://alexgorbatchev.com/pub/sh/current/scripts/shCore.js" type="text/javascript"></script>
<script src="http://alexgorbatchev.com/pub/sh/current/scripts/shAutoloader.js" type="text/javascript"></script>
<script type="text/javascript">
//<![CDATA[
function path()
{
var args = arguments,
result = []
;
for(var i = 0; i < args.length; i++)
result.push(args[i].replace('@', 'http://alexgorbatchev.com/pub/sh/current/scripts/'));
return result
};
SyntaxHighlighter.autoloader.apply(null, path(
'applescript @shBrushAppleScript.js',
'actionscript3 as3 @shBrushAS3.js',
'bash shell @shBrushBash.js',
'coldfusion cf @shBrushColdFusion.js',
'cpp c @shBrushCpp.js',
'c# c-sharp csharp @shBrushCSharp.js',
'css @shBrushCss.js',
'delphi pascal @shBrushDelphi.js',
'diff patch pas @shBrushDiff.js',
'erl erlang @shBrushErlang.js',
'groovy @shBrushGroovy.js',
'java @shBrushJava.js',
'jfx javafx @shBrushJavaFX.js',
'js jscript javascript @shBrushJScript.js',
'perl pl @shBrushPerl.js',
'php @shBrushPhp.js',
'text plain @shBrushPlain.js',
'py python @shBrushPython.js',
'ruby rails ror rb @shBrushRuby.js',
'sass scss @shBrushSass.js',
'scala @shBrushScala.js',
'sql @shBrushSql.js',
'vb vbnet @shBrushVb.js',
'xml xhtml xslt html @shBrushXml.js'
));
SyntaxHighlighter.config.bloggerMode = true;
SyntaxHighlighter.all();
//]]>
</script>
That uses the autoloader feature of SyntaxHighlighter 3. It will always load two core CSS files, the core javascript file, and the autoloader script, but it will only load specific brush scripts if the corresponding code language is used on the current site. If you opt for SyntaxHighlighter 2, you'll have load brushes even on pages that don't need them.
You'll also notice that bloggerMode is set to true. This is only necessary on Blogger and defaults to false for use on other sites.
Samples
Now you can start adding code snippets to your website. For example, to add the following C# code snippet:
public HelloWorld()
{
Console.WriteLine("Hello, World!");
this.Name = "blah";
}
Add the following to your HTML using the <pre> tag:
<pre class="brush: csharp; toolbar: false">
public HelloWorld()
{
Console.WriteLine("Hello, World!");
}
</pre>
Or add the following code to your HTML using the <script> tag:
In both methods, the "class=" parameter tells SyntaxHighlighter which language to expect. You can also add other options here as described on SyntaxHighlighter's configuration page.
There are some differences between the two methods though. With the <pre> method, any HTML entities need to be encoded properly (e.g. '<' becomes '<'). This means that in order to show the following HTML snippet:
<body> <p>Hello, World!</p> </body>
You need to have the following in your HTML file:
<pre class="brush: html; toolbar: false"> <body> <p>Hello, World!</p> </body> </pre>
The easiest way to convert your code samples is to use Quick Escape. This site allows you to paste in text and it then properly encodes any HTML entities for you to copy back to your website.
If you choose to use the <script> tag, you don't need to worry about HTML entities (the CDATA bit takes care of that), but there are some other downsides. The main issue is that the code in the <script> tag will get stripped out by some browsers or RSS readers. This includes the "Compose" feature of Blogger's post editor.
The <pre> tag will still format a bit like code even when <script> tags are removed or SyntaxHighlighter isn't working. Here's the C# sample with just the <pre> tag but no SyntaxHighlighter:
public HelloWorld()
{
Console.WriteLine("Hello, World!");
}
You may have noticed that all of SyntaxHighlighter samples have line numbers except for the first. That's because the newest version of SyntaxHighlighter, 3.x, doesn't handle double-digit line numbers correctly. The solution is to either remove the line numbers all together or use an older version of SyntaxHighlighter. Remember though, if you drop back to SyntaxHighlighter 2.x, you lose the autoloader feature I mentioned earlier.
Optimization
I noticed in Chrome's Web Developer Tools that using the hosted SyntaxHighlighter files causes double requests to be issued to get each file. This is because the public address that SyntaxHighlighter recommends is at http://alexgorbatchev.com/pub/sh/current/, but the actual files reside at http://agorbatchev.typepad.com/pub/sh/3_0_83. Changing to the typepad address cut my page's load time down by about 30% from 1.1s to 0.76s. The downside to using the typepad address is twofold. First, my blog won't automatically be using the newest version when it is released. Second, if the files are ever moved to a new host, the redirection address that you're supposed to use will probably be updated, but the typepad address I'm using will go dead.
Acknowledgements
This post was put together using information from the following sites:
SyntaxHighlighter
Adding a Syntax Highlighter to your Blogger blog
Awesome code syntax highlighting made easy including a comment by "freak"
That's all for now. Please let me know in the comments if this has helped you or if you have further questions.
No comments:
Post a Comment