README.md

Tilt

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.

The following features are supported for all template engines (assuming the
feature is relevant to the engine):

Custom template evaluation scopes / bindings

Ability to pass locals to template evaluation

Support for passing a block to template evaluation for "yield"

Backtraces with correct filenames and line numbers

Template file caching and reloading

Fast, method-based template source compilation

The primary goal is to get all of the things listed above right for all
template engines included in the distribution.

Support for these template engines is included with the package:

Engine

File Extensions

Required Libraries

Maintainer

Asciidoctor

.ad, .adoc, .asciidoc

asciidoctor (>= 0.1.0)

Community

ERB

.erb, .rhtml

none (included ruby stdlib)

Tilt team

InterpolatedString

.str

none (included ruby core)

Tilt team

Erubi

.erb, .rhtml, .erubi

erubi

Community

Erubis

.erb, .rhtml, .erubis

erubis

Tilt team

Haml

.haml

haml

Tilt team

Sass

.sass

haml (< 3.1) or sass (>= 3.1)

Tilt team

Scss

.scss

haml (< 3.1) or sass (>= 3.1)

Tilt team

Less CSS

.less

less

Tilt team

Builder

.builder

builder

Tilt team

Liquid

.liquid

liquid

Community

RDiscount

.markdown, .mkd, .md

rdiscount

Community

Redcarpet

.markdown, .mkd, .md

redcarpet

Community

BlueCloth

.markdown, .mkd, .md

bluecloth

Community

Kramdown

.markdown, .mkd, .md

kramdown

Community

Pandoc

.markdown, .mkd, .md

pandoc

Community

reStructuredText

.rst

pandoc

Community

Maruku

.markdown, .mkd, .md

maruku

Community

CommonMarker

.markdown, .mkd, .md

commonmarker

Community

RedCloth

.textile

redcloth

Community

RDoc

.rdoc

rdoc

Tilt team

Radius

.radius

radius

Community

Markaby

.mab

markaby

Tilt team

Nokogiri

.nokogiri

nokogiri

Community

CoffeeScript

.coffee

coffee-script (+ javascript)

Tilt team

CoffeeScript (literate)

.litcoffee

coffee-script (>= 1.5.0) (+ javascript)

Tilt team

LiveScript

.ls

livescript (+ javascript)

Tilt team

TypeScript

.ts

typescript (+ javascript)

Tilt team

Creole (Wiki markup)

.wiki, .creole

creole

Community

WikiCloth (Wiki markup)

.wiki, .mediawiki, .mw

wikicloth

Community

Yajl

.yajl

yajl-ruby

Community

CSV

.rcsv

none (Ruby >= 1.9), fastercsv (Ruby < 1.9)

Tilt team

Prawn

.prawn

prawn (>= 2.0.0)

Community

Babel

.es6, .babel, .jsx

babel-transpiler

Tilt team

Opal

.rb

opal

Community

Sigil

.sigil

sigil

Community

Every supported template engine has a maintainer. Note that this is the
maintainer of the Tilt integration, not the maintainer of the template engine
itself. The maintainer is responsible for providing an adequate integration and
keeping backwards compatibility across Tilt version. Some integrations are
maintained by the community, which is handled in the following way:

The Tilt team will liberally accept pull requests against the template
integration. It's up to the community as a whole to make sure the integration
stays consistent and backwards compatible over time.

Test failures in community-maintained integrations will not be prioritized by
the Tilt team and a new version of Tilt might be released even though these
tests are failing.

Anyone can become a maintainer for a template engine integration they care
about. Just open an issue and we'll figure it out.

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

Jbuilder

.jbuilder

tilt-jbuilder

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

Basic Usage

It's recommended that calling programs explicitly require template engine
libraries (like 'erb' above) at load time. Tilt attempts to lazy require the
template engine library the first time a template is created but this is
prone to error in threaded environments.

The {Tilt} module contains generic implementation classes for all supported
template engines. Each template class adheres to the same interface for
creation and rendering. In the instant gratification example, we let Tilt
determine the template implementation class based on the filename, but
{Tilt::Template} implementations can also be used directly:

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

A single Template instance's render method may be called multiple times
with different scope and locals arguments. Continuing the previous example,
we render the same compiled template but this time in jane's scope:

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:

views/foo.html.erb

foo.html.erb

html.erb

erb

Encodings

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

Tilt compiles generated Ruby source code produced by template engines and reuses
it on subsequent template invocations. Benchmarks show this yields a 5x-10x
performance increase over evaluating the Ruby source on each invocation.