jQuery Syntax Highlighter provides an elegant and simplistic interface for using Google's Prettify with jQuery. We also add a series of features that aren't possible just using Prettify, to ensure that you get the best experience possible:
code
and pre
elements for SEO and semantic relevance!
Note! Currently Internet Explorer 6-8 have an issue with rendering new lines on code elements, until a fix is found please use pre
elements instead.
So let's walk through it.
If your page already has jQuery included then you can skip this step.
<!-- Include jQuery (Syntax Highlighter Requirement) --> <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>
<!-- Include jQuery Syntax Highlighter --> <script type="text/javascript" src="http://balupton.github.com/jquery-syntaxhighlighter/scripts/jquery.syntaxhighlighter.min.js"></script>
<!-- Initialise jQuery Syntax Highlighter --> <script type="text/javascript">$.SyntaxHighlighter.init();</script>
And that's all there is to it in regards to installation. You don't actually have to download anything! now that is neat. Alternatively you could use a local copy of jQuery Syntax Highlighter instead of the CDN copy, but we'll leave that to you. So moving on, how do we let Syntax Highlighter know that we want to highlight our code block?
So you have you standard code block of let's say javascript code, which looks like this:
The following code block is what I would like to syntax highlight: <pre> // Define our Function function checkMeaningOfLife ( decimal, success ) { if ( parseInt(decimal,10) === 42 ) { window.console.log(success); } }; // Define our Variables var str = 'The meaning of life is true', decimal = 42.00; // Fire our Function checkMeaningOfLife(decimal,success); </pre>
And we want to highlight it. We can do this two ways. One is letting the Syntax Highlighter auto-detect which language you are using, the other is a more SEO friendly approach where we explicitly specify which language we want to use.
To highlight our code and auto-detect the language, we would simply add the classname highlight
to our code block. This will look like so:
The following code block is what I would like to syntax highlight: <pre class="highlight"> // Define our Function function checkMeaningOfLife ( decimal, success ) { if ( parseInt(decimal,10) === 42 ) { window.console.log(success); } }; // Define our Variables var str = 'The meaning of life is true', decimal = 42.00; // Fire our Function checkMeaningOfLife(decimal,success); </pre>
We can also highlight our code by specifying the language used explicitly. This is good in case we don't trust the auto-detection script or if we would like some SEO benefits by being more semantic (explicit with our markup). To do this we would simply add the classname language-javascript
to our code block, where the text javascript
is the name of the language we are using. This will look like so:
The following code block is what I would like to syntax highlight: <pre class="language-javascript"> // Define our Function function checkMeaningOfLife ( decimal, success ) { if ( parseInt(decimal,10) === 42 ) { window.console.log(success); } }; // Define our Variables var str = 'The meaning of life is true', decimal = 42.00; // Fire our Function checkMeaningOfLife(decimal,success); </pre>
Sweet! That was too easy!. But there is one every important thing we have to take note of before we continue. And that is encoding our HTML within code blocks such that it is not actually interpreted by the browser as html! Eeee. So let's read about that.
An extremely important thing with using code blocks is making sure you are encoding your HTML properly within your code blocks.
This is because if you don't your web browser will think it has to run that code, despite it being in a code
or pre
element! Argh! That could really cause problems...
So what we want to do is whenever we want to include code blocks (regardless of whether or not we are wanting to syntax highlight them) we always must remember to encode the HTML entities appropriately!
So we do this by converting all the characters which are <
to <
and all the >
to >
.
So for instance let's look at the following code sample:
<pre class="language-html"> <span> I'm a span element. I hope I've been escaped properly... as otherwise I will be :-( and the browser will be :-O </span> </pre>
Looks good, but this is how we actually code it in our HTML:
<pre class="language-html"> <span> I'm a span element. I hope I've been escaped properly... as otherwise I will be :-( and the browser will be :-O </span> </pre>
Hrmmm. Interesting... But once you've got that nailed, then there really are not worries and you're all good to go. If you are a keen person, you may want also want check out the source code for this demo to gain a better grasp of this issue.
There is also one quite important thing. Internet Explorer 6-8 will struggle displaying newlines using code
elements. This is a known issue and has been documented in various locations with no known fix
1
2
3
. In the meantime please use pre
elements instead of code
elements. You can achieve the same SEO semantic benefits by adding the classname code
to your pre
element like so:
<pre class="code language-html"> <span> I'm a span element. I hope I've been escaped properly... as otherwise I will be :-( and the browser will be :-O </span> </pre>
Great! So that is all there is too it and all you need to know to install and use the Syntax Highlighter. You can quit reading and start working on your project right now, or you could learn a little bit more.
Syntax Highlighter is also ajax friendly. This means we can load in dynamic code blocks into our page which we would like highlighted, and actually highlight them without problem. Let's see how we can do this with the following snippet of javascript code:
var $content = $('<div>This is an upcoming code black:<code class="language-javascript">// I am some code</code></div>'); $content.syntaxHighlight(); // will highlight the code block found inside
If you are using jQuery Sparkle (a Do-Not-Repeat-Yourself jQuery Framework aimed at simplifying your development with powerful tools) then calling $content.sparkle()
will also call $content.syntaxHighlight()
automatically for us.
If anything isn't working the way you want it to, or if you would like to request a feature or provide praise or general feedback then be sure to click the feedback button to the right, or the "Get Support" link up the top of this page.
This work is powered by coffee and distributed for free. Donations are how we afford our coffee. Coffee is how we stay awake after our day job hours to work on things like this free open-source project which you're looking at. So go ahead, and get that warm fuzzy feeling knowing you just helped some poor fellow working after hours for free to buy his coffee. You only need to spare a few dollars, or as much as you feel this piece of work is worth. Thanks so much. Alternatively; if you are not in a donating mood, then spreading the word about this project on twitter, your blog, or whatever is just as good. You can also give praise by clicking the feedback button or visiting our "Get Support" link. Thanks a bunch, we appreciate the help deeply.
This work is licensed under a GNU Affero General Public License.