Tweet

Docs /  templates

Getting Started Templates Data Configuration Content Development

Templates Overview

Assemble allows use of either Lo-Dash or Handlebars templates, depending on where the templates are used.

Separation of Concerns

In general:

  • Lo-Dash templates are used for configuration and metadata. Lo-Dash may be used in the Gruntfile, JSON/YAML files, YAML front matter, etc.
  • Handlebars templates are used for content. These templates may be used in the content of pages or partials.

Note that there is one exception to this separation of concerns, and these two libs also make a great team when you use them together.

Lo-Dash templates

Syntax

A basic template looks like this:

title: <%= pkg.name %>

Usage

Lo-Dash templates can be used in:

  • Gruntfile
  • YAML/JSON files
  • YAML front matter of files (pages, partials, etc.)

However, Lo-Dash templates cannot be used in the "content of pages".

Assemble only limits where you can use Lo-Dash templates, beyond that you can do anything with Lo-Dash templates that you can do with JavaScript. Keep in mind, however, that the more logic you add to the YAML front matter of page for instance, the more complicated you make your pages and the more difficult your projects will be to maintain.

Handlebars templates

Syntax

A basic expression looks like this:

<h1>{{component.title}}</h1>

Usage: May be used only in the "content" of pages, e.g. anywhere but the YAML front matter of a page..

Although Handlebars is most often used for generating HTML, you can also generate JSON, XML, YAML, CSS, LESS, SASS and so on.

This keeps Lo-Dash templates focused on configuration(ish) data, or data that is used directly by the build process, and Handlebars focused on rendering content with as little logic as possible.

Templating Basics

Most templating languages share a few common features:

"Do"s and "Don't"s

Don't

// alert.json
{
  "message": "this is an alert from {{site.name}}"
}

Or this:

---
title: {{pkg.name}} # Oops! Can't use handlebars here!!!
---
<h1>{{title}}</h1>

Neither of those examples will because Handlebars templates can only be used outside of the YAML front matter.

This won't work either:

---
title: My Site
---
<h1><%= title %></h1>
Whoa! Nope, this won't work either. No Lo-Dash in the "content" part of the page!

Lo-Dash templates can only be used in the YAML front Matter (or in YAML/JSON files, or the Gruntfile).

Do

This works:

// alert.json
{
  "message": "this is an alert from <%= site.name %>"
}

This works too:

---
title: <% pkg.name %> # Nice!!! Assuming you are reading in the package.json in the Gruntfile, this works!
---
<h1>{{title}}</h1>
And this title will pull data from the YAML front matter. It's kind of like cheating, accept not.

So does this:

# alert.yml
modifier: alert-warning
strong: Be advised!
message: this is an alert from <%= site.name %> # pass in the site name

And then pass it to alert.hbs:

<div class="alert {{alert.modifier}}">
  <strong>{{ alert.strong }}</strong>{{ alert.message }}
</div>

See the template for this page →

Find an error? Let us know →