A Jekyll instance for organizing and building HTML emails offline using Haml
HTML CSS Ruby
Switch branches/tags
Nothing to show
Clone or download
Latest commit 49ea7aa Sep 14, 2015

README.md

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.