Chris Kempson

Blogging With Nanoc3 Blog Starter Kit

I’ve recently started blogging again as previously mentioned. I wiped the slate clean and started again. This time moving from my own PHP based CMS to nanoc. nanoc (must be spelt with a lowercase “n” for some reason) is a nice little tool for building static (flat HTML) websites. If you thought that flat HTML was a thing of the past, think again! As of recent times it’s quite the fashionable thing for reasons such as speed (static content so no code to run, just grab a file a send it to the browser) and security (try to exploit an HTML page!). nanoc helps you build these flat pages by compiling them ready to send to your web server.

Instead of reinvent the wheel I decided to use a nanoc3 Blog Starter Kit. This handy kit is a pre-made template with a few nice customisations (tagging, preconfigured to use Sass and Haml, easy article creation) to get you up and blogging with nanoc as fast as possible. Both of these softwares together are great and just what I was looking for when wishing to replace my own PHP based CMS. As also previously mentioned I’m trying to learn Ruby and that’s what nanoc is written in. I had hoped that actually using something written in Ruby would help me learn it and that seems to be the case as I can’t help but tweak my blog being the of a tinkering nature.

Straight out of the box there are a few tweaks that I feel need to be made to the nanoc3 Blog Starter Kit.

  • It renders XHTML instead of HTML5
  • It uses underscores instead of dashes to separate words in URIs (Mr Google says use the dash)
  • The tagging system doesn’t even use underscores or dashes but validation-breaking spaces (words fail me…)
  • There is no syntax highlighting for code which of course is a must for all good geeks.

Let’s see how we can go about fixing these issues and get back to some blogging.

Rending HTML5

The stater kit uses Haml to render HTML and making Haml render HTML5 is super easy.

At the very bottom of your Rules file add :format => :html5 to your layout line:

1
 layout '*', :haml, :format => :html5

Swapping underscores for dashes

For some bizarre reason the starter kit uses underscores instead of dashes though I thought the “underscores vs dashes” debate was dead? Anyway change the following code inside the route_path function of helpers.rb by swapping the dashes for underscores. For example:

1
2
3
 if url.include?('_')
      url = url.split('_').join('/')
  end

Finally open the Rakefile file and change the calc_path function so it looks like this:

1
2
3
4
5
6
 def calc_path(title)
    year, month_day = @ymd.split('-', 2)
    path = "content/" + year + "/"
    filename = month_day + "_" + title.parameterize('-') + ".md"
    [path, filename, path + filename]
  end

Removing spaces from tags

Hopefully you have a decent editor or tool you can use to do a mass (sort of, four matches) find replace on all occurrences of /tags/#{tag} replacing them with /tags/#{tag.gsub(' ', '-').downcase}.

Syntax Highlighting for Code

There are quite a few ways of doing this, for me I wanted to solve it using CodeRay (which comes bundled with Nanoc3) and a filter so that I could wrap code in <pre class="LANGUAGE">CODE<pre> and have it highlighted for me.

You’ll need to create a filter, I called mine code.rb and placed it in the lib directory. The contents of code.rb are as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
 require 'coderay'
  require 'htmlentities'

  class CodeFilter < Nanoc3::Filter
      identifier :code
      type :text

      def run(content, params={})
          regex = %r{(&lt;pre class="(\w+)">(.+?)&lt;/pre&gt;)}m

          while content =~ regex
              original, language, code = $1, $2, $3

              if code
                  # Convert tabs to spaces
                  code.gsub!("\t", ' ')

                  # Convert HTML entities
                  coder = HTMLEntities.new
                  code = coder.decode(code)

                  content.gsub!(
                      original,
                      '&lt;pre&gt;' + CodeRay.scan(code, language).html + '&lt;/pre&gt;'
                  )
              end
          end
          content
      end
  end

Next in the Rules file add filter :code to the if statement that deals with formatting markdown. For example:

1
2
3
4
5
 elsif ext == 'md' || ext == 'markdown'
      filter :code
    filter :erb
    filter :rdiscount
  else

Finally add your own CSS to your style.sass file. You could use one of CodeRay’s themes but then CodeRay will spit out inline CSS which I’m not too keen on. Instead I inspected the HTML of some code and added CSS for the span classes. For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
  code, pre
      .pd, .r
          color: #A78BAF       /* Purple */
      .dl, .k
          color: #939E5B       /* Green */
      .lv, .ch, .co
          color: #CC6764       /* Red */
      .i
          color: #CD9260       /* Orange */
      .fu, .cl, .sy, .gv
          color: #718EA7       /* Blue */
      .c
          color: #9C9C9C       /* Light Grey */

That’s all the tweaks I have for now but if I find out anything interesting on my travels I’ll blog about it. For now, enjoy blogging with nanoc!