Choose Your Engine
Bridgetown’s primary template language is Liquid, due to historical reasons (its heritage coming from Jekyll) and well as Liquid’s simple syntax and safe execution context making it ideal for designer-led template creation.
However, starting in v0.18, you can configure Bridgetown to use ERB as its primary template engine, and in addition you can specify your preferred template engine (including even Haml or Slim) on a per-file basis.
Liquid is a great way to start out if you’re not that familiar with Ruby, because it feels more akin to template engines like Mustache, Jinja, Nunjucks, Twig, and so forth. Simple tags and filters, along with loops and conditional statements, let you construct templates quickly and easily.
But if you need more power (especially when writing components) or you’re already familiar with Ruby and engines such as ERB, then the cognitive overhead to learn and stick with Liquid can actually become a hindrance. In addition, it’s an important goal for Bridgetown to integrate well with a development workflow which already incorporates the Ruby on Rails framework. Or perhaps you’re looking to switch from Middleman which uses ERB by default.
In any case, the ability to “pick your flavor” of template engines on a site-by-site or file-by-file basis is now one of Bridgetown’s core strengths as a web framework.
Per-file Engine Configuration
When the default Liquid template engine is configured, Bridgetown processes files through Liquid even when they don’t have a
.liquid extension. For example,
authors.html will all get processed through Liquid during the build process.
As an initial step, you can use a different template engine based on extension alone. For example,
authors.erb would get processed through ERB and output as
authors.html. But there are a couple of drawbacks to that approach. If you wanted
posts.erb to be output as
posts.json, you’d have to manually set a
permalink in your front matter. In addition, if you wanted to write a document in Markdown but add ERB tags in as well, you couldn’t do that via file extension alone because the Markdown converter looks for files ending in
So instead of doing that, you can switch template engines directly. All you need to do is use the
template_engine front matter variable. You can do this on any page, document, or layout. For example, you could write
posts.json but add
template_engine: erb to the front matter, and then you’d be all set. Write your template using ERB syntax, get
posts.json on output. In the Markdown scenario, you could still author
about.md while adding ERB tags to the content, and it would work exactly as you expect.
Front Matter Defaults
template_engine directly in your file’s front matter, you could use front matter defaults to specify a template engine for a folder or folder tree or files which match a particular “glob pattern”. That way you could, say, use Liquid for most of the site but use ERB just for a certain group of files.
Most likely, however, you’ll want to switch your site wholesale from one engine to another. That’s where
bridgetown.config.yml comes in. Simply add
template_engine: erb right in your config, and suddenly everything will get processed through ERB regardless of file extension. Write HTML, XML, Markdown, JSON, CSV, whatever you like—and still access the full power of your Ruby template language of choice. You don’t even need to give up on Liquid completely—just save files with
.liquid or use
template_engine: liquid front matter.
It’s Up to You
Regardless of which template engine you pick, whether it’s Liquid or ERB or something else, Bridgetown has got you covered. We continue to look for ways to make switching engines easier while reducing the number of “sharp edges” that can arise to differences in how various template engines process content, so please don’t hesitate to let us know if you run in to any issues.