Skip to content
๐Ÿ“š Static blogs: YAML + Slim โ†’ HTML5
Branch: master
Clone or download
Fetching latest commitโ€ฆ
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Readably: YAML + Slim => HTML5

                  (, /   )          /)     /)  /)
                    /__ /  _  _   _(/ _   (/_ //
                 ) /   \__(/_(_(_(_(_(_(_/_) (/_ (_/_
                (_/                             .-/

Readably is a minimal static blog engine that emits clean, readable Web pages. You can view them locally on your own computer without needing a Web server. And when you publish them to any Web server, they will function just as they did locally on your computer. This is the benefit of a static blog engine!

See my blog at for an example of Readably output.


  • Its output is easy to read and beautiful to print in modern Web browsers.

  • Its output is self-explanatory and multi-lingual: no translation needed. (There is only 1 English phrase in the entire output, for attribution.)

  • It has simple navigation that works well in both text-mode Web browsers (such as Lynx, elinks, and w3m) and modern Web browsers (like Firefox).

  • It supports the two most popular JavaScript-based blog comment services: Disqus and IntenseDebate.

  • It supports automatic syntax highlighting of code blocks in Markdown.

  • It is implemented in less than 200 lines of pure Ruby code! :-)




git clone
cd readably
bundle install # with markdown OR
bundle install --without markdown


bundle exec rake
firefox content/index.html


  • Edit the config.yaml and template/* files to your liking.

  • Edit the Rakefile to configure the blog processing logic. (This isn't really necessary, but you are free to do so.)


NOTE: If you are using Ruby 1.8.7, add -rubygems to the following commands.

Run bundle exec rake --tasks to see available commands:

bundle exec rake build    # Build entire blog.
bundle exec rake entry    # Build entry pages.
bundle exec rake index    # Build index pages.
bundle exec rake style    # Build stylesheet.

bundle exec rake clean    # Remove any temporary products.
bundle exec rake clobber  # Remove any generated file.

bundle exec rake upgrade  # Upgrade blog software.


To create a new blog entry (*.readably file) from the template:

cp content/entry.readably content/your-entry-file-name.readably
edit content/your-entry-file-name.readably

To create a new blog entry (*.readably file) in a nested directory:

cp content/entry.readably content/your/path/your-entry-file-name.readably
edit content/your/path/your-entry-file-name.readably


Simply open the content/index.html file in your favorite web browser. After making changes to a blog entry, run bundle exec rake, and then reload the corresponding web page in your web browser.


Use your favorite file uploading software to upload the content/ directory (while omitting *.readably files from it) to your web hosting platform.

Here is an example that uses rsync to upload to a DESTINATION. (NOTE: the trailing slash after DESTINATION is necessary!)

rsync -auv content/ --exclude '*.readably' DESTINATION/

You can take this further and make it a Rake task by adding it to Rakefile:

desc 'Publish your blog.'
task :publish => :build do
  sh "rsync -auv content/ --exclude '*.readably' DESTINATION/"

From then onwards, you can publish your blog at any time, simply by running:

bundle exec rake publish


To upgrade your copy of Readably, run the following command:

bundle exec rake upgrade


Fork this project on GitHub and send pull requests.

Bugs, Features, Issues, Questions

File a report on the issue tracker.


Like my work? ๐Ÿ‘ Please spare a life today as thanks! ๐Ÿฎ๐Ÿท๐Ÿ”๐ŸŸ๐Ÿ™ŠโœŒ๏ธ๐Ÿ’ž

Copyright 2010 Suraj N. Kurapati

Distributed under the terms of the ISC license (see the LICENSE file).

You canโ€™t perform that action at this time.