Tilt Build Status Dependency Status

NOTE The following file documents the current release of Tilt (2.0). See https://github.com/rtomayko/tilt/tree/tilt-1 for documentation for Tilt 1.4.

Tilt is a thin interface over a bunch of different Ruby template engines in an attempt to make their usage as generic as possible. This is useful for web frameworks, static site generators, and other systems that support multiple template engines but don't want to code for each of them individually.


  • Custom template evaluation scopes / bindings
  • Ability to pass locals to template evaluation
  • Backtraces with correct filenames and line numbers
  • Template file caching and reloading
  • Fast, method-based template source compilation


Support for these template engines is included with the package:

Engine File Extensions Required Libraries
Asciidoctor .ad, .adoc, .asciidoc asciidoctor (>= 0.1.0)
ERB .erb, .rhtml none (included ruby stdlib)
InterpolatedString .str none (included ruby core)
Erubis .erb, .rhtml, .erubis erubis
Haml .haml haml
Less CSS .less less
Builder .builder builder
Liquid .liquid liquid
RDiscount .markdown, .mkd, .md rdiscount
Redcarpet .markdown, .mkd, .md redcarpet
BlueCloth .markdown, .mkd, .md bluecloth
Kramdown .markdown, .mkd, .md kramdown
Maruku .markdown, .mkd, .md maruku
RedCloth .textile redcloth
RDoc .rdoc rdoc
Radius .radius radius
Markaby .mab markaby
Nokogiri .nokogiri nokogiri
CoffeeScript .coffee coffee-script (+ javascript)
Creole (Wiki markup) .wiki, .creole creole
Yajl .yajl yajl-ruby
CSV .rcsv none (Ruby >= 1.9), fastercsv (Ruby < 1.9)

These template engines ship with their own Tilt integration:

Engine File Extensions Required Libraries
Slim .slim slim (>= 0.7)
Embedded JavaScript sprockets
Embedded CoffeeScript sprockets
JST sprockets
Org-mode .org org-ruby (>= 0.6.2)
Handlebars .hbs, handlebars tilt-handlebars

See TEMPLATES.md for detailed information on template engine options and supported features.

Basic Usage

Instant gratification:

require 'erb'
require 'tilt'
template = Tilt.new('templates/foo.erb')
output = template.render
=> "Hello world!"



require 'tilt/haml'
template = Tilt::HamlTemplate.new('templates/foo.haml')
output = template.render


require 'tilt/erb'
template = Tilt::ERBTemplate.new('templates/foo.erb')
joe = Person.find('joe')

If no scope is provided, the template is evaluated within the context of an object created with Object.new.


jane = Person.find('jane')


Hey <%= yield %>!

The block passed to render is called on yield:

template = Tilt::ERBTemplate.new('foo.erb')
template.render { 'Joe' }
# => "Hey Joe!"

Template Mappings

The Tilt::Mapping class includes methods for associating template implementation classes with filename patterns and for locating/instantiating template classes based on those associations.

The Tilt module has a global instance of Mapping that is populated with the table of template engines above.


 >> Tilt.register Tilt::ERBTemplate, 'bar'
 >> Tilt.new('views/foo.bar')
 => #<Tilt::ERBTemplate @file="views/foo.bar" ...>

Retrieving the template class for a file or file extension:

 >> Tilt['foo.bar']
 => Tilt::ERBTemplate
 >> Tilt['haml']
 => Tilt::HamlTemplate

Retrieving a list of template classes for a file:

>> Tilt.templates_for('foo.bar')
=> [Tilt::ERBTemplate]
>> Tilt.templates_for('foo.haml.bar')
=> [Tilt::ERBTemplate, Tilt::HamlTemplate]

The template class is determined by searching for a series of decreasingly specific name patterns. When creating a new template with Tilt.new('views/foo.html.erb'), we check for the following template mappings:

  1. views/foo.html.erb
  2. foo.html.erb
  3. html.erb
  4. erb


Tilt needs to know the encoding of the template in order to work properly:

Tilt will use Encoding.default_external as the encoding when reading external files. If you're mostly working with one encoding (e.g. UTF-8) we highly recommend setting this option. When providing a custom reader block (Tilt.new { custom_string }) you'll have ensure the string is properly encoded yourself.

Most of the template engines in Tilt also allows you to override the encoding using the :default_encoding-option:

tmpl = Tilt.new('hello.erb', :default_encoding => 'Big5')

Ultimately it's up to the template engine how to handle the encoding: It might respect :default_encoding, it might always assume it's UTF-8 (like CoffeeScript), or it can do its own encoding detection.

Template Compilation



