Ninja-Style Blogging with toto and Heroku

It doesn't take much to create a limited, but fast, blog in Ruby if you use existing tools such as Toto (the flat-file blogging engine) and Git, and deploy it to the Heroku cloud platform.

Toto is a very simple blog publishing engine written in Ruby and created by Alexis Sellier, popularly known as @cloudhead (creator of LESS). Toto’s a flat-file blogging engine which means it doesn’t need a database and, unlike many other blogging engines, doesn’t have an admin panel either.

Articles are written in text files and you can use markdown or html inside the file. Toto itself is a Ruby gem designed to run on Heroku. We’ll be using Git, the most popular distributed version control system, to deploy the application and publish articles. That means publishing a new article is as simple as a Git push command.


You must have Ruby, Git, and RubyGems installed in your system. As we are deploying the application in Heroku, you need to have a Heroku account and install the Heroku gem. This article describes how to install Ruby, RubyGems, Git, and Heroku in Ubuntu. If you’re using Windows, you may need to check Heroku documentation. To run and test our application locally, we’re using a light-weight server named thin.

We use Ubuntu OS, so this article is from a Linux perspective. To install toto in Ubuntu, run the following from the command line:

If you have Ruby and RubyGems installed already, it will complete the installation without any problems. Before continuing you need to install thin server to run the blog locally. Thin is also a Ruby gem.

I assume that you have already installed Git. Now clone the Dorothy template from GitHub. Dorothy is the default template for toto.

Navigate to myblog directory and run

from the command line. That’s all! Now you have a sample toto blog running. You can access the blog via your browser using

Okay, it’s time to deploy our application. Create a Heroku application from the command line:

You can check the web dashboard of Heroku to see the created application. If you check the config file of Git repo, you can see a new remote added with name ‘heroku’.

Now let’s push the initial application to Heroku:

This will deploy the application to Heroku and our application will start automatically. If you check it in your browser, you will see toto running.

Toto filesystem

The articles directory holds all our articles. The name of each article should be in the format yyyy-mm-dd-your-long-article-title.txt. It’s important that you should keep the title and filenames the same. The Public folder will have css, js, and image files for template, and the Template folder will contain the page layout (layout.rhtml) and the templates of inner pages, such as about, archives, etc.

Writing a new article

To publish a new article you can open up your favorite text editor and start writing. You can use markdown or html in the article. Every article will have two sections, meta and content. The meta part is simply YAML formatted key: value pairs to specify the metadata of the article. If you take a look into the default article in article folder, you will see the following meta information.

Here the title and date are the only mandatory bits of information. In addition to those, we can also have tags or categories in this section, which can be displayed in the article page. Begin the content section leaving one line after the meta section. Once you finish the article, go to the toto blog root and from the command line and run git status:

It will show we have a new file which has not been added to the repository. Next we can add the file to the repository and commit it.

Now you have the second article published in local dev server. If you like, you can run thin server to see the changes locally. Now, publish the article to Heroku using Git:

Our second article is now published in Heroku.


In this article I have described how to start a simple, blazingly fast blog using toto and Heroku. I have explained only the basic features of toto. In fact, it can do much more than we discussed here, such as have more sophisticated templates, custom pages, etc. Since it doesn’t have an admin panel to hack, it’s a highly secure platform to use.

There are some limitations in the current toto gem. We can’t use all the HTML5 features inside articles since our current markup parser doesn’t support them. Also we don’t have a choice about URL structure. Another big drawback is, you can’t have much dynamic content like comments, search, etc. in the site. Though we can show tags and categories, we can’t have the list of articles under a certain category or tag. I am sure true ninjas won’t be happy with these limitations. To overcome these drawbacks we will need to customize our templates and toto engine to add more functionality. I will describe how to do this in my next article.