Blogging with Nanoc

Last time we talked about the structure of a nanoc project. Today I would like to introduce nanoc as a simple blogging engine. Let’s get started.

For a simple blog we need an index page with a list of current articles. Old articles should be displayed on the archive page. Additional features like RSS feed or comments will be added in the last part of this series.

Articles

Firstly we create a hello world post. Go to the content directory and create a new folder posts. This is the place where our posts are going to be stored.

We are going to use kramdown syntax. Kramdown is a superset of Markdown for ruby. It is an easy to read markup language that allows you to focus on the content.

Create a file 2013-05-22-hello-world.md with the following content.

---
title: Hello World
created_at: 2013-05-22 01:00:00 +0100
description: Hello World article
kind: article
tags: [Greeting, Salutation]
---

This is out first **Hello World** blog post!

The first lines are the post’s metadata. The kind: article is very important parameter. It tells nanoc to treat this content as a post. Below the metadata the content of the post is written in markdown format.

Now we edit some settings in the Rules file.

compile 'posts/*' do
    filter :kramdown
    layout 'post'
end

This compile rule ensures that kramdown filter is applied and the layout called post is used. We haven’t created the layout yet but we are going to do it soon. Remember that the ordering matters. The most general rules should be placed last.

Let’s play with the nice and clean URL routing. Again edit the Rules file.

route '/posts/*' do
    y,m,d,slug = /([0-9]+)\-([0-9]+)\-([0-9]+)\-([^\/]+)/
        .match(item.identifier).captures

    "/#{y}/#{m}/#{d}/#{slug}/index.html"
end

This piece of a scary regular expression ensures that the URL of the blog post is in year\month\day\post title format. Pretty neat.

We created our first article. It uses layout called post so let’s create one.

Layout

From the previous part of the series you know how to create a simple default layout. Let’s reuse it and add the one for the posts. Last time we created file called default.erb inside the layout directory. It was a really simple file and looked like this.

<html>
<head>
    <title>Hello World</title>
</head>
<body>
    <%= yield =>
</body>
</html>

Next step is to create a file post.erb and inherit from the default layout.

<% render "default" do %>
    <div class="post">
        <h1><%= item[:title] %></h1>
        <article>
            <%= yield %>
        </article>
    </div>
<% end %>

The code above prints a title of the article and it’s content.

Index Page

The layout and the first article are ready. Now we have to display the article on the index page. We start with adding nanoc blogging extensions to the project. Edit the file default.rb in the lib folder and add these lines.

include Nanoc3::Helpers::Blogging
include Nanoc3::Helpers::Tagging
include Nanoc3::Helpers::Rendering
include Nanoc3::Helpers::LinkTo

Now let’s create an index.erb in the content directory with the following content.

---
title: The most awesome article!
---

<% sorted_articles[0, 3].each do |post| %>
    <div class="post-list">
        <h2><%= link_to post[:title], post.path %></h2>
        <aside>Posted at: <%= post[:created_at] %></aside>
        <article>
            <%= post.compiled_content %>
        </article>
    </div>
<% end %>
<p><a href="/archive">&larr; Archive</a></p>

The first line of the ruby code is responsible for finding the first three articles sorted by date. After that it prints post’s title displayed as a link and it’s creation date. In this example the whole content of the post is displayed on the page.

Conclusion

Creating a simple blog with nanoc is very easy. If you followed the steps in this article you should have a solid basics to build a great site with all of the advantages of the static generation.

In the last post of this series we are going to enhance this simple engine with more advanced features that are going to make it even more awesome.