Maizzle

Templates

Templates in Maizzle contain the body of your email templates.

They're made up of two distinct sections:

  1. Front Matter
  2. Nunjucks blocks

Front Matter

Templates can override environment config variables and even define new ones, through YAML-style Front Matter.

It looks like this:

---
title: "Please confirm your email address"
isClimateChangeReal: true
---

Each of those variables will be available under the page object, which means you can use Nunjucks to render them in your Templates, like this:

<p>{{ page.title }}</p>

Nunjucks Blocks

For a Layout to render a Template's body, that body must be wrapped in a Nunjucks block that has the same name in both the Template and the Layout.

In Maizzle, we named it template:

{% block template %}
<table>
  <tr>
    <td>...</td>
  </tr>
</table>
{% endblock %}

Everything that is inside that block will be output into the Template's Layout, wherever a {% block template %}{% endblock %} is found.

Multiple Blocks

Your Templates can use as many blocks as you need.

For example, Maizzle uses a head block in its master Layout, allowing you to insert additional tags into the <head>, right from the Template.

Extending Layouts

A Template can specify a Layout to extend, in Front Matter:

---
layout: "src/layouts/custom.njk"
---

The value must be a path relative to the root of the project.

Default Layout

You don't have to explicitly extend a Layout.

If no layout key is found in Front Matter, Maizzle will try to use the Layout defined in your environment config:

// config.js
module.exports = {
  build: {
    layout: 'src/layouts/master.njk',
    // ...
  }
  // ...
}

Likewise, if build.layout points to a file that doesn't exist, the build will fail.

How Extending Works

When a Template extends a Layout, the {% block template %}{% endblock %} section in the Layout being extended is replaced with the contents of the Template's own {% block template %}.

Read more about template inheritance, in the Nunjucks docs ↗

Extending Templates

A Template can also extend another Template 🤯

For example, imagine src/templates/first.njk :

---
layout: src/layouts/default.njk
---

{% block template %}
Parent Template
{% block button %}First{% endblock %}
{% endblock %}

We could then extend it in src/templates/second.njk :

---
layout: src/templates/first.njk
---

{% block template %}
{% block button %}Second{% endblock %}
{% endblock %}

Inheritance Gotchas

1. When extending a Template from another Template, you must always specify the layout you're extending - in both templates.

2. You must always use the template keyword for your main template block: both in all Templates that extend a Template, and in your Layout.

So this works:

---
layout: src/templates/first.njk
---

{% block template %}
 # ...
{% endblock %}

But this won't:

---
layout: src/templates/first.njk
---

{% block content %}
 # ...
{% endblock %}

Basic Example

Here's a very basic Template example:

---
layout: src/layouts/master.njk
title: "This month's news from Maizzle"
---

{% block template %}
<table class="w-full">
  <tr>
    <td>
      <p class="m-0">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
    </td>
  </tr>
</table>
{% endblock %}

Archiving

Maizzle will only compile templates found in your build.templates.source path.

However, if you create a lot of emails, your builds can start to slow down, since all templates are rebuilt every time you run the build command.

Archive Templates (and their assets) that you no longer need built, by simply moving them to a directory outside that path.

Plaintext

Maizzle can create plaintext versions of your HTML emails.

Simply enable it in your Template's Front Matter:

---
title: This template will also have a plaintext version
plaintext: true
---

{% block template %}
  ...
{% endblock %}

A .txt file will be output at the same location with the compiled Template.