summaryrefslogtreecommitdiffhomepage
path: root/haml.html.markdown
diff options
context:
space:
mode:
Diffstat (limited to 'haml.html.markdown')
-rw-r--r--haml.html.markdown155
1 files changed, 155 insertions, 0 deletions
diff --git a/haml.html.markdown b/haml.html.markdown
new file mode 100644
index 00000000..aed3dcae
--- /dev/null
+++ b/haml.html.markdown
@@ -0,0 +1,155 @@
+---
+language: haml
+filename: learnhaml.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.
+
+You can also use Haml on a project independent of Ruby, by installing the Haml gem on your machine and using the command line to convert it to html.
+
+$ haml input_file.haml output_file.html
+
+
+```haml
+/ -------------------------------------------
+/ Indenting
+/ -------------------------------------------
+
+/
+ Because of the importance indentation has on how your code is rendered, the
+ indents should be consistent throughout the document. Any differences in
+ indentation will throw an error. It's common-practice to use two spaces,
+ but it's really up to you, as long as they're constant.
+
+
+/ -------------------------------------------
+/ Comments
+/ -------------------------------------------
+
+/ This is what a comment looks like in 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>
+
+/ The div tag is the default element, 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 ( &= ). This
+ converts html-sensitive characters (&, /, :) into their html encoded
+ equivalents. For example
+
+%p
+ &= "Yes & yes"
+
+/ 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>'
+
+/ CSS 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 its 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.