{"id":13463246,"url":"https://github.com/rtomayko/tilt","last_synced_at":"2025-04-14T08:52:29.088Z","repository":{"id":490997,"uuid":"117302","full_name":"rtomayko/tilt","owner":"rtomayko","description":"Generic interface to multiple Ruby template engines","archived":false,"fork":false,"pushed_at":"2023-12-29T08:13:39.000Z","size":984,"stargazers_count":1948,"open_issues_count":6,"forks_count":224,"subscribers_count":35,"default_branch":"master","last_synced_at":"2025-04-07T01:08:30.926Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://github.com/rtomayko/tilt","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rtomayko.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2009-01-29T13:49:29.000Z","updated_at":"2025-04-05T11:26:12.000Z","dependencies_parsed_at":"2023-01-13T10:23:17.676Z","dependency_job_id":"ee29d769-1cac-4400-a47a-e709fee0dff0","html_url":"https://github.com/rtomayko/tilt","commit_stats":{"total_commits":744,"total_committers":112,"mean_commits":6.642857142857143,"dds":0.6720430107526882,"last_synced_commit":"9e2dba10cfd7a11b8e7b2b8f6214ad85ef2caac7"},"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rtomayko%2Ftilt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rtomayko%2Ftilt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rtomayko%2Ftilt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rtomayko%2Ftilt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rtomayko","download_url":"https://codeload.github.com/rtomayko/tilt/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248852078,"owners_count":21171838,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T13:00:48.882Z","updated_at":"2025-04-14T08:52:29.059Z","avatar_url":"https://github.com/rtomayko.png","language":"Ruby","readme":"Tilt [![Test suite](https://github.com/rtomayko/tilt/actions/workflows/test.yml/badge.svg)](https://github.com/rtomayko/tilt/actions/workflows/test.yml) [![Inline docs](http://inch-ci.org/github/rtomayko/tilt.svg)](http://inch-ci.org/github/rtomayko/tilt)\n====\n\nTilt is a thin interface over a bunch of different Ruby template engines in\nan attempt to make their usage as generic as possible. This is useful for web\nframeworks, static site generators, and other systems that support multiple\ntemplate engines but don't want to code for each of them individually.\n\nThe following features are supported for all template engines (assuming the\nfeature is relevant to the engine):\n\n * Custom template evaluation scopes / bindings\n * Ability to pass locals to template evaluation\n * Support for passing a block to template evaluation for \"yield\"\n * Backtraces with correct filenames and line numbers\n * Template file caching and reloading\n * Fast, method-based template source compilation\n\nThe primary goal is to get all of the things listed above right for all\ntemplate engines included in the distribution.\n\nSupport for these template engines is included with the package:\n\n| Engine                  | File Extensions        | Required Libraries                         | Maintainer  |\n| ----------------------- | ---------------------- | ------------------------------------------ | ----------- |\n| Asciidoctor             | .ad, .adoc, .asciidoc  | asciidoctor (\u003e= 0.1.0)                     | Community   |\n| ERB                     | .erb, .rhtml           | none (included ruby stdlib)                | Tilt team   |\n| InterpolatedString      | .str                   | none (included ruby core)                  | Tilt team   |\n| Erubi                   | .erb, .rhtml, .erubi   | erubi                                      | Community   |\n| Erubis                  | .erb, .rhtml, .erubis  | erubis                                     | Tilt team   |\n| Haml                    | .haml                  | haml                                       | Tilt team   |\n| Sass                    | .sass                  | sass-embedded (\u003e= 1.0) or sassc (\u003e=2.0)    | Tilt team   |\n| Scss                    | .scss                  | sass-embedded (\u003e= 1.0) or sassc (\u003e=2.0)    | Tilt team   |\n| Builder                 | .builder               | builder                                    | Tilt team   |\n| Liquid                  | .liquid                | liquid                                     | Community   |\n| RDiscount               | .markdown, .mkd, .md   | rdiscount                                  | Community   |\n| Redcarpet               | .markdown, .mkd, .md   | redcarpet                                  | Community   |\n| Kramdown                | .markdown, .mkd, .md   | kramdown                                   | Community   |\n| Pandoc                  | .markdown, .mkd, .md   | pandoc                                     | Community   |\n| reStructuredText        | .rst                   | pandoc                                     | Community   |\n| Maruku                  | .markdown, .mkd, .md   | maruku                                     | Community   |\n| CommonMarker            | .markdown, .mkd, .md   | commonmarker                               | Community   |\n| RedCloth                | .textile               | redcloth                                   | Community   |\n| RDoc                    | .rdoc                  | rdoc                                       | Tilt team   |\n| Radius                  | .radius                | radius                                     | Community   |\n| Markaby                 | .mab                   | markaby                                    | Tilt team   |\n| Nokogiri                | .nokogiri              | nokogiri                                   | Community   |\n| CoffeeScript            | .coffee                | coffee-script (+ javascript)               | Tilt team   |\n| CoffeeScript (literate) | .litcoffee             | coffee-script (\u003e= 1.5.0) (+ javascript)    | Tilt team   |\n| LiveScript              | .ls                    | livescript (+ javascript)                  | Tilt team   |\n| TypeScript              | .ts                    | typescript (+ javascript)                  | Tilt team   |\n| Creole (Wiki markup)    | .wiki, .creole         | creole                                     | Community   |\n| WikiCloth (Wiki markup) | .wiki, .mediawiki, .mw | wikicloth                                  | Community   |\n| Yajl                    | .yajl                  | yajl-ruby                                  | Community   |\n| CSV                     | .rcsv                  | none (included ruby stdlib)                | Tilt team   |\n| Prawn                   | .prawn                 | prawn (\u003e= 2.0.0)                           | Community   |\n| Babel                   | .es6, .babel, .jsx     | babel-transpiler                           | Tilt team   |\n| Opal                    | .rb                    | opal                                       | Community   |\n\nEvery supported template engine has a *maintainer*. Note that this is the\nmaintainer of the Tilt integration, not the maintainer of the template engine\nitself. The maintainer is responsible for providing an adequate integration and\nkeeping backwards compatibility across Tilt version. Some integrations are\nmaintained by the *community*, which is handled in the following way:\n\n- The Tilt team will liberally accept pull requests to update existing\n  community-maintained template integrations. It's up to the community as a\n  whole to make sure the integration stays consistent and backwards compatible\n  over time.\n- Test failures in community-maintained integrations will not be prioritized by\n  the Tilt team and a new version of Tilt might be released even though these\n  tests are failing.\n- Anyone can become a maintainer for a template engine integration they care\n  about. Just open an issue and we'll figure it out.\n- The Tilt team is no longer accepting new community-maintained template\n  integrations.\n\nThese template engines ship with their own Tilt integration:\n\n| Engine                | File Extensions  | Required Libraries  |\n| -------------------   | ---------------- | ------------------- |\n| Slim                  | .slim            | slim (\u003e= 0.7)       |\n| Embedded JavaScript   |                  | sprockets           |\n| Embedded CoffeeScript |                  | sprockets           |\n| JST                   |                  | sprockets           |\n| Org-mode              | .org             | org-ruby (\u003e= 0.6.2) |\n| Emacs Org             | .org             | tilt-emacs_org      |\n| Handlebars            | .hbs, handlebars | tilt-handlebars     |\n| Jbuilder              | .jbuilder        | tilt-jbuilder       |\n\nSee [TEMPLATES.md][t] for detailed information on template engine\noptions and supported features.\n\n[t]: http://github.com/rtomayko/tilt/blob/master/docs/TEMPLATES.md\n   \"Tilt Template Engine Documentation\"\n\nBasic Usage\n-----------\n\nInstant gratification:\n\n~~~ruby\nrequire 'erb'\nrequire 'tilt'\ntemplate = Tilt.new('templates/foo.erb')\n=\u003e #\u003cTilt::ERBTemplate @file=\"templates/foo.erb\" ...\u003e\noutput = template.render\n=\u003e \"Hello world!\"\n~~~\n\nIt's recommended that calling programs explicitly require template engine\nlibraries (like 'erb' above) at load time. Tilt attempts to lazy require the\ntemplate engine library the first time a template is created but this is\nprone to error in threaded environments.\n\nThe {Tilt} module contains generic implementation classes for all supported\ntemplate engines. Each template class adheres to the same interface for\ncreation and rendering. In the instant gratification example, we let Tilt\ndetermine the template implementation class based on the filename, but\n{Tilt::Template} implementations can also be used directly:\n\n~~~ruby\nrequire 'tilt/haml'\ntemplate = Tilt::HamlTemplate.new('templates/foo.haml')\noutput = template.render\n~~~\n\nThe `render` method takes an optional evaluation scope and locals hash\narguments. Here, the template is evaluated within the context of the\n`Person` object with locals `x` and `y`:\n\n~~~ruby\nrequire 'tilt/erb'\ntemplate = Tilt::ERBTemplate.new('templates/foo.erb')\njoe = Person.find('joe')\noutput = template.render(joe, :x =\u003e 35, :y =\u003e 42)\n~~~\n\nIf no scope is provided, the template is evaluated within the context of an\nobject created with `Object.new`.\n\nA single `Template` instance's `render` method may be called multiple times\nwith different scope and locals arguments. Continuing the previous example,\nwe render the same compiled template but this time in jane's scope:\n\n~~~ruby\njane = Person.find('jane')\noutput = template.render(jane, :x =\u003e 22, :y =\u003e nil)\n~~~\n\nBlocks can be passed to `render` for templates that support running\narbitrary ruby code (usually with some form of `yield`). For instance,\nassuming the following in `foo.erb`:\n\n~~~ruby\nHey \u003c%= yield %\u003e!\n~~~\n\nThe block passed to `render` is called on `yield`:\n\n~~~ruby\ntemplate = Tilt::ERBTemplate.new('foo.erb')\ntemplate.render { 'Joe' }\n# =\u003e \"Hey Joe!\"\n~~~\n\nTemplate Mappings\n-----------------\n\nThe {Tilt::Mapping} class includes methods for associating template\nimplementation classes with filename patterns and for locating/instantiating\ntemplate classes based on those associations.\n\nThe {Tilt} module has a global instance of `Mapping` that is populated with the\ntable of template engines above.\n\nThe {Tilt.register} method associates a filename pattern with a specific\ntemplate implementation. To use ERB for files ending in a `.bar` extension:\n\n~~~ruby\n\u003e\u003e Tilt.register Tilt::ERBTemplate, 'bar'\n\u003e\u003e Tilt.new('views/foo.bar')\n=\u003e #\u003cTilt::ERBTemplate @file=\"views/foo.bar\" ...\u003e\n~~~\n\nRetrieving the template class for a file or file extension:\n\n~~~ruby\n\u003e\u003e Tilt['foo.bar']\n=\u003e Tilt::ERBTemplate\n\u003e\u003e Tilt['haml']\n=\u003e Tilt::HamlTemplate\n~~~\n\nRetrieving a list of template classes for a file:\n\n~~~ruby\n\u003e\u003e Tilt.templates_for('foo.bar')\n=\u003e [Tilt::ERBTemplate]\n\u003e\u003e Tilt.templates_for('foo.haml.bar')\n=\u003e [Tilt::ERBTemplate, Tilt::HamlTemplate]\n~~~\n\nThe template class is determined by searching for a series of decreasingly\nspecific name patterns. When creating a new template with\n`Tilt.new('views/foo.html.erb')`, we check for the following template\nmappings:\n\n  1. `views/foo.html.erb`\n  2. `foo.html.erb`\n  3. `html.erb`\n  4. `erb`\n\nEncodings\n---------\n\nTilt needs to know the encoding of the template in order to work properly:\n\nTilt will use `Encoding.default_external` as the encoding when reading external\nfiles. If you're mostly working with one encoding (e.g. UTF-8) we *highly*\nrecommend setting this option. When providing a custom reader block (`Tilt.new\n{ custom_string }`) you'll have ensure the string is properly encoded yourself.\n\nMost of the template engines in Tilt also allows you to override the encoding\nusing the `:default_encoding`-option:\n\n~~~ruby\ntmpl = Tilt.new('hello.erb', :default_encoding =\u003e 'Big5')\n~~~\n\nUltimately it's up to the template engine how to handle the encoding: It might\nrespect `:default_encoding`, it might always assume it's UTF-8 (like\nCoffeeScript), or it can do its own encoding detection.\n\nTemplate Compilation\n--------------------\n\nTilt compiles generated Ruby source code produced by template engines and reuses\nit on subsequent template invocations. Benchmarks show this yields a 5x-10x\nperformance increase over evaluating the Ruby source on each invocation.\n\nTemplate compilation is currently supported for these template engines:\nStringTemplate, ERB, Erubis, Erubi, Haml, Nokogiri, Builder and Yajl.\n\nLICENSE\n-------\n\nTilt is Copyright (c) 2010 [Ryan Tomayko](http://tomayko.com/about) and\ndistributed under the MIT license. See the `COPYING` file for more info.\n","funding_links":[],"categories":["HTML \u0026 Markup","Ruby","Template Engine","Gems"],"sub_categories":["Template Engines","Template engines"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frtomayko%2Ftilt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frtomayko%2Ftilt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frtomayko%2Ftilt/lists"}