Ninja-Style Blogging with toto and Heroku- Part 2

Shameer continues in his quest to use the Toto Blogging engine and Git to create a fast blogging platform on Heroku. In part 1, he showed how to get a basic blogging platform up and running. Now he shows how to customize a Toto template and engine, and edit the engine to have more sophisticated functionality such as tag clouds or related articles.

It was only a few days back I thought to transfer my blog from WordPress to a flat-file blog engine. Flat-file blogs are much faster than any dynamic websites and they are easy to manage. One of my friends introduced me to toto, a Ruby-based blogging engine, which was of great interest to me. It was easy to use and is specially designed to be used with Heroku, the Ruby cloud platform. It was easy to set up toto and publish articles, which I discussed in the first part of this article. However, porting from WordPress to toto was not as easy as I had expected, primarily due to the URL structure of currently published articles, which was not supported by toto gem. Its URLs are also not based on categories or tags, so I decided to hack the toto library and add the missing features.

In this article I will discuss how we can customize a toto template and engine  to add more functionality, and hopefully once you’ve read this article, you’ll have an idea about how toto works. If you don’t like coding, don’t worry, skip the sections of code and fork my custom toto mentioned at the end of this article, and enjoy flat-file blogging. As I have explained the basics of toto in my previous post, I’m not going to go into that again here. If you haven’t read it, then I would suggest you take a look before continuing.

Understanding the config file

In the root of our application you will see a file named, which contains the configurations for our blog. If you open it, you will see something like this:

Most important things that we need to change here are:

As toto doesn’t have inbuilt support for a comment system, it recommends that you use disqus for comments. If you want to use it, add your disqus username here:

Customizing the template

All template files will be placed in template folder. A toto template is an RHTML file which contains a mix of HTML and Ruby code. The main template or layout file, layout.rhtml, defines the layout of the site, which means that content in this file will be shown in all pages. If you want something like a navigation bar or side bar, it can be added in this file.

All other template files will be rendered into the <%= yield %> section. These files are located in the templates/pages directory. The template for the home page, index.rhtml, will by default show up to 3 articles, with a summary of the rest appearing in the archives. You can edit this file to have a nice looking home page with custom contents or listing styles.

Archives are rendered in the archives.rhtml template file. Currently it will show only a title with a link to the article, although you can customize this page to add a summary or to sort them by year and month.

Adding custom pages

It’s obvious that you won’t be happy with the limited set of pages included in the Dorothy template (toto’s default template). You can add a new page by simply adding a template file in templates/pages folder. For example, if you want to have a ‘Contact’ page, just create an HTML file with the required content, name it contact.rhtml, and place it in the templates/pages folder. Now you can access the contact page,

Displaying meta information

If you look at the article page, you’ll see it’s showing only the article title, date, and the content. There is no author name or tags shown. To show tags on the article page, open article.rhtml and add the following code where ever you like:

This will show all tags for that article on the page. There’s no secret behind it, you can show anything from the meta part like this. To show an author’s name, just add the following to the article template:

The problem with this method is that it will throw an error if that meta information is not in the article. Also, we can’t use the above code to show meta data in the index/archives page. For these reasons, you need to write an ‘accessor’ method for meta information in the Article class. You will also need to do some modification in the toto engine. Here is an example to show tags related to an article. For this, first clone toto from github to myblog folder and change the path to the toto engine in

Open and change require ‘toto’ to require ‘./toto/lib/toto.rb’

Before moving on, take a look into the index.rhtml file:

We are looping through a set of objects, of the type Article, which you can see in the toto engine.

To get the tags of an article in array, add the following method to the Article class:

This method will return an array of tags for the article. Note that tags in the article need to be separated with a comma, since we split it with comma in the code above. Now, to show tags in index.rhtml, edit the template and add the following code somewhere inside the loop:

It will now show the tags related to articles in the index page. Also, toto now won’t show any errors if tags do not exist in some articles.

Custom URLs and Routes

Now you can show categories and tags corresponding to an article. But they are all just static and we have not yet given any links to them. Unfortunately toto currently doesn’t support custom URLs and Routes. For this we will need to hack the engine and make some changes. Let’s assume you need to show articles belonging to a particular category/ tag in following URL.

You will need to do a couple of things to achieve this. Firstly, change toto routing to allow these URL formats. Toto routes from the go method of class Site. You can change that function as given below. I haven’t given the entire body of the function here, but the part of it which determines the route based on the current URL.

If you hit the above URL from the browser, you will see the same archives page. We have successfully added a route based on a tag, so that if the first part of our URL is ‘tag‘, it will return the article archive.

Secondly, we are required to have a template file named tag.rhtml. Now, we can get all articles in tag.rhtml, but we need to filter them based on their current tag. For this, make a copy of archives.rhtml and rename it to tag.rhtml. Edit this file to add a tag filter, like given below:

That’s it! Now, if you load the same URL it will list all the articles with that particular tag. We have added an ‘if’ condition which will basically check if the tags of article contain the current tag.

Now we can add links to the tags shown in the index page:

Altering the URL structure

Apart from custom routes, I also had to change the URL structure. Article links from my WordPress site were in the format /yyyy/mm/an-article-title.html. But toto supported only one URL structure, ‘/yyyy/mm/dd/an-article-title/’. In order to change this, you have to do three things:

1. Add two additional config values in class Config.
2. Alter the function which creates links to each article
3. Change routing to accept these URL formats – I have already done it when we customized routing for adding tags.

Search toto.rb to find the Config class and add the following to the Defaults hash.

The first of these config changes is  over the date part of the URLs and the second relates to the URL extension, you need to decide whether to show a ‘/’ (as in this case), or use any other extension like .html, .php, etc. As you can see in the template files, we’re calling a method named ‘path’ wherever we need to add a URL to an article so, we’ll need to alter this method to incorporate the new values from the config files

This will essentially create a URL with our custom date format and extension, with a slug created from the article title. You can check it by changing the suffix to ‘.html’ or something similar.


In this article we have discussed customizing a toto template and engine, and I hope you’ve understood the way toto works. Now you can edit the engine to have more sophisticated functionality like tag clouds, related articles, etc. There are currently a number of forks of toto in Github, customized for users’ own requirements. If you are interested, you can take a look into the one I customized. For this I used Bootstrap from twitter for the template; apart from the above mentioned features, it can show tag clouds and list all categories in an article. If you have any questions, feel free to add comments, I’ll try my best to answer them. Cheers.