Haml Changelog


Released on August 10, 2015 (diff).


Released on Dec 1, 2014 (diff).


Released on Jan 7, 2014 (diff).


Released on November 5, 2013 (diff).


Released May 21, 2013 (diff).


Released April 5, 2013 (diff).


Released March 21, 2013 (diff).



The Haml 3.2 series was released only as far as 3.2.0.rc.4, but then was renamed to Haml 4.0 when the project adopted semantic versioning.










Backwards Incompatibilities – Must Read!


Tagged on GitHub.


Tagged on GitHub.


Tagged on GitHub.


Tagged on GitHub.


Tagged on GitHub.


Tagged on GitHub.


Tagged on GitHub.


Tagged on GitHub.


Tagged on GitHub.


Tagged on GitHub.


Tagged on GitHub.

There were no changes made to Haml between versions 3.0.14 and 3.0.15.


Tagged on GitHub.

Rails 3 Support


Tagged on GitHub.

Rails 3 Support

Support for Rails 3 versions prior to beta 4 has been removed. Upgrade to Rails 3.0.0.beta4 if you haven’t already.

Minor Improvements


Tagged on GitHub.

Rails 3 Support

Apparently the last version broke in new and exciting ways under Rails 3, due to the inconsistent load order caused by certain combinations of gems. 3.0.12 hacks around that inconsistency, and should be fully Rails 3-compatible.

Deprecated: Rails 3 Beta 3

Haml’s support for Rails 3.0.0.beta.3 has been deprecated. Haml 3.0.13 will only support 3.0.0.beta.4.


Tagged on GitHub.


Tagged on GitHub.

Appengine-JRuby Support

The way we determine the location of the Haml installation no longer breaks the version of JRuby used by appengine-jruby.

Bug Fixes


Tagged on GitHub.

There were no changes made to Haml between versions 3.0.8 and 3.0.9. A bug in Gemcutter caused the gem to be uploaded improperly.


Tagged on GitHub.


Tagged on GitHub.

Encoding Support

Haml 3.0.7 adds support for Ruby-style -# coding: comments for declaring the encoding of a template. For details see the reference.

This also slightly changes the behavior of Haml when the :encoding option is not set. Rather than defaulting to "utf-8", it defaults to the encoding of the source document, and only falls back to "utf-8" if this encoding is "us-ascii".

The haml executable also now takes an -E option for specifying encoding, which works the same way as Ruby’s -E option.

Other Changes

Bug Fixes


Tagged on GitHub.

Rails 2.3.7 Support

This release fully supports Rails 2.3.7.

Rails 2.3.6 Support Removed

Rails 2.3.6 was released with various bugs related to XSS-protection and interfacing with Haml. Rails 2.3.7 was released shortly after with fixes for these bugs. Thus, Haml no longer supports Rails 2.3.6, and anyone using it should upgrade to 2.3.7.

Attempting to use Haml with Rails 2.3.6 will cause an error.


Tagged on GitHub.

Rails 2.3.6 Support

This release hacks around various bugs in Rails 2.3.6, bringing Haml up to full compatibility.

Rails 3 Support

Make sure the #capture helper in Rails 3 doesn’t print its value directly to the template.


Tagged on GitHub.

There were no changes made to Haml between versions 3.0.3 and 3.0.4.


Tagged on GitHub.

Rails 3 Support

In order to make some Rails loading errors easier to debug, Sass will now raise an error if Rails.root is nil when Sass is loading. Previously, this would just cause the paths to be mis-set.


Tagged on GitHub.

There were no changes made to Haml between versions 3.0.1 and 3.0.2.


Tagged on GitHub.

Installation in Rails

haml --rails is no longer necessary for installing Haml in Rails. Now all you need to do is add gem "haml" to the Gemfile for Rails 3, or add config.gem "haml" to config/environment.rb for previous versions.

haml --rails will still work, but it has been deprecated and will print an error message. It will not work in the next version of Haml.

Rails Test Speed

The :ugly option is now on by default in the testing environment in Rails to help tests run faster.


Tagged on GitHub.

Backwards Incompatibilities: Must Read!

More Useful Multiline

Ruby code can now be wrapped across multiple lines as long as each line but the last ends in a comma. For example:

= link_to_remote "Add to cart",
    :url => { :action => "add", :id => product.id },
    :update => { :success => "cart", :failure => "error" }

haml_tag and haml_concat Improvements

haml_tag with CSS Selectors

The haml_tag helper can now take a string using the same class/id shorthand as in standard Haml code. Manually-specified class and id attributes are merged, again as in standard Haml code. For example:

haml_tag('#foo') #=> <div id='foo' />
haml_tag('.bar') #=> <div class='bar' />
haml_tag('span#foo.bar') #=> <span class='bar' id='foo' />
haml_tag('span#foo.bar', :class => 'abc') #=> <span class='abc bar' id='foo' />
haml_tag('span#foo.bar', :id => 'abc') #=> <span class='bar' id='abc_foo' />

Cheers, S. Burkhard.

haml_tag with Multiple Lines of Content

The haml_tag helper also does a better job of formatting tags with multiple lines of content. If a tag has multiple levels of content, that content is indented beneath the tag. For example:

haml_tag(:p, "foo\nbar") #=>
  # <p>
  #   foo
  #   bar
  # </p>

haml_tag with Multiple Lines of Content

Similarly, the haml_concat helper will properly indent multiple lines of content. For example:

haml_tag(:p) {haml_concat "foo\nbar"} #=>
  # <p>
  #   foo
  #   bar
  # </p>

haml_tag and haml_concat with :ugly

When the :ugly option is enabled, haml_tag and haml_concat won’t do any indentation of their arguments.

Basic Tag Improvements

:class and :id Attributes Accept Ruby Arrays

In an attribute hash, the :class attribute now accepts an Array whose elements will be converted to strings and joined with

`" "`

. Likewise, the :id attribute now accepts an Array whose elements will be converted to strings and joined with "_". The array will first be flattened and any elements that do not test as true will be stripped out. For example:

.column{:class => [@item.type, @item == @sortcol && [:sort, @sortdir]] }

could render as any of:

class="column numeric sort ascending"
class="column numeric"
class="column sort descending"

depending on whether @item.type is "numeric" or nil, whether @item == @sortcol, and whether @sortdir is "ascending" or "descending".

A single value can still be specified. If that value evaluates to false it is ignored; otherwise it gets converted to a string. For example:

.item{:class => @item.is_empty? && "empty"}

could render as either of:

class="item empty"

Thanks to Ronen Barzel.

HTML5 Custom Data Attributes

Creating an attribute named :data with a Hash value will generate HTML5 custom data attributes. For example:

%div{:data => {:author_id => 123, :post_id => 234}}

Will compile to:

<div data-author_id='123' data-post_id='234'></div>

Thanks to John Reilly.

More Powerful :autoclose Option

The :attributes option can now take regular expressions that specify which tags to make self-closing.

--double-quote-attributes Option

The Haml executable now has a --double-quote-attributes option (short form: -q) that causes attributes to use a double-quote mark rather than single-quote. Thanks to Charles Roper.

:css Filter

Haml now supports a :css filter that surrounds the filtered text with <style> and CDATA tags.

haml-spec Integration

We’ve added the cross-implementation tests from the haml-spec project to the standard Haml test suite, to be sure we remain compatible with the base functionality of the many and varied Haml implementations.

Ruby 1.9 Support

Rails Support

Rip Support

Haml is now compatible with the Rip package management system. Thanks to Josh Peek.

html2haml Improvements

Minor Improvements


Tagged on GitHub.


Tagged on GitHub.


Tagged on GitHub.


Tagged on GitHub.


Tagged on GitHub.


Tagged on GitHub.


Tagged on GitHub.


Tagged on GitHub.


Tagged on GitHub.


Tagged on GitHub.


Tagged on GitHub.


Tagged on GitHub.


Tagged on GitHub.

There were no changes made to Haml between versions 2.2.11 and 2.2.12.


Tagged on GitHub.


Tagged on GitHub.


Tagged on GitHub.

Rails XSS Protection

Haml 2.2.9 supports the XSS protection in Rails versions 2.3.5+. There are several components to this:


Tagged on GitHub.


Tagged on GitHub.


Tagged on GitHub.


Tagged on GitHub.


Tagged on GitHub.


Tagged on GitHub.

Haml 2.2.3 adds support for the JRuby bundling tools for Google AppEngine, thanks to Jan Ulbrich.


Tagged on GitHub.

Haml 2.2.2 is a minor bugfix release, with several notable changes. First, haml_concat will now raise an error when used with =. This has always been incorrect behavior, and in fact has never actually worked. The only difference is that now it will fail loudly. Second, Ruby 1.9 is now more fully supported, especially with the new attribute syntax. Third, filters are no longer escaped when the :escape_html option is enabled and #{} interpolation is used.


Tagged on GitHub.

Haml 2.2.1 is a minor bug-fix release.


Tagged on GitHub.

Haml 2.2 adds several new features to the language, fixes several bugs, and dramatically improves performance (particularly when running with :ugly enabled).

Syntax Changes

HTML-Style Attribute Syntax

Haml 2.2 introduces a new syntax for attributes based on the HTML syntax. For example:

%a(href="http://haml.info" title="Haml's so cool!")
  %img(src="/images/haml.png" alt="Haml")

There are two main reasons for this. First, the hash-style syntax is very Ruby-specific. There are now Haml implementations in many languages, each of which has its own syntax for hashes (or dicts or associative arrays or whatever they’re called). The HTML syntax will be adopted by all of them, so you can feel comfortable using Haml in whichever language you need.

Second, the hash-style syntax is quite verbose. %img{:src => "/images/haml.png", :alt => "Haml"} is eight characters longer than %img(src="/images/haml.png" alt="Haml"). Haml’s supposed to be about writing templates quickly and easily; HTML-style attributes should help out a lot with that.

Ruby variables can be used as attribute values by omitting quotes. Local variables or instance variables can be used. For example:

%a(title=@title href=href) Stuff

This is the same as:

%a{:title => @title, :href => href} Stuff

Because there are no commas separating attributes, more complicated expressions aren’t allowed. You can use #{} interpolation to insert complicated expressions in a HTML-style attribute, though:


Multiline Attributes

In general, Haml tries to keep individual elements on a single line. There is a multiline syntax for overflowing onto further lines, but it’s intentionally awkward to use to encourage shorter lines.

However, there is one case where overflow is reasonable: attributes. Often a tag will simply have a lot of attributes, and in this case it makes sense to allow overflow. You can now stretch an attribute hash across multiple lines:

%script{:type => "text/javascript",
        :src  => "javascripts/script_#{2 + 7}"}

This also works for HTML-style attributes:

        src="javascripts/script_#{2 + 7}")

Note that for hash-style attributes, the newlines must come after commas.

Universal interpolation

In Haml 2.0, you could use == to interpolate Ruby code within a line of text using #{}. In Haml 2.2, the == is unnecessary; #{} can be used in any text. For example:

%p This is a really cool #{h what_is_this}!
But is it a #{h what_isnt_this}?

In addition, to escape or unescape the interpolated code, you can just add & or !, respectively, to the beginning of the line:

%p& This is a really cool #{what_is_this}!
& But is it a #{what_isnt_this}?

Flexible indentation

Haml has traditionally required its users to use two spaces of indentation. This is the universal Ruby style, and still highly recommended. However, Haml now allows any number of spaces or even tabs for indentation, provided:

New Options


The :ugly option is not technically new; it was introduced in Haml 2.0 to make rendering deeply nested templates less painful. However, it’s been greatly empowered in Haml 2.2. It now does all sorts of performance optimizations that couldn’t be done before, and its use increases Haml’s performance dramatically. It’s enabled by default in production in Rails, and it’s highly recommended for production environments in other frameworks.


This option specifies the encoding of the Haml template when running under Ruby 1.9. It defaults to Encoding.default_internal or "utf-8". This is useful for making sure that you don’t get weird encoding errors when dealing with non-ASCII input data.



This helper is being deprecated for the obvious reason that it conflicts with the Kernel#puts method. I’m ashamed I ever chose this name. Use haml_concat instead and spare me the embarrassment.

= haml_tag

A lot of people accidentally use “= haml_tag”. This has always been wrong; haml_tag outputs directly to the template, and so should be used as “- haml_tag”. Now it raises an error when you use =.



Haml 2.2 is fully compatible with Rails, from 2.0.6 to the latest revision of edge, 783db25.

Ruby 1.9

Haml 2.2 is also fully compatible with Ruby 1.9. It supports Ruby 1.9-style attribute hashes, and handles encoding-related issues (see the :encoding option).



There are numerous improvements to the Markdown filter. No longer will Haml attempt to use RedCloth’s inferior Markdown implementation. Instead, it will look for all major Markdown implementations: RDiscount, RPeg-Markdown, Maruku, and BlueCloth.


There is now a :cdata filter for wrapping text in CDATA tags.


The :sass filter now uses options set in Sass::Plugin, if they’re available.



The haml executable now takes -r and -I flags that act just like the same flags for the ruby executable. This allows users to load helper files when using Haml from the command line.

It also takes a --debug flag that causes it to spit out the Ruby code that Haml generates from the template. This is more for my benefit than anything, but you may find it interesting.


The html2haml executable has undergone significant improvements. Many of these are bugfixes, but there are also a few features. For one, it now understands CDATA tags and autodetects ERB files. In addition, a line containing just “- end” is now a Haml error; since it’s not possible for html2haml to properly parse all Ruby blocks, this acts as a signal for the author that there are blocks to be dealt with.



Haml 2.2 supports a DTD for XHTML Mobile: !!! Mobile.


All the documentation for Haml 2.2, including this changelog, has been moved to YARD. YARD is an excellent documentation system, and allows us to write our documentation in Maruku, which is also excellent.