Introduction to Haml For HTML Layouts for Newbs – Part 3: Markdown Syntax For Content

Introduction to Haml For HTML Layouts for Newbs – Part 3: Markdown Syntax For Content

Haml rocks for Layout, but what about content?

So obviously I really like Haml. Pretty sure that comes through in my writing. I’ve also stated that it is good for the layout/structure of your page, but what about the fluff of the page? You know, all the paraphraphs, lists and other crap the end user will actually read. Let me finally give you an example of why Haml is not the way to go for this.

            %a{:href=> "/index.html"} Home
            %a{:href=> "/services"} Services
            %a{:href=> "/about"} About

Keep in mind this is a very uncomplicated example, but I want you to note that each element has to be on its own line, which is a pain in the ass when dealing with content. There is a better way though, and that is where Markdown comes in (and use that link for reference later). Think of Markdown as a small syntax, within another syntax, used specifically to write plain text formatting and turn it into HTML. All you have to do is use Haml’s Markdown filter. How the hell do you do that? Easy, and I’m glad you were so thoughtful to ask. A simple colon, followed by the filter name. To write the same thing I wrote above using Markdown, you would write:

        + [Home](/index.html)
        + [Services](/services)
        + [About](/about)

Much easier to read, wouldn’t you agree? If you want to see a really good example, go and check Chris Eppstein’s article and you will REALLY get the point. Which basically is that Haml isn’t really made for creating content because of how it must be written. Markdown though handles it very well. Seriously, check out that link and you will see what must be done to get a simple link within a paragraph tag.

Markdown’s basic syntax

Markdown isn’t going to pay attention to your indentation. It is better to give you a clear cut example though of the basics, because it is easier to see than to explain it.

	#This is an h1 tag
	##This is an h2 tag
	###This is an h3 tag
	This is a paragraph
	<p class="highlight">You can also insert html</p>
	This is **strong**
	This is *italic*, and below is an image
        ![Alt text](/path/to/img.jpg)
        + List item
        + List item
        + List item

This will render in HTML as:

<div id='content'>
        <h1>This is an h1 tag</h1>
        <h2>This is an h2 tag</h2>
        <h3>This is an h3 tag</h3>
        <p>This is a paragraph</p>
        <p class="highlight">You can also insert html</p>
        <p>This is <strong>strong</strong></p>
        <p>This is <em>italic</em>, and below is an image
        <img src="/path/to/img.jpg" alt="Alt text" /></p>  
        <li>List item</li>
        <li>List item</li>
        <li>List item</li>

There are some things to note, as there always are when using something like this. First, as you can see in the Haml part, you are free to inject HTML within the Markdown filter. Yep, that’s right! Second, there are multiple ways to do certain things, such as the header tags which you can see marked with the ‘#’ in front of them. Here are two ways to do ‘h1′ and ‘h2′ tags in Markdown:

#This is an h1 tag in Markdown
This is also an h1 tag
##This is an h2 tag in Markdown
This is also an h2 tag

Any number of equal signs or dashes will work underneath the headings, but the cool part is that there are different options to write the same thing. Bold and italic also have different options, but for my main example I used the ones I preferred. The heading tags just seem easier to remember if I use the correct number of ‘#’ in front of them. If you want to see all of the syntax used in Markdown, go to the site that I linked to above.

Wait, so I have to learn TWO different kinds of syntax?

Oh GOD with your complaining. No, feel free to use Haml for the content of your site. See if I give a crap. I guarantee after about five minutes you will be fed up. Also, it’s not like you are learning a coding language. Haml basics take about 20 minutes or less to learn, and once you have written some basic content in Markdown, you will understand it without much need to go look something up. It is that easy.

I can’t explain in words how fun it is to write a page out using Haml. You have to go and do it yourself to really get it. Once you do though, I’ll bet you will see how much better it is to write your layout in Haml. Using Markdown to write the content makes it even easier. Not only will you actually enjoy it, you will see how clean your web page can really be. Feel free to leave a comment thanking me after showing you the light.

Now go and do it!

Articles in this series:

Coupon Code: webmachine

Tags: ,

Leave a Reply