Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Some usefull helpers for your ruby based blog.
Branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib refactored a little


Having a closer look at ruby based blogging platforms like serious and toto, I missed some functionality.

This a a collection of tools usable in both platforms. The project was formerly known as blog_helper, but Karakuri is a far more suitable name & will be used from now on.


  • tag your posts
  • use seo friendly page titles
  • use the disqus comment counter
  • a workaround for serious allowing you to use generic yaml fields


It's a piece of cake: just install the gem. Simply add gem 'karakuri' to your Gemfile or use sudo gem install karakuri to get going.

For a default karakuri powered toto template, check out dorothy's sister karathy.


Piece of cake, again: all you have to do is use <% require 'karakuri'%> in your .rhtml or .erb file and call the corresponding methods.

SEO friendly titles

For example, to use seo friendly titles, your layout.rhtml should be looking like this:

<!doctype html>
    <% require 'karakuri'
       page_title = Karakuri::seo_friendly_title(@path, title, '')
    <title><%=  page_title %></title>
    <link rel="alternate" type="application/atom+xml" title="<%= page_title %> - feed" href="/index.xml" />


Adding the tagging feature requires the toto_prerelease as mentioned above, since we need the http request to apply our little hack.

To add a list of tags to your article, just use a custom yaml attribute:

title: The Wonderful Wizard of Oz
author: Lyman Frank Baum
date: 1900/05/17
tags: hacks, love, rock 'n' roll

Dorothy lived in the midst of the great Kansas prairies, with Uncle Henry,
who was a farmer, and Aunt Em, who was the farmer's wife.

Next, you need a place to show the tag links, for example the index.rhtml:

<section id="articles">
  <% require 'karakuri' %>
  <% for article in articles[0...10] %>
    <article class="post">
        <h1><a href="<%= article.path %>"><%= article.title %></a></h1>
        <span class="descr"><%= %></span><% 10.times { %>&nbsp;<%}%>
        <span class="tags">
            <%= Karakuri::tag_link_list(article[:tags])  %>
        </span><% 10.times { %>&nbsp;<%}%>

And again: piece of cake ;-). Now all we need to add is a page that displays articles belonging to a ceratin tag:

Create a page called tagged.rhtml in your templates/pages directory that looks like this:

 require 'karakuri'
 desired_tag = Karakuri::desired_tag(env["QUERY_STRING"])
<h1>Posts filed under '<%= desired_tag %>': </h1>

<% Karakuri::desired_articles(@articles, desired_tag).each do |article| %>
    <span class="descr"><a href="<%= article.path %>" alt="<%= article.title %>"><%= article.title %></a><br/></span>
<% end %>

Now, you did most likely implement a tag listing on your toto blog. Congrats!

Tag Cloud

Example usage:

<%  Karakuri::tag_cloud(@articles).each do |tag, freq| %>
    <%= %|<a href="/tagged?tag=#{tag}" alt="articles concerning #{tag}" style="font-size: #{10 * freq}px">#{tag}</a>| %>
<% end %>

Thanks baopham for the nice addition.

short url (via

To use a shortened URL, just call the followin function inside a .rhtml file:

<%= Karakuri::short_url_bitly(<url>, < login name>, < api key>) %>

disqus comment counter

Basically just adds the necessary java script to enable the disqus comment counter. For best performance, place it near the end of the page:

    <%= Karakuri::disqus_comment_count_js(@config[:disqus]) %>


Mind the usage of @config[:disqus], this enables configuration via

To access the comment count, use #disqus_thread at the end of the permalink to the post & it will be replaced with the disqus comment count:

<a href="<%= article.path %>#disqus_thread">&nbsp;</a>

Will result in the number of comments of the article the permalink posts to.

serious custom yaml field reader

I hacked serious' custom yaml field access (quite dirty hack) - but please refer to the source & ri for that, I don't use serious anymore.

Something went wrong with that request. Please try again.