Templates

They're called pages in Jigsaw, but in Maizzle these are actually your email templates.

Templates can:

Maizzle provides a source/emails directory that includes template examples covering both scenarios above.


File Types

Templates can be Blade, Markdown, or Blade-Markdown hybrids. Different formats support different things, so here's an overview of what you can do with them:

ExtensionDescription
*.blade.phpRegular PHP files that will be parsed by the Blade engine. This means you can use directives, includes, and even regular PHP in them. It's mandatory that you use the @section directive to define where the content starts and ends.
*.mdRegular Markdown files, cannot use Blade. Of course, you can use YAML Front Matter variables.
*.blade.mdBlade-Markdown hybrids combine the best of both worlds, allowing you to use Markdown with Front Matter, as well as Blade and even pure PHP. You don't even need to define section start and end, like you have to with .blade.php files - it's done automatically.

Variables

Variables can either be set in the config (for example, Maizzle's default language or charset), or at a page level, through Front Matter.

With Front Matter, simply add them like this, inside triple-dashed lines at the top of your file:

---
myvar: This is the value
---

If you specify a variable that is already defined in your config, Jigsaw will use the one in your template instead. For example, you can set the charset of a single email to be something else than the default utf-8:

---
charset: ISO-8859-1
---

Defining Sections

With .blade.md or plain .md files, you don't need to define a section. Simply using @yield('content') in a Layout will pull in everything that comes after your Template's Front Matter.

However, if you're using .blade.php files for your templates, you need to tell Jigsaw where your content starts and ends. To do this, simply use the @section Blade directive, giving it a string parameter that matches what you have inside @yield() in the layout your template is extending:

// emails/example-sections.blade.php

---
extends: _layouts.master
title: The title of your email
preheader: This month's words of wisdom
---

@section('content')

    // your email's HTML markup goes here

@endsection

As you can see, we define a section named content, and this is exactly what @yield() references in the master layout.

Blade Stacks 1.1.0

Maizzle's default layouts include a @stack('head') directive (see Blade docs).

This allows you to use @push('head') and @prepend('head') in your Blade email files, to add anything you'd like right before the closing </head> tag.

You could use this to add custom <style></style> blocks on a per-template basis. Email client-specific CSS resets make for a good example:

source/emails/confirm-email.blade.md

---
// front matter needs to be first!
---

@push('head')
<style data-embed>
  a[x-apple-data-detectors] {color: inherit; text-decoration: none;}
</style>
@endpush

<table> 
    ...

You can push multiple stacks, too:

---
front matter ...
---

@push('head')
<meta name="format-detection" content="telephone=no">
<meta name="format-detection" content="date=no">
<meta name="format-detection" content="address=no">
<meta name="format-detection" content="email=no">
@endpush

@prepend('head')
<style data-embed>
  a[x-apple-data-detectors] {color: inherit; text-decoration: none;}
  </style>
@endprepend

<table> 
    ...

Of course, you can use it for anything you'd like to have right before </head>, for this template only: additional meta tags, Outlook conditionals, custom ESP code - you name it!

Notes:

Blade Directives 1.1.0

The @env($environment) Blade directive, inspired by the one in the Laravel docs, allows you to output content only when building for a specific environment.

For example, to output something only for production emails, you can do this:

source/emails/example.blade.md

---
// front matter always first!
---

<table class="w-full" cellpadding="0" cellspacing="0" role="presentation">
  <tr>
      <td align="center" class="px-8">
        @env('production')
            This text will be visible only when running `npm run production`
        @endenv
      </td>
  </tr>
</table>

Of course, you can do an if/else statement:

...

<table class="w-full" cellpadding="0" cellspacing="0" role="presentation">
  <tr>
      <td align="center" class="px-8">
        @env('development')
            Show this if we do `npm run dev` or `npm run watch`
        @elseenv('production')
            But when we do `npm run production`, show this instead
        @endenv
      </td>
  </tr>
</table>

Note: $environment must match one of the NODE_ENV environment variables set in package.json.