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.

Syntax

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.

References

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

{title}
{author.name}

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

Conditionals

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

{?image}
  <img src="{image}">
{/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:

{?image}
  <img src="{image}">
{:else}
  No image
{/image}

Sections

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 {author.name} and my email is {email}.

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

{#author}
  Hi, my name is {name} and my email is {email}.
{/author}

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:

{#author}
  Hi, my name is {name} and my email is {email}.
{:else}
  No author found
{/author}

Looping

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

{
users: [
{ name: 'Tom', email: 'tom@example.com' },
{ name: 'Dick', email: 'dick@example.com' },
{ name: 'Harry', email: 'harry@example.com' }
]
}

You can loop through each user like this:

{#users}
  Hello, {name}!<br>
{/users}

This will output:

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

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

Comments

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

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

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.

Resources

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: