Simple web development with Webby

by Zenon Harley

For our website (skythink.com), we needed something simple, sustainable, and relatively secure. We considered using a content management system (CMS) from the superabundance of available options. Our favourites, Textpattern, Drupal, and Wordpress, are overkill for our purposes. They have installation footprints of over 150, 500, and 800 files respectively, not including essential plug-ins. Some minimal CMS options like Blosxom are appealing due to their simplicity (just a single file installed). However, this simplicity comes at a cost. Customization beyond the default setup inevitably requires some degree of tinkering with the source code.

What about going back to the basics? Countless static websites are maintained with fancy (i.e. WYSIWYG) editors like KompoZer, Dreamweaver and iWeb. These editors let you reuse chunks of HTML by setting up templates. But this is useful only up to a point. You cannot, for example, reuse something more abstract like the way you present images. Suppose that instead of directly linking to full-sized images, you wish use a Lightbox effect. With static HTML, regardless of the editor, you will inevitably find yourself cutting and pasting until your fingers hurt.

We breathed a big sigh of relief when we came across Webby. It's not a CMS, but rather it's a web page generator. Written in Ruby, Webby is pure genius, but not necessarily for its originality. The general idea is at least as old as Genpage, which accomplished something similar in Perl as far back as the late 1990's. In fact, Webby is not unique even among modern incarnations of web page generators. Here are a few that we came across:

• Ruby: Webby, nanoc, webgen, Static, StaticMatic, Jekyll
• Python: Poole, Hyde, AYM CMS, Lanyon, growl, Tahchee, Webber
• Perl: WebMake, Genpage
• More can be found on this list.

Webby, in particular, stood out for us because:

• It feels similar to the Ruby On Rails style that we're used to.
• It has many options for reusing code: templates, layouts, partials, helpers.
• It's easily extensible with plugins, including Markdown, our preferred markup language.
• It has a very flexible url system.
• It comes with Blueprint, which is a thoughtful touch.

Getting started

You need Ruby and RubyGems. If you have them, then the following should return their version numbers.

ruby -v
gem -v

We're currently using Ruby 1.8.7 and RubyGems 1.3.5. If you need to install both, start by installing Ruby and then install RubyGems as appropriate for your platform. On our Ubuntu 9.10 workstation, this worked:

sudo apt-get install ruby rubygems ruby1.8-dev

Finally, just install Webby:

sudo gem install webby

If you run into an error regarding not being able to find Webby executables, then probably the gems bin directory is not in your path. This step will differ according to your environment, but on our Ubuntu workstation, we added this to our ~/.profile file.

if [ -d /var/lib/gems/1.8/bin ] ; then
    PATH=/var/lib/gems/1.8/bin:"${PATH}"
fi

The official tutorial and user manual are great, so that material doesn't need to be repeated here. But here is a quick screencast to show how easy it is to get started on Ubuntu:

Using clean urls

If you want clean urls (i.e. /about as opposed to /about.html) there are a couple of obstacles. First of all, the problem is not solved by renaming your content files. Webby doesn't seem to care what extension your content files have. [That's actually nice because you can use whatever naming convention is convenient for development. If it's primarily Markdown text, for example, we just use the .mkd extension because that gives us nice default syntax highlighting in our editor.]

What actually does determine the extension of the output files is the layouts/default.txt file. A site-wide default of an .html extension looks like this:

---
extension: html
filter:    erb
---

You can easily change it to a blank extension:

---
extension: ""
filter:    erb
---

Then rebuild:

webby rebuild

You'll find that output files without extensions are being generated, as expected, but there's a snag. When the Webrick webserver (upon which autobuild depends) sees a file without an extension, it automatically assigns "application/octet-stream" as the MIME type.

To work around this issue, we apply a small patch to Webrick. We do this by adding the following file to the lib directory.

require 'webrick'

# This patch changes the default mime-type detected by Webrick.
#
# Note that in /usr/lib/ruby/1.8/webrick/httputils.rb
# the mime_type method looks like this:
#
# def mime_type(filename, mime_tab)
#   suffix1 = (/\.(\w+)$/ =~ filename && $1.downcase)
#   suffix2 = (/\.(\w+)\.[\w\-]+$/ =~ filename && $1.downcase)
#   mime_tab[suffix1] || mime_tab[suffix2] || "application/octet-stream"
# end
#
# Notice that when a suffix is not recognized, suffix1 and suffix2
# are nil, and then "application/octet-stream" is set.
# 
# We adjust DefaultMimeTypes so that "nil" is interpreted differently.
class Webby::AutoBuilder::WebServer
  alias_method :old_initialize, :initialize

  def initialize
    WEBrick::HTTPUtils::DefaultMimeTypes.store(nil, 'text/html')

    # call the original initialize method
    old_initialize
  end
end

After re-running autobuild, now the /about page loads properly. This is a good time to mention that we disclaim any liability for any damage this may cause. In addition, note that Webrick used in this manner is meant only for your local development environment. Any such patch applied in a production environment is very likely to have unintended consequences.

You will encounter a related problem when you deploy your website online (i.e. your webserver will probably not set the MIME type correctly). We use Apache and for us, it sufficed to set the following in our .htaccess file.

Options -Indexes

RewriteEngine On
RewriteBase /

RewriteRule !\. - [T=text/html]

What it's trying to do is for any address that does not have a dot (.), force the MIME type to be text/html. Again, we do our best, but we're not infallible. This may have unintended consequences. Read up on mod_rewrite to satisfy yourself that this method is right for you!