Static blogs: YAML + Slim → HTML5
Failed to load latest commit information.
content make everything Just Work by default with examples Apr 7, 2016
template style: replace TOC's dashed border with inset glow Jun 19, 2016
.gitignore use negation in .gitignore to unignore *.readably Jul 18, 2014
Gemfile.lock upgrade to slim 3.0 and fix deprecation warnings Apr 7, 2016
LICENSE initial GitHub release May 7, 2010
Rakefile upgrade to slim 3.0 and fix deprecation warnings Apr 7, 2016
config.yaml make everything Just Work by default with examples Apr 7, 2016


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.