Last Update: Wed Feb 01 20:34:06 MST 2006

Markaby (Markup as Ruby)

Markaby is a very short bit of code for writing HTML pages in pure Ruby. It is an alternative to ERb which weaves the two languages together. Also a replacement for templating languages which use primitive languages that blend with HTML.

Using Markaby as a Rails plugin

Write Rails templates in pure Ruby. Example layout:

  html do
    head do
      title 'Products: ' + action_name
      stylesheet_link_tag 'scaffold'

    body do
      p flash[:notice], :style => "color: green"

      self << content_for_layout

Using Markaby as a Ruby class

Markaby is flaming easy to call from your Ruby classes.

  require 'markaby'

  mab =
  mab.html do
    head { title "" }
    body do
      h1 " has great deals"
      ul do
        li "$49 for a canoe"
        li "$39 for a raft"
        li "$29 for a huge boot that floats and can fit 5 people"
  puts mab.to_s does take two arguments for passing in variables and a helper object. You can also affix the block right on to the class.

See Markaby::Builder for all of that.

A Note About instance_eval

The Markaby::Builder class is different from the normal Builder class, since it uses instance_eval when running blocks. This cleans up the appearance of the Markaby code you write. If instance_eval was not used, the code would look like this:

  mab =
  mab.html do
    mab.head { mab.title "" }
    mab.body do
      mab.h1 " has great deals"
  puts mab.to_s

So, the advantage is the cleanliness of your code. The disadvantage is that the block will run inside the Markaby::Builder object’s scope. This means that inside these blocks, self will be your Markaby::Builder object. When you use instance variables in these blocks, they will be instance variables of the Markaby::Builder object.

This doesn’t effect Rails users, but when used in regular Ruby code, it can be a bit disorienting. You are recommended to put your Markaby code in a module where it won’t mix with anything.

A Note About Rails Helpers

When used in Rails templates, the Rails helper object is passed into Markaby::Builder. When you call helper methods inside Markaby, the output from those methods will be output to the stream. This is incredibly handy, since most Rails helpers output HTML tags.

  head do
    javascript_include_tag 'prototype'

However, some methods are designed to give back a String which you can use elsewhere. Call the @helpers object with the method and you’ll get the String back and nothing will be output.

  p "Total is: #{@helper.number_to_human_size @file_bytes}"

Conversely, you may call instance variables from your controller by using a method and its value will be returned, nothing will be output.

  # Inside imaginary ProductController
  def list
    @products = Product.find :all

  # Inside app/views/product/list.mab
  products.each do |product|
    p product.title

A Quick Tour

If you dive right into Markaby, it’ll probably make good sense, but you’re likely to run into a few kinks. Keep these pointers in mind and everything will be fine.

Element Classes

Element classes may be added by hooking methods onto container elements:

  div.entry do
    h2.entryTitle 'Son of WebPage'
    div.entrySection %{by Anthony}
    div.entryContent 'Okay, once again, the idea here is ...'

Which results in:

  <div class="entry">
    <h2 class="entryTitle">Son of WebPage</h2>
    <div class="entrySection">by Anthony</div>
    <div class="entryContent">Okay, once again, the idea here is ...</div>

Element IDs

IDs may be added by the use of bang methods:!
      h1 "A Short Short Saintly Dog"

Which results in:

  <div id="page">
    <div id="content">
      <h1>A Short Short Saintly Dog</h1>

Markaby assumes XHTML 1.0 Transitional

Output defaults to XHTML 1.0 Transitional. To do XHTML 1.0 Strict, try this:

  xhtml_strict do
    # innerds

The capture Method

Want to catch a block of HTML as a string and play with it a bit? Use the capture method.

Commonly used to join HTML blocks together:! \
    ['5.gets', 'bits', 'cult', 'inspect', '-h'].map do |category|
      capture { link_to category }
    join( " | " )

The tag! Method

If you need to force a tag at any time, call tag! with the tag name followed by the possible arguments and block. The CssProxy won’t work with this technique.

  tag! :select, :id => "country_list" do
    countries.each do |country|
      tag! :option, country


Markaby is a work of immense hope by Tim Fletcher and why the lucky stiff. Thankyou for giving it a whirl.

Markaby is inspired by the HTML library within cgi.rb. Hopefully it will turn around and take some cues.