👋 New syntax

You are viewing the documentation for Templates using the new Components syntax introduced in v4.4.0. Not ready to switch yet? See the legacy Templates docs.

A Template in Maizzle is a special kind of Component that typically contains the body of your email: the HTML that defines the design and content.

It's made up of two distinct sections:

  1. Front Matter
  2. Your HTML

Unlike other Components, a Template may include a Front Matter block, which is a YAML-style block of variables that you may define at the top of the file.

Maizzle knows to parse this block's variables and makes them available to all other Components that you add to this Template, as well as to the Layout it uses.

Front Matter

Templates can define new variables and even override existing ones from your config, through the optional YAML-style Front Matter block:

title: "Please confirm your email address"

Front Matter variables are accessible through the page object.

To output them in a Template, use the {{ }} expression syntax:

title: "Please confirm your email address"

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

Using Layouts

Your emails will likely share the same boilerplate, like the <!doctype>, the <head> with all the <meta> tags, or the <body> tag - code that rarely needs to change.

Although you're free to do it, it would be very inefficient to always have to write this boilerplate every time you create a new Template.

To reuse this code in Maizzle, you may create a Layout:

<!doctype html>
  <style>{{{ page.css }}}</style>
  <slot:template />

Then, in a Template, you can fill that <slot:template /> with your Template's HTML:

    <!-- your email HTML... -->

In the example above, we use the <x-main> Component tag to say that we want to use the main.html Layout. We then fill (replace) its <slot:template /> tag with the HTML inside our Template's <fill:template> tag.

Current template

When developing locally, information about the Template file that is currently being processed is available under page.build.current.

It's an object containing a parsed path of the destination file name:

build: {
  current: {
    path: {
      root: '',
      dir: 'build_production',
      base: 'transactional.html',
      ext: '.html',
      name: 'transactional'

It can be used in Events like beforeRender if you need the file name or extension of the Template file currently being processed.


Maizzle will only compile templates found in path(s) that you have defined in build.templates.source, which have the same extension as the one defined in build.templates.filetypes (html by default).

If your project has a lot of emails, your builds may start to slow down since all Templates are rebuilt on cold start (every time you run the maizzle build <env> command) or when developing locally and making changes to a Layout, a Component, or a config file (this needs to trigger a full rebuild to reflect changes across all Templates).

You can archive Templates in a few ways:

  1. Move them to a directory outside the one defined in build.templates.source, so they don't get copied over to the destination directory (recommended).
  2. Change their file extension to something that is not defined in build.templates.filetypes. They'll just be copied over to the destination, Maizzle will not try to compile them.
  3. Use the omit option
Copyright © 2023 Maizzle SRL Brand policy
Edit this page on GitHub