Introduction to Haml For HTML Layouts for Newbs – Part 2: Writing Haml

Introduction to Haml For HTML Layouts for Newbs – Part 2: Writing Haml

The difference between structure and content

Haml is great! But for what, is the real question. According to Haml’s website, “Markup should be beautiful.” It definitely does make things look clean and easy to read, but there seems to be a catch. Chris Eppstein (creator of Compass) wrote an article that basically says don’t use Haml for content, and I suggest reading it when you are done reading this. Looking at his first example, which I won’t duplicate here, you see what he is driving at right away. For the actual content of the site, Haml starts to look like garbage. What it IS good for though, is the actual structure of the template. Template, file, whatever. The stuff you write in HTML, like this:

<div id="luckDragon"></div>

Haml can do better:


The lesson to be learned here is that, for the main layout of your site use Haml. For the fluff we’ll use something called Markdown, which I’ll talk about in Part 3 of this series. In this post, we are going to deal with the basics of Haml though.

Haml’s syntax

The first part you need in an HTML file is the doctype, and while there are many you can use (which you can see here), I am going to use the HTML5 version. The doctype is written out with three exclamation points, like so:


Which will give you this HTML output:

<!DOCTYPE html>

Pretty sweet, because I am all about eliminating as many characters as possible, so I can get my work done faster. Haml does this with almost everything.

After that, things are pretty straight forward. Elements start with a “%”, id’s start with a ‘#’, class starts with a ‘.’. What is really badass is that Haml defaults id’s and classes to render as a ‘div’ in the HTML output file, unless you specify otherwise. Let’s take a look some basic syntax in an actual example:

!!! 5
		%title Stasis - Static Sites Made Powerful
		%link{ :href => "stasis.css", :media => "screen", :rel => "stylesheet", :type => "text/css" }
						%a{:href=> "#"} Home
						%a{:href=> "#"} Services
						%a{:href=> "#"} About Us
						%a{:href=> "#"} Blog
						%a{:href=> "#"} Contact Us

If you have followed along so far, you can easily see what is going on here. Everything with a ‘%’ symbol in front of it, is an element. Everything with a ‘#’ in front of it is a div tag with an id. Once you render this into the HTML file, this is what you get:

<!DOCTYPE html>
    <title>Stasis - Static Sites Made Powerful</title>
    <link href='stasis.css' media='screen' rel='stylesheet' type='text/css' />
    <div id='container'>
            <a href='#'>Home</a>
            <a href='#'>Services</a>
            <a href='#'>About Us</a>
            <a href='#'>Blog</a>
            <a href='#'>Contact Us</a>
      <div id='content'></div>

Now I know what you are thinking. Yes, the HTML is not formatted the way you would like it to be, but there are options in changing that, which I won’t get into right now. For now, just accept it and move along. In reality, if you are using Haml, the actual HTML is not what you are going to be working with. You would use the ‘.haml’ file. That is the point here.

Moving forward now, so keep up. If you really looked at the example I used above, you will see something I didn’t mention, and that is an element’s attributes. Not that big of a deal, it’s just markup you wouldn’t recognize if you haven’t seen Ruby. After the element you are going to put the ‘{}’ in, and between that are the attributes. If you have multiple, they are seperated by a comma, and each attribute starts with a colon. The odd part you will most likely forget without looking the first few times is the ‘=>’. I look at it as the attribute pointing to the value it is supposed to be. That could have been the intention, but what the hell do I know. Here is what the link to a css file would look like though:

%a{:href=> "#"} Home

Which outputs this HTML:

<a href='#'>Home</a>

Indentation matters, so pay attention!

Yes, Haml pays attention to how you indent your markup. You probably already do this kind of thing in your normal HTML when you nest your div tags, but it isn’t required. Forget to indent at the right place using Haml, and you could get an error when you try to render it into HTML. In the following example, you will see Haml’s markup for the HTML5 doctype:

!!! 5

The above is correct, but if you tabbed over the ‘%html’, which renders as the ‘html’ tag, you will get the error: “Illegal nesting: nesting within a header command is illegal.” This is because Haml treats the indent as if you were nesting the ‘html’ tag within the doctype.

Now, if you indented an element over twice (2 tabs) from its parent, you would get an error that says something like “The line was indented 2 levels deeper than the previous line.” If you ever get an error like this, you know what your problem is. Indenting is extremely important because it shows Haml how to structure everything. If it is tabbed over from the element above it, that element becomes nested within. Seriously, this is important if you are going to be using Haml.

Rendering Haml into HTML

Two methods really. The regular way, and the way Stasis does it if you have that all loaded and ready from the previous post. I’ll show you both though, just in case.

Using Stasis: at the command line, cd to the directory your file is in (index.html.haml) and type:

$ stasis -o index.html.haml

This will output an HTML file in the public folder named ‘index.html’.

Just using Haml, in the command line, cd to your project folder, and type:

$ haml index.haml index.html

The first file (index.haml) is obviously your Haml file, while the second is what you want the output file to be called (index.html in this case).

Either way is easy, you just don’t have to go through all that install crap that I went through in my first post in this series. I was using Stasis because I might be using its options later.

Final thoughts

I REALLY like Haml for its simplicity, and almost as much as I love Sass. You become aware of things pretty quickly once you start using it, such as indentation being key to writing your structure. I think the best part of writing your layout using this, is that the basics are learned quickly. Once you have it down, writing the main structure becomes a breeze. I should also point out that while you are using Haml’s syntax, you can also inject HTML into it just like normal. Seems kind of pointless, but the option is there.

What’s next?

Since Haml is not great for writing the actual content of the site, the third post in this series will deal with Markdown. It is a plain text formatting syntax that you can use within Haml, and makes writing the content easier.

Hope you learned something today, so leave a comment and let me know!

Artilces in this series:

Coupon Code: webmachine

Tags: ,

2 Responses to “Introduction to Haml For HTML Layouts for Newbs – Part 2: Writing Haml”

  1. Neal Rudnick says:

    The whole concept of Haml is pretty cool and would be awesome if it was taking the structure of HTML to another level… but it’s not. After running through your post, you come to realize it is literally knocking off milliseconds by providing you the option to use less characters when writing HTML. Not that big of a deal to me. Of course I always want to use new technologies that will cut down on my build times, but it’s just not that beneficial to use in projects going forward. It adds more time by having to learn new syntax, worrying about indentations (which could cause errors), and kind of lacks a clean code look. Anyways, just my opinion – good review of Haml though, broken down well and easy to understand.

    • jcDesigns says:

      I would agree with you for the most part. Personally I think Haml is easier to read than HTML when looked at by a glance. I also view it as an abstraction language, like Sass and Coffeescript. With Haml, you are basically writing HTML, just getting rid of the extra syntax, so that everything becomes shorter.

      Haml is also meant to be used along with Ruby. 99% of front-end developers are NOT going to just go and use Haml by itself. Likely I’ll be one of the very few, but I also intend to learn Ruby once I get my ass in gear.

      The point of this post isn’t to say “Use Haml, it kicks HTML’s ass!” I’m just showing people the basics, and how to use it, not that they necessarily should. I use Sass now in all of my freelance projects now, and it saves me a lot time, and as Haml seems to do the same thing I thought I would try it out.

      I’ll go over all of my final thoughts in the last post in this series.

      Thanks for the comment by the way! And you can go to hell for taking Vick!!! Trade him for Freeman?

Leave a Reply to Neal Rudnick