During the redesign of this blog I needed to decide how I was going to display any code snippets in my posts. There are few different ways of achieving this as I’m sure you’ve noticed on your travels around the web so I was mainly searching for the right tool for the job.
Code snippets come in all shapes and sizes, some do very little to what is in the pre or code tags, some glitz it up and some pop windows up when you interact with them. Some approaches I like, others I don’t. For example, I’m not really a fan of code snippets that have line numbers. They are fine if you are explaining the code by referring to sections by line number but sometimes it seems unnecessary. It is particularly irritating if the line numbers interfere with copying and pasting.
As a reader, my primary aim is to learn. Usually done through a combination of reading explanations, reviewing examples and experimenting with those examples. Doing so is made more difficult when line numbers interfere. Admittedly it isn’t made too difficult but it is made more difficult than it should be.
Some sites offer an alternative approach to copying the code, such as having a button which copies it to the clipboard but that’s not what people expect. People are used to selecting text and copying it that way, why change it. Familiarity is a useful thing if you use it correctly.
Anyway enough of my whinging, my key requirements were for it to be aesthetically pleasing, easy to read and follow (irrespective of the quality of my code) and easy to copy if desired.
Seen as this blog is built using WordPress the logical choice seemed to be to use a WordPress plugin. Highly recommended was the CodeColorer plugin, written by Dmytro Shteflyuk. It is easy to install – it’s just a plugin after all – and it is highly customisable. However on the negative it does display line numbers, non interfering line numbers though. Despite that I thought I would use it for a while to see how I got on with it. I was using it like so:
[cc lang="php" tab_size="2" lines="40"]
// some code
[/cc]
In the end I decided it wasn’t for me. It is pretty big and I thought it was a bit bloated for what I needed it for. For example the CSS file alone was 210 lines long.
The next thing I tried is what I’ve ended up using. It is Google’s Code Prettify js library. It is simple to use, it only requires 2 files and supports a large number of languages. To set it up all I needed to do was add the javascript library file and the accompanying CSS file to either of my theme’s header.php or footer.php files.
It’s also nice and lightweight, for example the CSS file is less than 50 lines long and is very easy to comprehend and start editing. It has one main style declaration that you can change, pre.prettyprint, and then rules, that mainly set colours, for each of the different types of words a language uses, such as keywords and comments. This makes it very easy to create your own theme for your code snippets. To use it all I need to do is the following:
<pre class="prettyprint html">
// some example code
</pre>
There are other approaches that one can use depending on your use case but no other approach suited my needs. An example of a different approach is embedding content directly from another website or service, such as Github. This is an approach used by the folks that created Lawnchair and is very useful if you will always be showing completed, useful snippets. That wasn’t what I was looking for for this project so it made little sense for me to do it that way.
All in all I’m pretty pleased with what I’ve learnt and where I’ve ended up.