Blog Syntax Highlighting

Overview

Ok a quick post on how to do Syntax Highlighting on a Nanoc Blog, like this Blog even.

Knowing that I’ll be writing about tech stuff here means that at some stage I’ll be including code samples, so I thought I might as well figure it out now. Then I might as well write a post about it, so I’ve got an example of using pretty code samples.

The Plan

Looking around I found Highlight.Js … its pretty simple, I kinda like that it just processes over code blocks in the browser, rather than figuring out things at the compile stage of Nanoc. All this requires is getting some code into a <pre><code class='language-blah'></code>/<pre> section, then adding highlight js to the page and initialising it.

How To

Firstly, how do I output code blocks like that? … Well in Markdown it’s just indenting a block by four spaces

Secondly, how do I get the correct class name there? … Well, I then look more under the hood and see that in Nanoc I’m actually using kramdown, and kramdown has this concept of Inline Attribute Lists which is good, so I can add classes, and looking more I see that kramdown also has an additional syntax for code blocks, Fenced Code Blocks which looks easier to write, as well as having its own way of specifying the language being used.

Easy so lets try it out … Hang on, I’m getting what looks like syntax highlighting as soon I put in a code block with a language specified, looking deeper it seem like it’s being formatted with CodeRay … I don’t ike this … not that I’ve got anything against CodeRay, I just don’t like something happening that I don’t understand, so like a dog with a bone, I need to figure out how this could be.

Now this is where I got stumped for a while (I’m not going to say how long, it was embarrassing) as none of the Nanoc docs mentioned that this would happen, the docs talk about there being a CodeRay filter that could be applied, but I didn’t have that anywhere. After a while I found in the kramdown docs that CodeRay can be output as part of kramdown, and after more digging found that it was enabled by default. So how to disable it? Well more digging around other stuff led me to this post ah, so thats easy ….

compile '/posts/*' do
  filter :erb
  filter :kramdown, :enable_coderay=> false
  layout 'post'
end

So now I have it I can add code to my page with something as simple as (gaa a code block example in a code block) …

    public static void main(String... args) {
        System.out.println("Space Monkey");
    }
{: .java}

or

~~~ java
public static void main(String... args) {
    System.out.println("Space Monkey");
}
~~~

Results

So real examples …

public static void main(String... args) {
    System.out.println("This is obviously Java");
}
alert("and I'm Javascript");
puts 'And a little bit of Ruby'

Well this took me longer to do that planned, that said, these tools are new to me so maybe in a few weeks or months, I would have solved this much quicker.

Maybe kramdown added syntax highlighting as on by default recently? hence no mention of it on the Nanoc site … thats just life when using open source, you have to accept that the way tools combine might change over time and you can’t expect that every project updates its docs to reflect changes in other projects … Its what we sign up for when we get all of this great technology for free.

Next Steps

In the interests of time, I’ve taken a shortcut and added highlighting to every page on the site, just by adding it to my default layout file. I could make it so that only posts are highlighted, and then so that only posts that have code are highlighted.

Comments

comments powered by Disqus