Themes Overview

Postleaf themes are built with Dust.js templates. Dust.js is an open source, modern templating engine designed to work well in JavaScript environments.

Templates are nothing more than plain old HTML with special {placeholders}. You can output data, add logic, and use helpers to do more advanced things, but let's start with the basics first.

Before we get into syntax, it's important to know that Postleaf makes certain data available to each template it renders. This is called the template context, and is discussed more in the templates section.


Dust.js has a very elegant syntax. If you're familiar with Handlebars or Twig, you'll be able to master Dust.js in no time.


To output data, simply surround the variable name with curly braces. If you're referencing an object's property, separate it with a dot.


It's that simple. Postleaf will automatically sanitize and output the appropriate content for you!


You can use conditionals, or if statements, by doing this:

  <img src="{image}">

Notice the syntax here. The opening brace is proceeded with a question mark and there's a closing tag that uses a forward slash to signify the end of the block.

You can create else blocks like this:

  <img src="{image}">
  No image


Sections are used to switch the context. Imagine a context that has an author object. I could output the author's info like this:

Hi, my name is {} and my email is {email}.

But this can get pretty verbose. By switching to the author context, I can reference properties more elegantly:

  Hi, my name is {name} and my email is {email}.

Notice the pound symbol that proceeds the opening curly brace and, once again, the closing tag with a forward slash.

If you're not sure if an object exists, you can use an {:else} block just like with a conditional:

  Hi, my name is {name} and my email is {email}.
  No author found


You can loop over a collection of items by creating a section that references it. Consider the following object:

users: [
{ name: 'Tom', email: '' },
{ name: 'Dick', email: '' },
{ name: 'Harry', email: '' }

You can loop through each user like this:

  Hello, {name}!<br>

This will output:

Hello, Tom!
Hello, Dick!
Hello, Harry!

Tip: when a collection contains objects, you can reference their properties with dot notation.


Comments have a simple syntax. They start with a curly bracket and an exclamation point, and end with the reverse. They can be single- or multi-line:

{! This is a comment !}

{! This is a long comment that
spans more than one line. !}


Helpers let you add additional logic and more robust features to your templates. For example, you can use the {@gt} helper to see if one value is greater than another. Or you can use the {@readingTime/} helper to display the number of minutes it will take the average user to read a post.

The syntax for helpers and a list of all available helpers in Postleaf can be found in the helpers section.


Filters are used to transform a variable before outputting it. You can use them to encode values and even to convert HTML to plain text.

The syntax for filters and a list of all available filters in Postleaf can be found in the filters section.


To learn more about Dust.js, check out these pages:

If you're building a theme, it will help quite a bit to look at the default theme's source.

Syntax Highlighting

If your editor doesn't support syntax highlighting for Dust.js, try searching for a plugin. Here are a few for some popular editors: