Haml: the Ruby HTML templating engine that trades angle brackets for indentation

What Haml removes from an HTML document

Haml is a templating engine for HTML written in Ruby. The README describes its goal as eliminating redundancy and reflecting the structure the document represents. In practice that means three things disappear from a template: closing tags, angle brackets, and the repeated class and id attributes that CSS already names.

The audience is narrow and identifiable. It is Ruby developers writing views by hand, either standalone or inside Rails. The README gives the Rails path explicitly: add the gem to your Gemfile and run `bundle`. If you also want Rails's ERB-based generators replaced with Haml generators, the README points to a separate gem, haml-rails.

Haml is not a component framework and not a runtime. It is a compiler from one text syntax to HTML, and the README presents it that way: you write Haml, you get HTML. Everything else, partials, helpers, asset handling, comes from the framework around it.

Indentation as the parse tree

The mechanism is indentation. A tag's children are indented beneath the parent, and Haml adds the closing tag itself. The README's example is a list: `%ul` on one line, then `%li Salt` and `%li Pepper` indented under it, which becomes a `ul` with two `li` children.

Attributes have two accepted forms. The hash form is `%tagname{:attr1 => 'value1', :attr2 => 'value2'} Contents`. The HTML-style form is `%tagname(attr1='value1' attr2='value2') Contents`. Class and id reuse CSS syntax, so `%tagname#id.class` sets both. A tag with no name defaults to a div, which is why `#foo Hello!` compiles to a div with id foo.

Ruby is embedded with two prefixes. An equals sign outputs the result of the expression; a hyphen runs the code without outputting it. Control statements such as `if` and `while` work under the hyphen form, and the README shows a `%strong= now` line inside an `if` block that conditionally emits a string.

The constraint that bites first is indentation consistency. The README states that indentation may be one or more tabs or spaces, but that it must be consistent within a document: hard tabs and spaces cannot be mixed, and the same number of tabs or spaces must be used throughout. Haml 7 supports Ruby 3.2.0 and higher, per the contributing section.

Installing the haml gem and rendering a first document

Installation is a single gem command. The README's first step is:

gem install haml

After writing some Haml, you compile it from the command line:

haml render document.haml

The compiled HTML goes to standard output. The README points at `haml --help` for the full set of commands, so treat the render subcommand as the entry point rather than the whole CLI.

For a Rails app, the README says to add Haml to the Gemfile and run `bundle`:

gem 'haml'

If you want Rails generators to emit Haml instead of ERB, the README says to add haml-rails to the Gemfile as well. To use Haml programmatically rather than through the CLI, the README directs you to the YARD documentation at haml.info.

A minimal file to try first, following the syntax the README documents, is a list with one attribute-carrying item:

%ul
  %li Salt
  %li#pepper Pepper

Rendering that should produce a `ul` containing two `li` elements, the second carrying id pepper. If the output is wrong, check indentation before anything else: mixed tabs and spaces are the most common cause of a parse that does not match what you see on screen.

Where Haml is the wrong tool

The clearest failure mode is indentation drift. Because structure is whitespace, a diff that changes leading whitespace changes the document. That is fine in an editor with visible whitespace and painful in a review tool that renders tabs ambiguously. The README's rule is absolute, not a style preference: no mixing, one consistent count throughout the file.

A second limitation is language lock-in. Haml is a Ruby gem, and the README's usage paths are the command line and Ruby web frameworks. If your application is not Ruby, the gem does not help you, and the CLI route only makes sense if you are willing to run Ruby in the build.

A third case is content that is already HTML. Haml's value comes from rewriting markup in its own syntax, so a template that is largely pasted HTML snippets gains little and loses the ability to paste them unchanged. The README does not document a passthrough mode for arbitrary HTML blocks, so budget for converting that content rather than assuming it can stay as-is.

Finally, the README does not document rollback or migration tooling for moving a codebase back to ERB. That absence is worth noting before a large conversion, because the reverse direction is manual work.

Haml against ERB and other Ruby templating engines

The natural comparison is ERB, Rails's default. ERB is HTML with Ruby embedded between `<% %>` and `<%= %>` tags; the document keeps its angle brackets and closing tags, and the template is valid HTML with embedded code. Haml inverts that: the document is not HTML at all, and the compiler produces it. The practical difference is where the redundancy lives. ERB repeats closing tags and attribute syntax; Haml repeats indentation levels. Neither is free.

That difference decides most adoption questions. If your team reviews templates as HTML, or if designers hand you markup, ERB keeps that workflow intact. If your team writes views by hand all day and finds closing-tag noise the main cost, Haml's syntax removes it, at the price of a compiler step and an indentation contract.

The README also distinguishes Haml from haml-rails, which is not an alternative engine but a Rails integration that swaps the ERB-based generators. Adding haml alone gives you the engine; adding haml-rails changes what `rails generate` writes. Those are separate decisions.

Upgrades, maintenance and the MIT licence

The repository is not archived. Its last push was on 2026-09-01, and releases v7.5.1, v7.5.0 and v7.4.1 landed in August and September 2026, so the project is being maintained on a current cadence. The README lists four current maintainers and names Hampton Catlin as the original author, with Natalie Weizenbaum and Norman Clarke as alumni. That history matters for one reason: a templating language accumulates syntax, and the REFERENCE.md file at the repository root is where the full grammar lives, not the README.

The version to plan around is Haml 7, which the contributing section says supports Ruby 3.2.0 and higher. If you are on an older Ruby, that is the boundary to check before upgrading, and the CHANGELOG.md at the repository root is the place to read what moved between 7.4 and 7.5.

Licensing is MIT. The README states the implementation is licensed under the MIT License, with copyright spanning 2006 to 2019 for Hampton Catlin, Natalie Weizenbaum and the Haml team, and notes that some of Natalie's work was supported by Unspace Interactive. MIT is permissive: it allows use, modification, distribution and sublicensing provided the copyright notice and permission notice are included. That is a description of the licence text, not legal advice; if your organisation has a policy on attribution in distributed artifacts, have it reviewed against the actual MIT-LICENSE file in the repository.

Editorial conclusion

Adopt Haml if you maintain a Ruby or Rails view layer and want markup whose structure is visible from indentation alone. Do not adopt it if your templates are mostly pasted HTML, if you need a non-Ruby host language, or if your team cannot agree on one indentation width, because the README states that hard tabs and spaces cannot be mixed and the same count must be used throughout. Before committing, render one of your real ERB views through `haml render` and compare the output, and check the REFERENCE.md file in the repository for the syntax your templates actually use, since the README covers only the basics.

Frequently asked questions

Official sources

1. haml/haml on GitHub
2. License: MIT
3. Project website
4. README
5. Releases