summaryrefslogtreecommitdiffhomepage
path: root/haml.html.markdown
blob: 86d9ba8131597b60ee7af4ff7fb9a4ff5299500a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
---
language: haml
filename: learnhaml.html.haml
contributors:
  - ["Simon Neveu", "https://github.com/sneveu"]
---

Haml is a markup language predominantly used with Ruby that cleanly 
and simply describes the HTML of any web document without the use of
inline code. It is a popular alternative to using rails templating 
language (.erb) and allows you to embed ruby code into your markup.

It aims to reduce repetition in your markup by closing tags for you
based on the structure of the indents in your code. The result is
markup that is well-structured, DRY, logical, and easier to read.


```haml
/ -------------------------------------------
/ Comments
/ -------------------------------------------

/ This is what a comment looks like haml.

/
  To write a multi line comment, indent your commented code to be
  wrapped by the forward slash

-# This is a silent comment, which means it wont be rendered into the doc at all


/ -------------------------------------------
/ Html elements
/ -------------------------------------------

/ To write your tags, use the percent sign followed by the name of the tag
%body
  %header
    %nav

/ Notice no closing tags. The above code would output
  <body>
    <header>
      <nav></nav>
    </header>
  </body>

/ Divs are the default elements so they can be written simply like this
.foo

/ To add content to a tag, add the text directly after the declaration
%h1 Headline copy

/ To write multiline content, nest it instead
%p 
  This is a lot of content that we could probably split onto two
  separate lines.

/ You can escape html by using the ampersand and equals sign ( &= )
%p
  &= "Yes & yes"

/ which would output 'Yes &amp; yes'

/ You can unescape html by using the bang and equals sign ( != )
%p
  != "This is how you write a paragraph tag <p></p>"

/ which would output 'This is how you write a paragraph tag <p></p>'

/ Classes can be added to your tags either by chaining .classnames to the tag
%div.foo.bar

/ or as part of a ruby hash
%div{:class => 'foo bar'}

/ Attributes for any tag can be added in the hash
%a{:href => '#', :class => 'bar', :title => 'Bar'}

/ For boolean attributes assign the value 'true'
%input{:selected => true}

/ To write data-attributes, use the :data key with it's value as another hash
%div{:data => {:attribute => 'foo'}}


/ -------------------------------------------
/ Inserting Ruby
/ -------------------------------------------

/ 
  To output a ruby value as the contents of a tag, use an equals sign followed
  by the ruby code

%h1= book.name

%p
  = book.author
  = book.publisher


/ To run some ruby code without rendering it to the html, use a hyphen instead
- books = ['book 1', 'book 2', 'book 3']

/ Allowing you to do all sorts of awesome, like ruby blocks
- books.shuffle.each_with_index do |book, index|
  %h1= book

  if book do
    %p This is a book

/
  Again, no need to add the closing tags to the block, even for the ruby.
  Indentation will take care of that for you.


/ -------------------------------------------
/ Inline Ruby / Ruby interpolation
/ -------------------------------------------

/ Include a ruby variable in a line of plain text using #{}
%p Your highest scoring game is #{best_game}


/ -------------------------------------------
/ Filters
/ -------------------------------------------

/
  Use the colon to define haml filters, one example of a filter you can 
  use is :javascript, which can be used for writing inline js

:javascript
  console.log('This is inline <script>');

```

## Additional resources

- [What is HAML?](http://haml.info/) - A good introduction that does a much better job of explaining the benefits of using HAML.
- [Official Docs](http://haml.info/docs/yardoc/file.REFERENCE.html) - If you'd like to go a little deeper.