Templates configuration

Configure where your Templates live, where they should be output, as well as what file extensions they use or which assets should be copied over in the process.

Template configuration is done under the build.templates key of your Maizzle config:

module.exports = {
  build: {
    templates: {
      source: 'src/templates',
      destination: {
        path: 'build_local',
        extension: 'html'
      },
      filetypes: 'html',
      assets: {
        source: './src/images',
        destination: 'images'
      }
    }
  }
}

source

Define the source directory where Maizzle should look for Templates to compile.

source can be:

• a string
• an array of strings
• a function that returns one of the above

String source

Use a string source to define a single source directory:

module.exports = {
  build: {
    templates: {
      source: 'src/templates'
    }
  }
}

Array source

Use source as an array of strings to define multiple source directories:

module.exports = {
  build: {
    templates: {
      source: ['src/templates', 'src/amp-templates']
    }
  }
}

Function source

Use source as a function to define a dynamic source directory.

The function receives the Maizzle config object as its only argument, and must return a string or an array of strings:

module.exports = {
  build: {
    templates: {
      source: (config) => {
        if (config.env === 'production') {
          return 'src/templates'
        }

        return ['src/templates', 'src/amp-templates']
      }
    }
  }
}

Remember, Maizzle will copy these folders and their entire contents to the templates.destination.path directory.

filetypes

Default: html

Define what file extensions your Templates use.

filetypes can be a string, but it can also be an array or a pipe|delimited list:

module.exports = {
  build: {
    templates: {
      filetypes: ['html', 'blade.php'] // or 'html|blade.php'
    }
  }
}

Maizzle will only compile files with these extensions.

This means you can keep other files alongside your Templates, and Maizzle will not try to compile them - it will simply copy them over to the build destination directory.

destination

Define the output path for compiled Templates, and what file extension they should use.

path

Directory path where Maizzle should output the compiled emails.

module.exports = {
  build: {
    templates: {
      destination: {
        path: 'build_local'
      }
    }
  }
}

If you omit this key, a build_[env] directory name will be used, where [env] is the current environment, i.e. build_production or build_local.

Unique destination paths

Using multiple templates config blocks? Make sure to have unique destination.path names, otherwise files with the same name will be overwritten.

extension

Define the file extension - without the leading dot - to be used for the compiled templates. For example, let's output Laravel Blade files:

module.exports = {
  build: {
    templates: {
      destination: {
        path: 'build_laravel',
        extension: 'blade.php'
      }
    }
  }
}

The compiled templates will be output as build_laravel/*.blade.php.

permalink

Use the permalink Front Matter key to define a custom output path right in a Template:

---
permalink: output/this/template/here.html
---

<extends src="src/layouts/main.html">
  <block name="template">
    <!-- ... -->
  </block>
</extends>

This will override destination.path from your config, but only for this Template.

You may use both relative and absolute file paths.

For example, output one level above project directory:

---
permalink: ../newsletter.html
---

<extends src="src/layouts/main.html">
  <block name="template">
    <!-- ... -->
  </block>
</extends>

Output at a specific system location:

---
permalink: C:/Users/Cosmin/Newsletter/2022/12/index.html
---

<extends src="src/layouts/main.html">
  <block name="template">
    <!-- ... -->
  </block>
</extends>

assets

Source and destination directories for your asset files.

At build time, templates.assets.destination will be created relative to templates.destination, and files inside templates.assets.source will be copied into it:

module.exports = {
  build: {
    templates: {
      assets: {
        source: 'src/images',
        destination: 'images'
      }
    }
  }
}

You can use it to store any files you might need, not just images.

Of course, if using multiple templates blocks, you can have different asset configurations for each block:

module.exports = {
  build: {
    templates: [
      {
        source: 'src/templates',
        destination: {
          path: 'build_basic'
        },
        assets: {
          source: 'src/images',
          destination: 'images' // assets output to build_basic/images
        }
      },
      {
        source: 'src/amp-templates',
        destination: {
          path: 'build_amp'
        },
        assets: {
          source: 'src/assets/amp',
          destination: 'media' // assets output to build_amp/media
        }
      }
    ]
  }
}

Multiple templates

You may define multiple templates sections. Each section will be processed and templates will be output based on the section's configuration.

module.exports = {
  build: {
    // Multiple `templates` as array of objects
    templates: [
      {
        source: 'src/templates',
        destination: {
          path: 'build_local'
        }
      },
      {
        source: 'src/amp-templates',
        destination: {
          path: 'build_amp'
        }
      }
    ]
  }
}