Deprecated
I learned a lot putting this together but I've moved on. I don't want to remove it in case people are using this, but I'll be sharing my Middleman version instead.
emayll
A Jekyll instance for organizing and building HTML emails offline using Haml
Dependencies
Getting Started
- Install Jekyll (if you don't have it yet)
- Clone the repo
- Start the Jekyll server (jekyll serve)
- Watch the Jekyll build (jekyll build --w or other options)
Why would you ever do this?
I'm most comfortable working locally, in my editor. While I had done some occasional emails, creating them on a regular basis didn't become part of my job until I had been a front-end dev in MVC environments for a while.
A static site generator allows for a better workflow and still results in what is necessary for the sending services: a single HTML file with all of the code for the email.
Methodologies
Write emails in Haml
Haml is more terse than HTML and the white space requirement helps keep nested tables clean.
Use HTML attributes whenever possible
As much as possible, I use HTML attributes. One example is bgcolor="" instead of applying a CSS background color. Another example is that separating paragraphs with spacer table rows.
Use front matter as a combo of includes and variables
Yaml front matter is used for meta about each email. It is also used to reduce repetitive code and to control the styles of regular patterns.
No automated inlining
A common practice is to write CSS in a stylesheet and then use something to automatically inline the CSS throughout your HTML. For the time being, I don't do that as I prefer to use a combo of YAML front matter and writing the code.
Basic Organization
By default, emails are organized into promotional and transactional categories. This will likely work for about 10 of each before it gets unwieldy. It's enough for you to jump in and figure out if building in this way works well for you.
Structure
Layouts
| File | Purpose |
|---|---|
| default.html | The HTML structure for the landing page of emayll. |
| email.html | The basic structure for every email you send. Things like doctype, html, body, etc. Code that may change per email are put into includes. |
Includes
| File | Purpose |
|---|---|
| style.css | The global CSS that needs to be included in the head, primarily media queries. It's an include so that it is output into the the HTML file for each email. |
| email-header.haml | HTML for the header of a group of emails. If you have multiple types of headers, create more. An example may be mailchimp-header.haml and mandrill-header.haml |
| email-footer.haml | HTML for the footer of a group of emails. If you have multiple types of headers, create more. An example may be mailchimp-footer.haml and mandrill-footer.haml |
| head.html, header.html, footer.html | Will these stay? Review after styling can be done. |
Emails
Each email is a Haml file in a collections folder. The folders initially set up are _promotional and _transactional. Haml files that are saved in those folders will be output as HTML every time that the build runs.
YAML Front Matter
Front matter is used to set information about an email, to control its layout, and to use variables for repeated code and values.
| Name | Purpose |
|---|---|
layout |
Sets the layout, which needs to be a file in the _layouts folder. |
title |
Sets the title of the email for displaying in emayll |
categories |
Sets the categories used for filtering in emayll |
service |
Displays the service being used for sent as meta information in emayll |
status |
Displays the status of the email as meta information in emayll. Requires manual configuration for anything beyond the default: inactive, active, retired |
Purpose |
Displays the purpose of the email as meta information in emayll |
The following are style defaults and will work only if the calls for them are used in a file. They allow for rapidly changing the look of an individual email.
| Name | Purpose |
|---|---|
hdr-c-base |
Sets the base text color for the header table |
hdr-c-bg |
Sets the base background color for the header table |
hdr-c-link |
Sets the base link color for the header table |
hdr-border |
Sets the CSS for a border for the header. Defaults to having one and can be overridden in an individual email by changing to border-bottom: 0; |
ftr-c-base |
Sets the base text color for the footer table |
ftr-c-bg |
Sets the base background color for the footer table |
ftr-c-link |
Sets the base link color for the footer table |
ftr-border |
Sets the CSS for a border for the footer table. Defaults to having one and can be overridden in an individual email by changing to border-bottom: 0; |
tbl-base |
Sets base HTML attributes that need to be on every table. Used to reduce code a bit. |
tbl-typeset |
Sets the base font stack, size, and line-height in any table with {{ page.tbl-typeset }} in the style tag. Used to reduce code. |
c-bg |
Sets the background color of the primary container table in the layout, setting the background color of the email. |
c-base |
Sets the font color for all tables containing {{ page.c-base }} as a CSS color. |
c-link |
Sets the color for all links containing {{ page.c-link }} as a CSS color. |
c-title |
Sets the color for any title containing {{ page.c-title }} as a CSS color. |
gutter |
Sets the pixel width of spacer cells, which are used to keep content off the edges in clients. It was created after Mailbox app changed their rendering, but also fixes issues with Gmail at smaller resolutions. |
btn-c-base |
Sets the font color for button tables containing {{ page.btn-c-base }} as a CSS color. |
btn-c-bg |
Sets the background color for button tables containing {{ page.btn-c-bg }} as a CSS color. |
btn-c-shadow |
Sets the shadow color for button tables containing {{ page.btn-c-shadow }} as a CSS color. |
