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>

Haml comes with the following filters defined:

  1. :cdata

    Surrounds the filtered text with CDATA tags.

  2. :coffee

    Compiles the filtered text to Javascript using Cofeescript. You can also reference this filter as :coffeescript. This filter is implemented using Tilt.

  3. :css

    Surrounds the filtered text with <style> and (optionally) CDATA tags. Useful for including inline CSS. Use the :cdata option to control when CDATA tags are added.

  4. :erb

    Parses the filtered text with ERb, like an RHTML template. Not available if the :suppress_eval option is set to true. Embedded Ruby code is evaluated in the same context as the Haml template. This filter is implemented using Tilt.

  5. :escaped

    Works the same as plain, but HTML-escapes the text before placing it in the document.

  6. :javascript

    Surrounds the filtered text with <script> and (optionally) CDATA tags. Useful for including inline Javascript. Use the :cdata option to control when CDATA tags are added.

  7. :less

    Parses the filtered text with Less to produce CSS output. This filter is implemented using Tilt.

  8. :markdown

    Parses the filtered text with Markdown. This filter is implemented using Tilt.

  9. :maruku

    Parses the filtered text with Maruku, which has some non-standard extensions to Markdown.

    As of Haml 4.0, this filter is defined in 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.

  10. :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.

  11. :preserve

    Inserts the filtered text into the template with whitespace preserved. preserved 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.

  12. :ruby

    Parses the filtered text with the normal Ruby interpreter. Creates an IO object named haml_io, anything written to it is output into the Haml document. Not available if the :suppress_eval option is set to true. The Ruby code is evaluated in the same context as the Haml template.

  13. :sass

    Parses the filtered text with Sass to produce CSS output. This filter is implemented using Tilt.

  14. :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.

  15. :textile

    Parses the filtered text with Textile. Only works if RedCloth is installed.

    As of Haml 4.0, this filter is defined in 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.

Casiano Rodriguez León 2015-06-18