haml 3.2.0.alpha.10 → 3.2.0.alpha.13

data/FAQ.md

@@ -0,0 +1,157 @@
+# Frequently Asked Questions
+
+## Haml
+
+### Why is my markup indented properly in development mode, but not in production?
+{#q-indentation-in-production}
+
+To improve performance, Haml defaults to {file:HAML_REFERENCE.md#ugly-option "ugly" mode} in Rails
+apps running in production.
+
+
+### How do I put a punctuation mark after an element, like "`I like <strong>cake</strong>!`"?
+{#q-punctuation}
+
+Expressing the structure of a document
+and expressing inline formatting are two very different problems.
+Haml is mostly designed for structure,
+so the best way to deal with formatting is to leave it to other languages
+that are designed for it.
+You could use Textile:
+
+    %p
+      :textile
+        I like *cake*!
+
+or Markdown:
+
+    %p
+      :markdown
+        I like **cake**!
+
+or plain old XHTML:
+
+    %p I like <strong>cake</strong>!
+
+If you're inserting something that's generated by a helper, like a link,
+then it's even easier:
+
+    %p== I like #{link_to 'chocolate', 'http://franschocolates.com'}!
+
+### How do I stop Haml from indenting the contents of my `pre` and `textarea` tags?
+{#q-preserve}
+
+Because Haml automatically indents the HTML source code,
+the contents of whitespace-sensitive tags like `pre` and `textarea`
+can get screwed up.
+The solution is to replace the newlines inside these tags
+with HTML newline entities (`&#x000A;`),
+which Haml does using the {Haml::Helpers#preserve} and {Haml::Helpers#find_and_preserve} helpers.
+
+Normally, Haml will do this for you automatically
+when you're using a tag that needs it
+(this can be customized using the {file:HAML_REFERENCE.md#preserve-option `:preserve`} option.
+For example,
+
+    %p
+      %textarea= "Foo\nBar"
+
+will be compiled to
+
+    <p>
+      <textarea>Foo&#x000A;Bar</textarea>
+    </p>
+
+However, if a helper is generating the tag,
+Haml can't detect that and so you'll have to call {Haml::Helpers#find_and_preserve} yourself.
+You can also use `~`, which is the same as `=`
+except that it automatically runs `find_and_preserve` on its input.
+For example:
+
+    %p= find_and_preserve "<textarea>Foo\nBar</textarea>"
+
+is the same as
+
+    %p~ "<textarea>Foo\nBar</textarea>"
+
+and renders
+
+    <p><textarea>Foo&#x000A;Bar</textarea></p>
+
+### How do I make my long lines of Ruby code look nicer in my Haml document?
+{#q-multiline}
+
+Put them in a helper or your model.
+
+Haml purposefully makes it annoying to put lots of Ruby code into your templates,
+because lots of code doesn't belong in the view.
+If you take that huge `link_to_remote` call
+and move it to a `update_sidebar_link` helper,
+it'll make your view both easier to read and more semantic.
+
+If you absolutely must put lots of code in your template,
+Haml offers a somewhat awkward multiline-continuation tool.
+Put a `|` (pipe character) at the end of each line you want to be merged into one
+(including the last line!).
+For example:
+
+    %p= @this.is(way.too.much). |
+        code("and I should").   |
+        really_move.it.into(    |
+          :a => @helper)        |
+
+Note that sometimes it is valid to include lots of Ruby in a template
+when that Ruby is a helper call that passes in a lot of template information.
+Thus when a function has lots of arguments,
+it's possible to wrap it across multiple lines
+as long as each line ends in a comma.
+For example:
+
+    = link_to_remote "Add to cart",
+        :url => { :action => "add", :id => product.id },
+        :update => { :success => "cart", :failure => "error" }
+
+### `form_for` is printing the form tag twice!
+
+Make sure you're calling it with `-`, not `=`.
+Just like in ERB, you have to do
+
+    <% form_for stuff do %>
+      ...
+    <% end %>
+
+in Haml, you have to do
+
+    - form_for stuff do
+      ...
+
+### I have Haml installed. Why is Rails (only looking for `.html.erb` files | rendering Haml files as plain text | rendering Haml files as blank pages)?
+{#q-blank-page}
+
+There are several reasons these things might be happening.
+First of all, make sure that Haml really is installed;
+either you've loaded the gem (via `config.gem` in Rails 2.3 or in the Gemfile in Rails 3),
+or `vendor/plugins/haml` exists and contains files.
+Then try restarting Mongrel or WEBrick or whatever you might be using.
+
+Finally, if none of these work,
+chances are you've got some localization plugin like Globalize installed.
+Such plugins often don't play nicely with Haml.
+Luckily, there's usually an easy fix.
+For Globalize, just edit `globalize/lib/globalize/rails/action_view.rb`
+and change
+
+    @@re_extension = /\.(rjs|rhtml|rxml)$/
+
+to
+
+    @@re_extension = /\.(rjs|rhtml|rxml|erb|builder|haml)$/
+
+For other plugins, a little searching will probably turn up a way to fix them as well.
+
+## You still haven't answered my question!
+
+Sorry! Try looking at the [Haml](http://haml.info/docs/yardoc/HAML_REFERENCE.md.html) reference,
+If you can't find an answer there,
+feel free to ask in `#haml` on irc.freenode.net
+or send an email to the [mailing list](http://groups.google.com/group/haml).

data/README.md

@@ -1,59 +1,55 @@
 # Haml
 
-Haml is a templating engine for HTML.
-It's are designed to make it both easier and more pleasant
-to write HTML documents,
-by eliminating redundancy,
-reflecting the underlying structure that the document represents,
-and providing elegant, easily understandable, and powerful syntax.
+[![Build Status](https://secure.travis-ci.org/haml/haml.png?branch=master)](http://travis-ci.org/haml/haml)
 
-## Using
+Haml is a templating engine for HTML. It's designed to make it both easier and
+more pleasant to write HTML documents, by eliminating redundancy, reflecting the
+underlying structure that the document represents, and providing an elegant syntax
+that's both powerful and easy to understand.
 
-Haml can be used from the command line
-or as part of a Ruby web framework.
-The first step is to install the gem:
+## Basic Usage
+
+Haml can be used from the command line or as part of a Ruby web framework. The
+first step is to install the gem:
 
     gem install haml
 
-After you convert some HTML to Haml, you can run
+After you write some Haml, you can run
 
     haml document.haml
 
-to compile them.
-For more information on these commands, check out
+to compile it to HTML. For more information on these commands, check out
 
     haml --help
 
-To install Haml in Rails 2,
-just add `config.gem "haml"` to `config/environment.rb`.
-In Rails 3, add `gem "haml"` to your Gemfile instead.
-and both Haml and Sass will be installed.
-Views with the `.html.haml` extension will automatically use Haml.
+To use Haml programatically, check out the [YARD
+documentation](http://haml.info/docs/yardoc/).
+
+## Using Haml with Rails
+
+To use Haml with Rails, simply add Haml to your Gemfile and run `bundle`.
 
-To use Haml programatically,
-check out the [YARD documentation](http://haml-lang.com/docs/yardoc/).
+If you'd like to replace Rails's Erb-based generators with Haml, add
+[haml-rails](https://github.com/indirect/haml-rails) to your Gemfile as well.
 
 ## Formatting
 
-The most basic element of Haml
-is a shorthand for creating HTML:
+The most basic element of Haml is a shorthand for creating HTML:
 
     %tagname{:attr1 => 'value1', :attr2 => 'value2'} Contents
 
-No end-tag is needed; Haml handles that automatically.
-If you prefer HTML-style attributes, you can also use:
+No end-tag is needed; Haml handles that automatically. If you prefer HTML-style
+attributes, you can also use:
 
     %tagname(attr1='value1' attr2='value2') Contents
 
-Adding `class` and `id` attributes is even easier.
-Haml uses the same syntax as the CSS that styles the document:
+Adding `class` and `id` attributes is even easier. Haml uses the same syntax as
+the CSS that styles the document:
 
     %tagname#id.class
 
-In fact, when you're using the `<div>` tag,
-it becomes _even easier_.
-Because `<div>` is such a common element,
-a tag without a name defaults to a div. So
+In fact, when you're using the `<div>` tag, it becomes _even easier_. Because
+`<div>` is such a common element, a tag without a name defaults to a div. So
 
     #foo Hello!
 
@@ -61,11 +57,9 @@ becomes
 
     <div id='foo'>Hello!</div>
 
-Haml uses indentation
-to bring the individual elements to represent the HTML structure.
-A tag's children are indented beneath than the parent tag.
-Again, a closing tag is automatically added.
-For example:
+Haml uses indentation to bring the individual elements to represent the HTML
+structure. A tag's children are indented beneath than the parent tag. Again, a
+closing tag is automatically added. For example:
 
     %ul
       %li Salt
@@ -84,11 +78,9 @@ You can also put plain text as a child of an element:
       Hello,
       World!
 
-It's also possible to embed Ruby code into Haml documents.
-An equals sign, `=`, will output the result of the code.
-A hyphen, `-`, will run the code but not output the result.
-You can even use control statements
-like `if` and `while`:
+It's also possible to embed Ruby code into Haml documents. An equals sign, `=`,
+will output the result of the code. A hyphen, `-`, will run the code but not
+output the result. You can even use control statements like `if` and `while`:
 
     %p
       Date/Time:
@@ -97,37 +89,82 @@ like `if` and `while`:
       - if now > DateTime.parse("December 31, 2006")
         = "Happy new " + "year!"
 
-Haml provides far more tools than those presented here.
-Check out the [reference documentation](http://beta.haml-lang.com/docs/yardoc/file.HAML_REFERENCE.html)
+Haml provides far more tools than those presented here. Check out the [reference
+documentation](http://haml.info/docs/yardoc/file.REFERENCE.html)
 for full details.
 
 ### Indentation
 
-Haml's indentation can be made up of one or more tabs or spaces.
-However, indentation must be consistent within a given document.
-Hard tabs and spaces can't be mixed,
-and the same number of tabs or spaces must be used throughout.
+Haml's indentation can be made up of one or more tabs or spaces. However,
+indentation must be consistent within a given document. Hard tabs and spaces
+can't be mixed, and the same number of tabs or spaces must be used throughout.
+
+## Contributing
+
+Contributions are welcomed, but before you get started please read the
+[guidelines](http://haml.info/development.html#contributing).
+
+After forking and then cloning the repo locally, install Bundler and then use it
+to install the development gem dependecies:
+
+    gem install bundler
+    bundle install
+
+Once this is complete, you should be able to run the test suite:
+
+    rake
+
+You'll get a warning that you need to install haml-spec, so run this:
+
+    git submodule update --init
+
+At this point `rake` should run without error or warning and you are ready to
+start working on your patch!
+
+Note that you can also run just one test out of the test suite if you're working
+on a specific area:
+
+    ruby -Itest test/helper_test.rb -n test_buffer_access
+
+Haml supports Ruby 1.8.7 and higher, so please make sure your changes run on
+both 1.9 and 1.8.
 
 ## Authors
 
-Haml was created by [Hampton Catlin](http://hamptoncatlin.com)
-(hcatlin) and he is the author of the original implementation. However, Hampton
-doesn't even know his way around the code anymore and now occasionally consults
-on the language issues.  Hampton lives in Jacksonville, Florida and is the lead
-mobile developer for Wikimedia.
+Haml was created by [Hampton Catlin](http://hamptoncatlin.com), the author of
+the original implementation. However, Hampton doesn't even know his way around
+the code anymore and now just occasionally consults on the language issues.
 
-[Nathan Weizenbaum](http://nex-3.com) is the primary developer and architect of
-the "modern" Ruby implementation of Haml. His hard work has kept the project
-alive by endlessly answering forum posts, fixing bugs, refactoring, finding
-speed improvements, writing documentation, implementing new features, and
-getting Hampton coffee (a fitting task for a boy-genius). Nathan lives in
-Seattle, Washington and while not being a student at the University of
-Washington or working at an internship, he consults for Unspace Interactive.
+[Nathan Weizenbaum](http://nex-3.com) was for many years the primary developer
+and architect of the "modern" Ruby implementation of Haml. His hard work
+endlessly answering forum posts, fixing bugs, refactoring, finding speed
+improvements, writing documentation, and implementing new features is what has
+kept the project alive.
 
-If you use this software, you must pay Hampton a compliment. And
-buy Nathan some jelly beans. Maybe pet a kitten. Yeah. Pet that kitty.
+[Norman Clarke](http://github.com/norman), the author of Haml Spec and the Haml
+implementation in Lua, took over as maintainer in April 2012.
 
-Some of the work on Haml was supported by Unspace Interactive.
+## License
+
+Some of Nathan's work on Haml was supported by Unspace Interactive.
 
 Beyond that, the implementation is licensed under the MIT License.
-Okay, fine, I guess that means compliments aren't __required__.
+
+Copyright (c) 2006-2009 Hampton Catlin and Nathan Weizenbaum
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/REFERENCE.md

@@ -0,0 +1,1404 @@
+# Haml (XHTML Abstraction Markup Language)
+
+Haml is a markup language
+that's used to cleanly and simply describe the XHTML of any web document,
+without the use of inline code.
+Haml functions as a replacement
+for inline page templating systems such as PHP, ERB, and ASP.
+However, Haml avoids the need for explicitly coding XHTML into the template,
+because it is actually an abstract description of the XHTML,
+with some code to generate dynamic content.
+
+## Features
+
+* Whitespace active
+* Well-formatted markup
+* DRY
+* Follows CSS conventions
+* Integrates Ruby code
+* Implements Rails templates with the .haml extension
+
+## Using Haml
+
+Haml can be used in three ways:
+as a command-line tool,
+as a plugin for Ruby on Rails,
+and as a standalone Ruby module.
+The first step for all of these is to install the Haml gem:
+
+    gem install haml
+
+To run Haml from the command line, just use
+
+    haml input.haml output.html
+
+Use `haml --help` for full documentation.
+
+### Rails/Merb Plugin {#plugin}
+
+To enable Haml in Rails versions before Rails 3,
+add the following line to `environment.rb`:
+
+    config.gem "haml"
+
+For Rails 3, instead add the following line to the Gemfile:
+
+    gem "haml"
+
+Once it's installed, all view files with the `".html.haml"` extension
+will be compiled using Haml.
+Haml is enabled by default in Merb.
+
+You can access instance variables in Haml templates
+the same way you do in ERB templates.
+Helper methods are also available in Haml templates.
+For example (this example uses Rails, but the principle for Merb is the same):
+
+    # file: app/controllers/movies_controller.rb
+
+    class MoviesController < ApplicationController
+      def index
+        @title = "Teen Wolf"
+      end
+    end
+
+    -# file: app/views/movies/index.haml
+
+    #content
+     .title
+       %h1= @title
+       = link_to 'Home', home_url
+
+may be compiled to:
+
+    <div id='content'>
+      <div class='title'>
+        <h1>Teen Wolf</h1>
+        <a href='/'>Home</a>
+      </div>
+    </div>
+
+#### Rails XSS Protection
+
+Haml supports Rails' XSS protection scheme,
+which was introduced in Rails 2.3.5+ and is enabled by default in 3.0.0+.
+If it's enabled, Haml's [`:escape_html`](#escape_html-option)
+option is set to `true` by default -
+like in ERB, all strings printed to a Haml template are escaped by default.
+Also like ERB, strings marked as HTML safe are not escaped.
+Haml also has [its own syntax for printing a raw string to the template](#unescaping_html).
+
+If the `:escape_html` option is set to false when XSS protection is enabled,
+Haml doesn't escape Ruby strings by default.
+However, if a string marked HTML-safe is passed to [Haml's escaping syntax](#escaping_html),
+it won't be escaped.
+
+Finally, all the {Haml::Helpers Haml helpers} that return strings
+that are known to be HTML safe are marked as such.
+In addition, string input is escaped unless it's HTML safe.
+
+### Ruby Module
+
+Haml can also be used completely separately from Rails and ActionView.
+To do this, install the gem with RubyGems:
+
+    gem install haml
+
+You can then use it by including the "haml" gem in Ruby code,
+and using {Haml::Engine} like so:
+
+    engine = Haml::Engine.new("%p Haml code!")
+    engine.render #=> "<p>Haml code!</p>\n"
+
+### Options
+
+Options can be set by setting the {Haml::Template#options Haml::Template.options} hash
+in `environment.rb` in Rails...
+
+    Haml::Template.options[:format] = :html5
+
+...or by setting the `Merb::Plugin.config[:haml]` hash in `init.rb` in Merb...
+
+    Merb::Plugin.config[:haml][:format] = :html5
+
+...or by passing an options hash to {Haml::Engine#initialize}.
+Available options are:
+
+{#format-option} `:format`
+: Determines the output format. Normally the default is `:xhtml`,
+  although under Rails 3 it's `:html5`, since that's the Rails 3's default format.
+  Other options are `:html4` and `:html5`, which are
+  identical to `:xhtml` except there are no self-closing tags,
+  the XML prolog is ignored and correct DOCTYPEs are generated.
+  <br/><br/> <!-- There's no better way to do a paragraph break in a dl in Maruku -->
+  If the mime_type of the template being rendered is `text/xml` then
+  a format of `:xhtml` will be used even if the global output format
+  is set to `:html4` or `:html5`.
+
+{#escape_html-option} `:escape_html`
+: Sets whether or not to escape HTML-sensitive characters in script.
+  If this is true, `=` behaves like [`&=`](#escaping_html);
+  otherwise, it behaves like [`!=`](#unescaping_html).
+  Note that if this is set, `!=` should be used for yielding to subtemplates
+  and rendering partials.
+  See also [Escaping HTML](#escaping_html) and [Unescaping HTML](#unescaping_html)
+  Defaults to false.
+
+{#escape_attrs-option} `:escape_attrs`
+: Sets whether or not to escape HTML-sensitive characters in attributes.
+  If this is true, all HTML-sensitive characters in attributes are escaped.
+  If it's set to false, no HTML-sensitive characters in attributes are escaped.
+  If it's set to `:once`, existing HTML escape sequences are preserved,
+  but other HTML-sensitive characters are escaped.
+  Defaults to `:once`.
+
+{#ugly-option} `:ugly`
+: If set to `true`, Haml makes no attempt to properly
+  indent or format the HTML output.
+  This significantly improves rendering performance
+  but makes viewing the source unpleasant.
+  Defaults to `true` in Rails production mode, and `false`
+  everywhere else.
+
+{#suppress_eval-option} `:suppress_eval`
+: Whether or not attribute hashes and Ruby scripts
+  designated by `=` or `~` should be
+  evaluated. If this is `true`, said scripts are
+  rendered as empty strings. Defaults to `false`.
+
+{#attr_wrapper-option} `:attr_wrapper`
+: The character that should wrap element attributes.
+  This defaults to `'` (an apostrophe). Characters
+  of this type within the attributes will be escaped
+  (e.g. by replacing them with `&apos;`) if
+  the character is an apostrophe or a quotation mark.
+
+{#hyphenate_data_attrs} `:hyphenate_data_attrs`
+: If set to `true`, Haml will convert underscores to hyphens in all
+  [Custom Data Attributes](#html5_custom_data_attributes)
+  As of Haml 3.2, this defaults to `true`.
+
+{#filename-option} `:filename`
+: The name of the Haml file being parsed.
+  This is only used as information when exceptions are raised.
+  This is automatically assigned when working through ActionView,
+  so it's really only useful for the user to assign
+  when dealing with Haml programatically.
+
+{#line-option} `:line`
+: The line offset of the Haml template being parsed.
+  This is useful for inline templates,
+  similar to the last argument to `Kernel#eval`.
+
+{#autoclose-option} `:autoclose`
+: A list of tag names that should be automatically self-closed
+  if they have no content.
+  This can also contain regular expressions that match tag names
+  (or any object which responds to `#===`).
+  Defaults to `['meta', 'img', 'link', 'br', 'hr', 'input', 'area', 'param', 'col', 'base']`.
+
+{#preserve-option} `:preserve`
+: A list of tag names that should automatically have their newlines preserved
+  using the {Haml::Helpers#preserve} helper.
+  This means that any content given on the same line as the tag will be preserved.
+  For example, `%textarea= "Foo\nBar"` compiles to `<textarea>Foo&#x000A;Bar</textarea>`.
+  Defaults to `['textarea', 'pre']`.
+  See also [Whitespace Preservation](#whitespace_preservation).
+
+{#encoding-option} `:encoding`
+: The encoding to use for the HTML output.
+  Only available in Ruby 1.9 or higher.
+  This can be a string or an `Encoding` Object.
+  Note that Haml **does not** automatically re-encode Ruby values;
+  any strings coming from outside the application should be converted
+  before being passed into the Haml template.
+  Defaults to `Encoding.default_internal`; if that's not set,
+  defaults to the encoding of the Haml template;
+  if that's `us-ascii`, defaults to `"utf-8"`.
+  <br/><br/> <!-- There's no better way to do a paragraph break in a dl in Maruku -->
+  Many Ruby database drivers are not yet Ruby 1.9 compatible;
+  in particular, they return strings marked as ASCII-encoded
+  even when those strings contain non-ASCII characters (such as UTF-8).
+  **This will cause encoding errors** if the Haml encoding isn't set to `"ascii-8bit"`.
+  To solve this, either call `#force_encoding` on all the strings returned from the database,
+  set `:encoding` to `"ascii-8bit"`, or try to get the authors of the database drivers
+  to make them Ruby 1.9 compatible.
+
+### Encodings
+
+When using Ruby 1.9 or later,
+Haml supports the same sorts of encoding-declaration comments that Ruby does.
+Although both Ruby and Haml support several different styles,
+the easiest it just to add `-# coding: encoding-name`
+at the beginning of the Haml template
+(it must come before all other lines).
+This will tell Haml that the template is encoded using the named encoding.
+
+By default, the HTML generated by Haml has the same encoding as the Haml template.
+However, if `Encoding.default_internal` is set, Haml will attempt to use that instead.
+In addition, the [`:encoding` option](#encoding-option) can be used
+to specify an output encoding manually.
+
+Note that, like Ruby, Haml does not support templates encoded in UTF-16 or UTF-32,
+since these encodings are not compatible with ASCII.
+It is possible to use these as the output encoding, though.
+
+## Plain Text
+
+A substantial portion of any HTML document is its content,
+which is plain old text.
+Any Haml line that's not interpreted as something else
+is taken to be plain text, and passed through unmodified.
+For example:
+
+    %gee
+      %whiz
+        Wow this is cool!
+
+is compiled to:
+
+    <gee>
+      <whiz>
+        Wow this is cool!
+      </whiz>
+    </gee>
+
+Note that HTML tags are passed through unmodified as well.
+If you have some HTML you don't want to convert to Haml,
+or you're converting a file line-by-line,
+you can just include it as-is.
+For example:
+
+    %p
+      <div id="blah">Blah!</div>
+
+is compiled to:
+
+    <p>
+      <div id="blah">Blah!</div>
+    </p>
+
+### Escaping: `\`
+
+The backslash character escapes the first character of a line,
+allowing use of otherwise interpreted characters as plain text.
+For example:
+
+    %title
+      = @title
+      \= @title
+
+is compiled to:
+
+    <title>
+      MyPage
+      = @title
+    </title>
+
+## HTML Elements
+
+
+### Element Name: `%`
+
+The percent character is placed at the beginning of a line.
+It's followed immediately by the name of an element,
+then optionally by modifiers (see below), a space,
+and text to be rendered inside the element.
+It creates an element in the form of `<element></element>`.
+For example:
+
+    %one
+      %two
+        %three Hey there
+
+is compiled to:
+
+    <one>
+      <two>
+        <three>Hey there</three>
+      </two>
+    </one>
+
+Any string is a valid element name;
+Haml will automatically generate opening and closing tags for any element.
+
+### Attributes: `{}` or `()` {#attributes}
+
+Brackets represent a Ruby hash
+that is used for specifying the attributes of an element.
+It is literally evaluated as a Ruby hash,
+so logic will work in it and local variables may be used.
+Quote characters within the attribute
+will be replaced by appropriate escape sequences.
+The hash is placed after the tag is defined.
+For example:
+
+    %html{:xmlns => "http://www.w3.org/1999/xhtml", "xml:lang" => "en", :lang => "en"}
+
+is compiled to:
+
+    <html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'></html>
+
+Attribute hashes can also be stretched out over multiple lines
+to accommodate many attributes.
+However, newlines may only be placed immediately after commas.
+For example:
+
+    %script{:type => "text/javascript",
+            :src  => "javascripts/script_#{2 + 7}"}
+
+is compiled to:
+
+    <script src='javascripts/script_9' type='text/javascript'></script>
+
+#### `:class` and `:id` Attributes
+{#class-and-id-attributes}
+
+The `:class` and `:id` attributes can also be specified as a Ruby array
+whose elements will be joined together.
+A `:class` array is joined with `" "`
+and an `:id` array is joined with `"_"`.
+For example:
+
+    %div{:id => [@item.type, @item.number], :class => [@item.type, @item.urgency]}
+
+is equivalent to:
+
+    %div{:id => "#{@item.type}_#{@item.number}", :class => "#{@item.type} #{@item.urgency}"}
+
+The array will first be flattened
+and any elements that do not test as true will be removed.
+The remaining elements will be converted to strings.
+For example:
+
+    %div{:class => [@item.type, @item == @sortcol && [:sort, @sortdir]] } Contents
+
+could render as any of:
+
+    <div class="numeric sort ascending">Contents</div>
+    <div class="numeric">Contents</div>
+    <div class="sort descending">Contents</div>
+    <div>Contents</div>
+
+depending on whether `@item.type` is `"numeric"` or `nil`,
+whether `@item == @sortcol`,
+and whether `@sortdir` is `"ascending"` or `"descending"`.
+
+If a single value is specified and it evaluates to false it is ignored;
+otherwise it gets converted to a string.
+For example:
+
+    .item{:class => @item.is_empty? && "empty"}
+
+could render as either of:
+
+    class="item"
+    class="item empty"
+
+#### HTML-style Attributes: `()`
+
+Haml also supports a terser, less Ruby-specific attribute syntax
+based on HTML's attributes.
+These are used with parentheses instead of brackets, like so:
+
+    %html(xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en")
+
+Ruby variables can be used by omitting the quotes.
+Local variables or instance variables can be used.
+For example:
+
+    %a(title=@title href=href) Stuff
+
+This is the same as:
+
+    %a{:title => @title, :href => href} Stuff
+
+Because there are no commas separating attributes, though,
+more complicated expressions aren't allowed.
+For those you'll have to use the `{}` syntax.
+You can, however, use both syntaxes together:
+
+    %a(title=@title){:href => @link.href} Stuff
+
+You can also use `#{}` interpolation to insert complicated expressions
+in a HTML-style attribute:
+
+    %span(class="widget_#{@widget.number}")
+
+HTML-style attributes can be stretched across multiple lines
+just like hash-style attributes:
+
+    %script(type="text/javascript"
+            src="javascripts/script_#{2 + 7}")
+
+#### Attribute Methods
+
+A Ruby method call that returns a hash
+can be substituted for the hash contents.
+For example, {Haml::Helpers} defines the following method:
+
+    def html_attrs(lang = 'en-US')
+      {:xmlns => "http://www.w3.org/1999/xhtml", 'xml:lang' => lang, :lang => lang}
+    end
+
+This can then be used in Haml, like so:
+
+    %html{html_attrs('fr-fr')}
+
+This is compiled to:
+
+    <html lang='fr-fr' xml:lang='fr-fr' xmlns='http://www.w3.org/1999/xhtml'>
+    </html>
+
+You can use as many such attribute methods as you want
+by separating them with commas,
+like a Ruby argument list.
+All the hashes will me merged together, from left to right.
+For example, if you defined
+
+    def hash1
+      {:bread => 'white', :filling => 'peanut butter and jelly'}
+    end
+
+    def hash2
+      {:bread => 'whole wheat'}
+    end
+
+then
+
+    %sandwich{hash1, hash2, :delicious => true}/
+
+would compile to:
+
+    <sandwich bread='whole wheat' delicious='true' filling='peanut butter and jelly' />
+
+Note that the Haml attributes list has the same syntax as a Ruby method call.
+This means that any attribute methods must come before the hash literal.
+
+Attribute methods aren't supported for HTML-style attributes.
+
+#### Boolean Attributes
+
+Some attributes, such as "checked" for `input` tags or "selected" for `option` tags,
+are "boolean" in the sense that their values don't matter -
+it only matters whether or not they're present.
+In HTML (but not XHTML), these attributes can be written as
+
+    <input selected>
+
+To do this in Haml using hash-style attributes, just assign a Ruby
+`true` value to the attribute:
+
+    %input{:selected => true}
+
+In XHTML, the only valid value for these attributes is the name of the
+attribute.  Thus this will render in XHTML as
+
+    <input selected='selected'>
+
+To set these attributes to false, simply assign them to a Ruby false value.
+In both XHTML and HTML
+
+    %input{:selected => false}
+
+will just render as
+
+    <input>
+
+HTML-style boolean attributes can be written just like HTML:
+
+    %input(selected)
+
+or using `true` and `false`:
+
+    %input(selected=true)
+
+#### HTML5 Custom Data Attributes
+
+HTML5 allows for adding [custom non-visible data attributes](http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#embedding-custom-non-visible-data)
+to elements using attribute names beginning with `data-`.
+Custom data attributes can be used in Haml by using the key `:data` with a Hash value
+in an attribute hash.
+Each of the key/value pairs in the Hash will be transformed into a custom data attribute.
+For example:
+
+    %a{:href=>"/posts", :data => {:author_id => 123}} Posts By Author
+
+will render as:
+
+    <a data-author-id='123' href='/posts'>Posts By Author</a>
+
+Notice that the underscore in `author_id` was replaced by a hyphen. If you wish
+to suppress this behavior, you can set Haml's [`:hyphenate_data_attrs`
+option](#hyphenate_data_attrs-option) to `false`, and the output will be
+rendered as:
+
+    <a data-author_id='123' href='/posts'>Posts By Author</a>
+
+### Class and ID: `.` and `#`
+
+The period and pound sign are borrowed from CSS.
+They are used as shortcuts to specify the `class`
+and `id` attributes of an element, respectively.
+Multiple class names can be specified in a similar way to CSS,
+by chaining the class names together with periods.
+They are placed immediately after the tag and before an attributes hash.
+For example:
+
+    %div#things
+      %span#rice Chicken Fried
+      %p.beans{ :food => 'true' } The magical fruit
+      %h1.class.otherclass#id La La La
+
+is compiled to:
+
+    <div id='things'>
+      <span id='rice'>Chicken Fried</span>
+      <p class='beans' food='true'>The magical fruit</p>
+      <h1 class='class otherclass' id='id'>La La La</h1>
+    </div>
+
+And,
+
+    %div#content
+      %div.articles
+        %div.article.title Doogie Howser Comes Out
+        %div.article.date 2006-11-05
+        %div.article.entry
+          Neil Patrick Harris would like to dispel any rumors that he is straight
+
+is compiled to:
+
+    <div id='content'>
+      <div class='articles'>
+        <div class='article title'>Doogie Howser Comes Out</div>
+        <div class='article date'>2006-11-05</div>
+        <div class='article entry'>
+          Neil Patrick Harris would like to dispel any rumors that he is straight
+        </div>
+      </div>
+    </div>
+
+These shortcuts can be combined with long-hand attributes;
+the two values will be merged together
+as though they were all placed in an array
+(see [the documentation on `:class` and `:id` attributes](#class-and-id-attributes)).
+For example:
+
+    %div#Article.article.entry{:id => @article.number, :class => @article.visibility}
+
+is equivalent to
+
+    %div{:id => ['Article', @article.number], :class => ['article', 'entry', @article.visibility]} Gabba Hey
+
+and could compile to:
+
+    <div class="article entry visible" id="Article_27">Gabba Hey</div>
+
+#### Implicit Div Elements
+
+Because divs are used so often, they're the default elements.
+If you only define a class and/or id using `.` or `#`,
+a div is automatically used.
+For example:
+
+    #collection
+      .item
+        .description What a cool item!
+
+is the same as:
+
+    %div#collection
+      %div.item
+        %div.description What a cool item!
+
+and is compiled to:
+
+    <div id='collection'>
+      <div class='item'>
+        <div class='description'>What a cool item!</div>
+      </div>
+    </div>
+
+### Self-Closing Tags: `/`
+
+The forward slash character, when placed at the end of a tag definition,
+causes the tag to be self-closed.
+For example:
+
+    %br/
+    %meta{'http-equiv' => 'Content-Type', :content => 'text/html'}/
+
+is compiled to:
+
+    <br />
+    <meta http-equiv='Content-Type' content='text/html' />
+
+Some tags are automatically closed, as long as they have no content.
+`meta`, `img`, `link`, `script`, `br`, and `hr` tags are closed by default.
+This list can be customized by setting the [`:autoclose`](#autoclose-option) option.
+For example:
+
+    %br
+    %meta{'http-equiv' => 'Content-Type', :content => 'text/html'}
+
+is also compiled to:
+
+    <br />
+    <meta http-equiv='Content-Type' content='text/html' />
+
+### Whitespace Removal: `>` and `<`
+
+`>` and `<` give you more control over the whitespace near a tag.
+`>` will remove all whitespace surrounding a tag,
+while `<` will remove all whitespace immediately within a tag.
+You can think of them as alligators eating the whitespace:
+`>` faces out of the tag and eats the whitespace on the outside,
+and `<` faces into the tag and eats the whitespace on the inside.
+They're placed at the end of a tag definition,
+after class, id, and attribute declarations
+but before `/` or `=`.
+For example:
+
+    %blockquote<
+      %div
+        Foo!
+
+is compiled to:
+
+    <blockquote><div>
+      Foo!
+    </div></blockquote>
+
+And:
+
+    %img
+    %img>
+    %img
+
+is compiled to:
+
+    <img /><img /><img />
+
+And:
+
+    %p<= "Foo\nBar"
+
+is compiled to:
+
+    <p>Foo
+    Bar</p>
+
+And finally:
+
+    %img
+    %pre><
+      foo
+      bar
+    %img
+
+is compiled to:
+
+    <img /><pre>foo
+    bar</pre><img />
+
+### Object Reference: `[]`
+
+Square brackets follow a tag definition and contain a Ruby object
+that is used to set the class and id of that tag.
+The class is set to the object's class
+(transformed to use underlines rather than camel case)
+and the id is set to the object's class, followed by the value
+of its `#to_key` or `#id` method (in that order).
+This is most useful for elements that represent instances of Models.
+Additionally, the second argument (if present) will be used as a prefix for
+both the id and class attributes.
+For example:
+
+    # file: app/controllers/users_controller.rb
+
+    def show
+      @user = CrazyUser.find(15)
+    end
+
+    -# file: app/views/users/show.haml
+
+    %div[@user, :greeting]
+      %bar[290]/
+      Hello!
+
+is compiled to:
+
+    <div class='greeting_crazy_user' id='greeting_crazy_user_15'>
+      <bar class='fixnum' id='fixnum_581' />
+      Hello!
+    </div>
+
+If you require that the class be something other than the underscored
+object's class, you can implement the `haml_object_ref` method on the object.
+
+    # file: app/models/crazy_user.rb
+
+    class CrazyUser < ActiveRecord::Base
+      def haml_object_ref
+        "a_crazy_user"
+      end
+    end
+
+    -# file: app/views/users/show.haml
+
+    %div[@user]
+      Hello!
+
+is compiled to:
+
+    <div class='a_crazy_user' id='a_crazy_user_15'>
+      Hello!
+    </div>
+
+
+## Doctype: `!!!`
+
+When describing HTML documents with Haml,
+you can have a document type or XML prolog generated automatically
+by including the characters `!!!`.
+For example:
+
+    !!! XML
+    !!!
+    %html
+      %head
+        %title Myspace
+      %body
+        %h1 I am the international space station
+        %p Sign my guestbook
+
+is compiled to:
+
+    <?xml version='1.0' encoding='utf-8' ?>
+    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+    <html>
+      <head>
+        <title>Myspace</title>
+      </head>
+      <body>
+        <h1>I am the international space station</h1>
+        <p>Sign my guestbook</p>
+      </body>
+    </html>
+
+You can also specify the specific doctype after the `!!!`
+When the [`:format`](#format-option) is set to `:xhtml` (the default except in Rails 3),
+the following doctypes are supported:
+
+`!!!`
+: XHTML 1.0 Transitional<br/>
+ `<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">`
+
+`!!! Strict`
+: XHTML 1.0 Strict<br/>
+ `<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">`
+
+`!!! Frameset`
+: XHTML 1.0 Frameset<br/>
+ `<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">`
+
+`!!! 5`
+: XHTML 5<br/>
+ `<!DOCTYPE html>`<br/>
+
+`!!! 1.1`
+: XHTML 1.1<br/>
+ `<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">`
+
+`!!! Basic`
+: XHTML Basic 1.1<br/>
+ `<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd"> `
+
+`!!! Mobile`
+: XHTML Mobile 1.2<br/>
+ `<!DOCTYPE html PUBLIC "-//WAPFORUM//DTD XHTML Mobile 1.2//EN" "http://www.openmobilealliance.org/tech/DTD/xhtml-mobile12.dtd">`
+
+`!!! RDFa`
+: XHTML+RDFa 1.0<br/>
+ `<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.0//EN" "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-1.dtd">`
+
+When the [`:format`](#format-option) option is set to `:html4`,
+the following doctypes are supported:
+
+`!!!`
+: HTML 4.01 Transitional<br/>
+ `<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">`
+
+`!!! Strict`
+: HTML 4.01 Strict<br/>
+ `<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">`
+
+`!!! Frameset`
+: HTML 4.01 Frameset<br/>
+ `<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd">`
+
+When the [`:format`](#format-option) option is set to `:html5`,
+`!!!` is always `<!DOCTYPE html>`.
+
+If you're not using the UTF-8 character set for your document,
+you can specify which encoding should appear
+in the XML prolog in a similar way.
+For example:
+
+    !!! XML iso-8859-1
+
+is compiled to:
+
+    <?xml version='1.0' encoding='iso-8859-1' ?>
+
+If the mime_type of the template being rendered is `text/xml` then
+a format of `:xhtml` will be used even if the global output format
+is set to `:html4` or `:html5`.
+
+## Comments
+
+Haml supports two sorts of comments:
+those that show up in the HTML output
+and those that don't.
+
+### HTML Comments: `/`
+
+The forward slash character, when placed at the beginning of a line,
+wraps all text after it in an HTML comment.
+For example:
+
+    %peanutbutterjelly
+      / This is the peanutbutterjelly element
+      I like sandwiches!
+
+is compiled to:
+
+    <peanutbutterjelly>
+      <!-- This is the peanutbutterjelly element -->
+      I like sandwiches!
+    </peanutbutterjelly>
+
+The forward slash can also wrap indented sections of code. For example:
+
+    /
+      %p This doesn't render...
+      %div
+        %h1 Because it's commented out!
+
+is compiled to:
+
+    <!--
+      <p>This doesn't render...</p>
+      <div>
+        <h1>Because it's commented out!</h1>
+      </div>
+    -->
+
+#### Conditional Comments: `/[]`
+
+You can also use [Internet Explorer conditional comments](http://www.quirksmode.org/css/condcom.html)
+by enclosing the condition in square brackets after the `/`.
+For example:
+
+    /[if IE]
+      %a{ :href => 'http://www.mozilla.com/en-US/firefox/' }
+        %h1 Get Firefox
+
+is compiled to:
+
+    <!--[if IE]>
+      <a href='http://www.mozilla.com/en-US/firefox/'>
+        <h1>Get Firefox</h1>
+      </a>
+    <![endif]-->
+
+### Haml Comments: `-#`
+
+The hyphen followed immediately by the pound sign
+signifies a silent comment.
+Any text following this isn't rendered in the resulting document
+at all.
+
+For example:
+
+    %p foo
+    -# This is a comment
+    %p bar
+
+is compiled to:
+
+    <p>foo</p>
+    <p>bar</p>
+
+You can also nest text beneath a silent comment.
+None of this text will be rendered.
+For example:
+
+    %p foo
+    -#
+      This won't be displayed
+        Nor will this
+                       Nor will this.
+    %p bar
+
+is compiled to:
+
+    <p>foo</p>
+    <p>bar</p>
+
+## Ruby Evaluation
+
+### Inserting Ruby: `=`
+
+The equals character is followed by Ruby code.
+This code is evaluated and the output is inserted into the document.
+For example:
+
+    %p
+      = ['hi', 'there', 'reader!'].join " "
+      = "yo"
+
+is compiled to:
+
+    <p>
+      hi there reader!
+      yo
+    </p>
+
+If the [`:escape_html`](#escape_html-option) option is set, `=` will sanitize any
+HTML-sensitive characters generated by the script. For example:
+
+    = '<script>alert("I\'m evil!");</script>'
+
+would be compiled to
+
+    &lt;script&gt;alert(&quot;I'm evil!&quot;);&lt;/script&gt;
+
+`=` can also be used at the end of a tag to insert Ruby code within that tag.
+For example:
+
+    %p= "hello"
+
+would be compiled to
+
+    <p>hello</p>
+
+A line of Ruby code can be stretched over multiple lines
+as long as each line but the last ends with a comma.
+For example:
+
+    = link_to_remote "Add to cart",
+        :url => { :action => "add", :id => product.id },
+        :update => { :success => "cart", :failure => "error" }
+
+Note that it's illegal to nest code within a tag that ends with `=`.
+
+### Running Ruby: `-`
+
+The hyphen character is also followed by Ruby code.
+This code is evaluated but *not* inserted into the document.
+
+**It is not recommended that you use this widely;
+almost all processing code and logic should be restricted
+to the Controller, the Helper, or partials.**
+
+For example:
+
+    - foo = "hello"
+    - foo << " there"
+    - foo << " you!"
+    %p= foo
+
+is compiled to:
+
+    <p>
+      hello there you!
+    </p>
+
+A line of Ruby code can be stretched over multiple lines
+as long as each line but the last ends with a comma.
+For example:
+
+    - links = {:home => "/",
+        :docs => "/docs",
+        :about => "/about"}
+
+#### Ruby Blocks
+
+Ruby blocks, like XHTML tags, don't need to be explicitly closed in Haml.
+Rather, they're automatically closed, based on indentation.
+A block begins whenever the indentation is increased
+after a Ruby evaluation command.
+It ends when the indentation decreases
+(as long as it's not an `else` clause or something similar).
+For example:
+
+    - (42...47).each do |i|
+      %p= i
+    %p See, I can count!
+
+is compiled to:
+
+    <p>42</p>
+    <p>43</p>
+    <p>44</p>
+    <p>45</p>
+    <p>46</p>
+    <p>See, I can count!</p>
+
+Another example:
+
+    %p
+      - case 2
+      - when 1
+        = "1!"
+      - when 2
+        = "2?"
+      - when 3
+        = "3."
+
+is compiled to:
+
+    <p>
+      2?
+    </p>
+
+### Whitespace Preservation: `~` {#tilde}
+
+`~` works just like `=`, except that it runs {Haml::Helpers#find\_and\_preserve} on its input.
+For example,
+
+    ~ "Foo\n<pre>Bar\nBaz</pre>"
+
+is the same as:
+
+    = find_and_preserve("Foo\n<pre>Bar\nBaz</pre>")
+
+and is compiled to:
+
+    Foo
+    <pre>Bar&#x000A;Baz</pre>
+
+See also [Whitespace Preservation](#whitespace_preservation).
+
+### Ruby Interpolation: `#{}`
+
+Ruby code can also be interpolated within plain text using `#{}`,
+similarly to Ruby string interpolation.
+For example,
+
+    %p This is #{h quality} cake!
+
+is the same as
+
+    %p= "This is the #{h quality} cake!"
+
+and might compile to
+
+    <p>This is scrumptious cake!</p>
+
+Backslashes can be used to escape `#{}` strings,
+but they don't act as escapes anywhere else in the string.
+For example:
+
+    %p
+      Look at \\#{h word} lack of backslash: \#{foo}
+      And yon presence thereof: \{foo}
+
+might compile to
+
+    <p>
+      Look at \yon lack of backslash: #{foo}
+      And yon presence thereof: \{foo}
+    </p>
+
+Interpolation can also be used within [filters](#filters).
+For example:
+
+    :javascript
+      $(document).ready(function() {
+        alert(#{@message.to_json});
+      });
+
+might compile to
+
+    <script type='text/javascript'>
+      //<![CDATA[
+        $(document).ready(function() {
+          alert("Hi there!");
+        });
+      //]]>
+    </script>
+
+### Escaping HTML: `&=` {#escaping_html}
+
+An ampersand followed by one or two equals characters
+evaluates Ruby code just like the equals without the ampersand,
+but sanitizes any HTML-sensitive characters in the result of the code.
+For example:
+
+    &= "I like cheese & crackers"
+
+compiles to
+
+    I like cheese &amp; crackers
+
+If the [`:escape_html`](#escape_html-option) option is set,
+`&=` behaves identically to `=`.
+
+`&` can also be used on its own so that `#{}` interpolation is escaped.
+For example,
+
+    & I like #{"cheese & crackers"}
+
+compiles to
+
+    I like cheese &amp; crackers
+
+### Unescaping HTML: `!=` {#unescaping_html}
+
+An exclamation mark followed by one or two equals characters
+evaluates Ruby code just like the equals would,
+but never sanitizes the HTML.
+
+By default, the single equals doesn't sanitize HTML either.
+However, if the [`:escape_html`](#escape_html-option) option is set,
+`=` will sanitize the HTML, but `!=` still won't.
+For example, if `:escape_html` is set:
+
+    = "I feel <strong>!"
+    != "I feel <strong>!"
+
+compiles to
+
+    I feel &lt;strong&gt;!
+    I feel <strong>!
+
+`!` can also be used on its own so that `#{}` interpolation is unescaped.
+For example,
+
+    ! I feel #{"<strong>"}!
+
+compiles to
+
+    I feel <strong>!
+
+## Filters {#filters}
+
+The colon character designates a filter. This allows you to pass an indented
+block of text as input to another filtering program and add the result to the
+output of Haml. The syntax is simply a colon followed by the name of the filter.
+For example,
+
+    %p
+      :markdown
+        # Greetings
+
+        Hello, *World*
+
+is compiled to
+
+    <p>
+      <h1>Greetings</h1>
+
+      <p>Hello, <em>World</em></p>
+    </p>
+
+Filters can have Ruby code interpolated with `#{}`. For example,
+
+    - flavor = "raspberry"
+    #content
+      :textile
+        I *really* prefer _#{flavor}_ jam.
+
+is compiled to
+
+    <div id='content'>
+      <p>I <strong>really</strong> prefer <em>raspberry</em> jam.</p>
+    </div>
+
+Currently, filters ignore the [`:escape_html`](#escape_html-option) option. This
+means that `#{}` interpolation within filters is never HTML-escaped.
+
+The functionality of some filters such as Markdown can be provided by many
+different libraries. Usually you don't have to worry about this - you can just
+load the gem of your choice and Haml will automatically use it.
+
+However in some cases you may want to make Haml explicitly use a specific gem
+to be used by a filter. In these cases you can do this via Tilt, the library
+Haml uses to implement many filters:
+
+    Tilt.prefer Tilt::RedCarpetTemplate
+
+See the [Tilt documentation](https://github.com/rtomayko/tilt#fallback-mode) for
+more info.
+
+Haml comes with the following filters defined:
+
+{#cdata-filter}
+### `:cdata`
+Surrounds the filtered text with CDATA tags.
+
+{#coffee-filter}
+### `:coffee`
+Compiles the filtered text to Javascript using Cofeescript. You can also
+reference this filter as `:coffeescript`. This filter is implemented using
+Tilt.
+
+{#css-filter}
+### `:css`
+Surrounds the filtered text with `<style>` and CDATA tags. Useful for including
+inline CSS.
+
+{#erb-filter}
+### `:erb`
+Parses the filtered text with ERb, like an RHTML template. Not available if the
+[`:suppress_eval`](#suppress_eval-option) option is set to true. Embedded Ruby
+code is evaluated in the same context as the Haml template. This filter is
+implemented using Tilt.
+
+{#escaped-filter}
+### `:escaped`
+Works the same as plain, but HTML-escapes the text
+before placing it in the document.
+
+{#javascript-filter}
+### `:javascript`
+Surrounds the filtered text with `<script>` and CDATA tags.
+Useful for including inline Javascript.
+
+{#less-filter}
+### `:less`
+Parses the filtered text with [Less](http://lesscss.org/) to produce CSS output.
+This filter is implemented using Tilt.
+
+
+{#markdown-filter}
+### `:markdown`
+Parses the filtered text with
+[Markdown](http://daringfireball.net/projects/markdown). This filter is
+implemented using Tilt.
+
+{#maruku-filter}
+### `:maruku`
+Parses the filtered text with [Maruku](https://github.com/nex3/maruku), which
+has some non-standard extensions to Markdown.
+
+As of Haml 3.2, this filter is defined in [Haml
+contrib](https://github.com/haml/haml-contrib) but is loaded automatically for
+historical reasons. In future versions of Haml it will likely not be loaded by
+default. This filter is implemented using Tilt.
+
+{#plain-filter}
+### `:plain`
+Does not parse the filtered text. This is useful for large blocks of text
+without HTML tags, when you don't want lines starting with `.` or `-` to be
+parsed.
+
+{#preserve-filter}
+### `:preserve`
+Inserts the filtered text into the template with whitespace preserved.
+`preserve`d blocks of text aren't indented, and newlines are replaced with the
+HTML escape code for newlines, to preserve nice-looking output. See also
+[Whitespace Preservation](#whitespace_preservation).
+
+{#ruby-filter}
+### `:ruby`
+Parses the filtered text with the normal Ruby interpreter. All output sent to
+`$stdout`, like with `puts`, is output into the Haml document. Not available if
+the [`:suppress_eval`](#suppress_eval-option) option is set to true. The Ruby
+code is evaluated in the same context as the Haml template.
+
+{#sass-filter}
+### `:sass`
+Parses the filtered text with [Sass](http://sass-lang.com/) to produce CSS
+output. This filter is implemented using Tilt.
+
+{#scss-filter}
+### `:scss`
+Parses the filtered text with Sass like the `:sass` filter, but uses the newer
+SCSS syntax to produce CSS output. This filter is implemented using Tilt.
+
+{#textile-filter}
+### `:textile`
+Parses the filtered text with [Textile](http://www.textism.com/tools/textile).
+Only works if [RedCloth](http://redcloth.org) is installed.
+
+As of Haml 3.2, this filter is defined in [Haml
+contrib](https://github.com/haml/haml-contrib) but is loaded automatically for
+historical reasons. In future versions of Haml it will likely not be loaded by
+default. This filter is implemented using Tilt.
+
+### Custom Filters
+
+You can also define your own filters. See {Haml::Filters} for details.
+
+## Multiline: `|` {#multiline}
+
+The pipe character designates a multiline string.
+It's placed at the end of a line (after some whitespace)
+and means that all following lines that end with `|`
+will be evaluated as though they were on the same line.
+**Note that even the last line in the multiline block
+should end with `|`.**
+For example:
+
+    %whoo
+      %hoo= h(                       |
+        "I think this might get " +  |
+        "pretty long so I should " + |
+        "probably make it " +        |
+        "multiline so it doesn't " + |
+        "look awful.")               |
+      %p This is short.
+
+is compiled to:
+
+    <whoo>
+      <hoo>I think this might get pretty long so I should probably make it multiline so it doesn't look awful.</hoo>
+      <p>This is short</p>
+    </whoo>
+
+Using multiline declarations in Haml is intentionally awkward.
+This is designed to discourage people from putting lots and lots of Ruby code
+in their Haml templates.
+If you find yourself using multiline declarations, stop and think:
+could I do this better with a helper?
+
+Note that there are a few cases where it's useful to allow
+something to flow over onto multiple lines in a non-awkward manner.
+One of these is HTML attributes.
+Some elements just have lots of attributes,
+so you can wrap attributes without using `|` (see [Attributes](#attributes)).
+
+In addition, sometimes you need to call Ruby methods or declare data structures
+that just need a lot of template information.
+So data structures and  functions that require lots of arguments
+can be wrapped over multiple lines,
+as long as each line but the last ends in a comma
+(see [Inserting Ruby](#inserting_ruby_)).
+
+## Whitespace Preservation
+
+Sometimes you don't want Haml to indent all your text.
+For example, tags like `pre` and `textarea` are whitespace-sensitive;
+indenting the text makes them render wrong.
+
+Haml deals with this by "preserving" newlines before they're put into the document --
+converting them to the XHTML whitespace escape code, `&#x000A;`.
+Then Haml won't try to re-format the indentation.
+
+Literal `textarea` and `pre` tags automatically preserve content given through `=`.
+Dynamically-generated `textarea`s and `pre`s can't be preserved automatically,
+and so should be passed through {Haml::Helpers#find\_and\_preserve} or the [`~` command](#tilde),
+which has the same effect.
+
+Blocks of literal text can be preserved using the [`:preserve` filter](#preserve-filter).
+
+## Helpers
+
+Haml offers a bunch of helpers that are useful for doing stuff like preserving
+whitespace, creating nicely indented output for user-defined helpers, and other
+useful things. The helpers are all documented in the {Haml::Helpers} and
+{Haml::Helpers::ActionViewExtensions} modules.