The default configuration of the email boilerplate should provide a common basis for most email campaigns, however if you want to customise any of the configuration you need to modify the configuration variables within a file called .boilerplate.custom.
There is a default configuration file called .boilerplate.defaults, this is always loaded first to make sure all configuration variables are loaded with a default value to prevent any build errors e.g. if a new variable is added and your .boilerplate.custom file doesn't have it.
Your .boilerplate.custom file is ignored by Git so you don't need to worry about any of your changes being overwritten on any updates to the source. Ensure you keep an eye on any changes made to this documentation for new configuration variables/modified behaviour. Tweak the .boilerplate.custom file to your needs and build the email boilerplate with gulp with your customisations.
The full list of configuration variables that can be used with the email boilerplate can be found in the table below.
| Option | Type | Value | Purpose |
|---|---|---|---|
| General boilerplate settings | |||
| GITHUB_REPO_URL | string | URL | Full URL of the project hosted on GitHub, used for generating latest git commit URL |
| ENABLE_GUIDELINES_VERSION_HEADER | boolean |
true (default) false |
Build email boilerplate guidelines version with the "pretty" document header |
| ENABLE_GENERATOR_META_TAG | boolean |
true (default) false |
Boolean to include a generator meta tag with the project name |
| Main Document | |||
| DOCTYPE_VERSION | string |
xhtml1_1 xhtml1_0-transitional (default) xhtml1_0-strict html4-transitional html4-strict html5 |
Build email boilerplate with a specific doctype. If this configuration option is blank or uses a non-existent value, no doctype will be used |
| LANGUAGE_CODE | string | en | Sets lang attribute value on root HTML tag. If the value is blank, the lang attribute will be removed from the root <html> tag entirely. |
| ENABLE_VML_NAMESPACES | boolean |
true (default) false |
Boolean to include VML namespaces on root HTML tag (needed for MSO specific code like VML) |
| CHARSET | string | utf-8 | Sets desired character set for the document |
| DOCUMENT_TITLE | string | Central College Nottingham | Ability to set a specific title value for the HTML document |
| ENABLE_FORMAT_DETECTION_META_TAG | boolean |
true false (default) |
Boolean to stop devices automatically converting data like phone numbers and addresses into ineteractive links |
| FORMAT_DETECTION_META_VALUE | string | telephone=no | Provide data types to be ignored |
| ENABLE_VIEWPORT_META_TAG | boolean |
true (default) false |
Boolean to include the viewport meta tag |
| VIEWPORT_META_VALUE | string | width=device-width | Ability to set a specific viewport value |
| ENABLE_XUA_COMPATIBLE_META_TAG | boolean |
true (default) false |
Boolean to include a XUA-Compatible meta tag for Internet Explorer based clients |
| XUA_COMPATIBLE_VALUE | string | IE=edge | Force a document mode for Internet Explorer based clients to use |
| ENABLE_ROBOTS_META_TAG | boolean |
true false (default) |
Boolean to include a meta robots tag |
| ROBOTS_META_VALUE | string | noindex, nofollow | Provide a value for the meta robots tags |
| ENABLE_APPLE_DISABLE_MESSAGE_FORMATTING_META_TAG | boolean |
true false (default) |
Boolean to include a specific meta tag that will prevent iOS/Apple Mail from auto formatting email messages (iOS 10) |
| ENABLE_FAVICON | boolean |
true false (default) |
Define a favicon reference which is used by some email clients/web version |
| FAVICON_URL | string | Absolute URL | Full http(s):// URL path to ico file |
| Microsoft Office (MSO) code | |||
| ENABLE_MSO_DPI_SCALING_FIX | boolean |
true (default) false |
Boolean to include MSO specific code that normalises PPI (DPI) on images |
| ENABLE_MSO_CONDITIONAL_STYLING | boolean |
true (default) false |
Boolean to include specific MSO CSS reset rules |
| ENABLE_VML_CSS_OBJECTS_STYLING | boolean |
true false (default) |
Boolean to include specific CSS rules for VML objects when using specific techniques |
| ENABLE_MSO_FALLBACK_FONT | boolean |
true (default) false |
Boolean to include a specific CSS block that targets main layout elements |
| MSO_DEFAULT_FALLBACK_FONT_STACK | string | Helvetica, Arial, sans-serif | Ability to set a web safe font stack Windows based Outlook clients will use when using web fonts |
| Main CSS Reset | |||
| ENABLE_GENERAL_SIBLING_SELECTOR_BUG_FIX | boolean |
true false (default) |
Fix CSS sibling selector support in certain Android/iOS clients |
| ENABLE_OUTLOOK_WEBMAIL_RESET_CSS (Deprecated) | boolean |
true (default) false |
Boolean to include specific CSS to reset line-height and email body container width in Outlook.com webmail |
| DEFAULT_ANCHOR_COLOUR | string | #e6057f | Ability to set a global general anchor colour |
| ENABLE_OUTLOOK_MAIL_ANCHOR_STYLING | boolean |
true false (default) |
Ability to override the default anchor styling in Outlook Mail (Windows 10) |
| DEFAULT_ANCHOR_VISITED_COLOUR | string | #ff0000 | Ability to set a global visited anchor colour |
| ENABLE_VISITED_ANCHOR_CSS | boolean |
true false (default) |
Boolean to include CSS to target visited links (not all clients support this styling) |
| ENABLE_IMG_FIX | boolean |
true (default) false |
Boolean to include the display property on the img selector CSS rule to make all images block elements |
| ENABLE_PARAGRAPH_CSS | boolean |
true false (default) |
Boolean to include CSS to reset the paragraph selector |
| ENABLE_HEADER_SELECTORS_CSS | boolean |
true false (default) |
Boolean to include CSS rules that targets h1 - h6 tags |
| HEADER_SELECTORS_CSS_COLOUR | string | #000000 | Ability to set the default colour of header tags (<h1> - <h6>) |
| HEADER_SELECTORS_ANCHOR_CSS_COLOUR | string | #0000FF | Ability to set the default colour of <a> tags within headers tags (<h1> - <h6>) |
| HEADER_SELECTORS_ANCHOR_ACTIVE_CSS_COLOUR | string | #FF0000 | Ability to set the default colour of active <a> within headers tags (<h1> - <h6>) |
| HEADER_SELECTORS_ANCHOR_VISITED_CSS_COLOUR | string | #800080 | Ability to set the default colour of visited <a> within header tags (<h1> - <h6>) |
| ENABLE_YAHOO_SHORTCUTS_CSS (Deprecated) | boolean |
true false (default) |
Boolean to include CSS rules that target automatically converted links in Yahoo! Mail (shortcuts) |
| YAHOO_SHORTCUTS_CSS_COLOUR | string | #000000 | Ability to set the colour of Yahoo shortcuts |
| CUSTOM_APPLE_LINKS_COLOUR1 | string | #666666 | Ability to create an additional .appleLinksCustom1 class with a custom colour |
| CUSTOM_APPLE_LINKS_COLOUR2 | string | #999999 | Ability to create an additional .appleLinksCustom2 class with a custom colour |
| CUSTOM_APPLE_LINKS_COLOUR3 | string | #222222 | Ability to create an additional .appleLinksCustom3 class with a custom colour |
| CSS3 media queries | |||
| ENABLE_WINDOWS_PHONE_VIEWPORT_FIX | boolean |
true false (default) |
Boolean to include a specific at-rule to adjust the viewport on Windows Phone devices |
| WINDOWS_PHONE_VIEWPORT_WIDTH | string | device-width | Ability to define a specific viewport value for Windows Phone devices |
| ENABLE_MEDIA_SCREEN_QUERY | boolean |
true (default) false |
Boolean to include a media screen query, useful for include webfonts with @font-face or import |
| ENABLE_MEDIA_PRINT_QUERY | boolean |
true false (default) |
Boolean to include a media print query, useful for optimising an email template for printing |
| ENABLE_YAHOO_MEDIA_QUERY | boolean |
true false (default) |
Boolean to include a specific yahoo media query that will be rendered in Yahoo! webmail |
| ENABLE_IE_10_11_MEDIA_QUERY | boolean |
true false (default) |
Boolean to include a specific IE 10/11 media query that targets both desktop and mobile |
| ENABLE_WEBKIT_DETECTION_QUERY | boolean |
true false (default) |
Boolean to include a specific webkit query that will be used on any Webkit client |
| ENABLE_GECKO_MEDIA_QUERY | boolean |
true false (default) |
Boolean to include a specific media query that targets Gecko based clients |
| ENABLE_IPAD_3_4_MEDIA_QUERY | boolean |
true false (default) |
Boolean to include a media query that matches the iPad 3/4 |
| ENABLE_IPAD_1_2_MEDIA_QUERY | boolean |
true false (default) |
Boolean to include a media query that matches the iPad 1/2 |
| ENABLE_MAX_DEVICE_WIDTH_MEDIA_QUERY | boolean |
true (default) false |
Boolean to include a media query that is triggered on TABLE_CONTAINER_WIDTH |
| ENABLE_RETINA_3X_MEDIA_QUERY | boolean |
true false (default) |
Boolean to include a media query that targets devices with a pixel density of 3x the standard |
| ENABLE_RETINA_2X_MEDIA_QUERY | boolean |
true false (default) |
Boolean to include a media query that targets devices with a pixel density of 2x the standard |
| ENABLE_RETINA_1X_MEDIA_QUERY | boolean |
true false (default) |
Boolean to include a media query that targets devices with a pixel density slighty higher than normal |
| ENABLE_IOS10_MEDIA_QUERY | boolean |
true false (default) |
Boolean to include a media query that targets iOS 10 devices |
| Misc/Other CSS | |||
| ENABLE_AOL_WEBMAIL_CSS_CLASS | boolean |
true false (default) |
Boolean to include a specific CSS class that will be rendered by AOL Webmail clients |
| ENABLE_OFFICE_365_CSS_SELECTOR | boolean |
true false (default) |
Boolean to include a specific CSS selector that will target Office 365 |
| ENABLE_GMAIL_HIDE_DOWNLOAD_ICON | boolean |
true false (default) |
Boolean to include a specific CSS selector that will remove the download icon on Gmail |
| ENABLE_GMAIL_WEBMAIL_TARGETING_SELECTOR | boolean |
true false (default) |
Boolean to include a specific CSS selector that will target Gmail webmail clients |
| ENABLE_ANDROID_4_4_CENTRE_FIX | boolean |
true (default) false |
Boolean to include an attribute selector that normalises the margin on Android 4.4 |
| ENABLE_CSS_DEBUG_MODE | boolean |
true false (default) |
Boolean to include a special set of CSS rules that will highlight elements allowing further analysis of layout elements |
| Main body | |||
| BODY_CSS_CLASS | string | body | Set a specific class on the <body> tag for advanced CSS targeting techniques |
| ENABLE_DOTMAILER_EASY_EDITOR_TEMPLATE | boolean |
true false (default) |
Boolean to include a specific HTML comment that is parsed by the dotmailer Easy Editor templating system |
| ENABLE_PREHEADER | boolean |
true (default) false |
Boolean to include a <div> following the <body> tag for the preheader |
| PREHEADER_TEXT | string | Example preheader text | Ability to provide a small sentence that will be the first text email clients will use in message/notification previews |
| PREHEADER_CHARACTER_PADDING | integer | 10 | A numeric value to control how many entities are included after the preheader content in PREHEADER_TEXT to act as character padding |
| BODY_BG_COLOUR | string | #ffffff | Ability to set a specific hexidecimal colour for the background of the email |
| TABLE_WRAPPER_CSS_ID | string | main-wrapper | Ability to set a specific CSS ID for the first wrapping table |
| TABLE_CONTAINER_CSS_ID | string | container-wrapper | Ability to set a specific CSS ID for the first wrapping cell |
| TABLE_WRAPPER_CELL_CSS_ID | string | main-cell | Ability to set a specific CSS ID for the container table |
| TABLE_CONTAINER_CELL_CSS_ID | string | container-cell | Ability to set a specific CSS ID for the container cell |
| TABLE_CONTAINER_CELL_BG_COLOR | string | #ffffff | Set a background colour for the container table cell |
| ENABLE_TABLE_CONTAINER | boolean |
true (default) false |
Boolean to control if a container table is created following the wrapper table |
| TABLE_CONTAINER_FIXED_WIDTH | boolean |
true (default) false |
Boolean to define if the email width should be fixed or not |
| TABLE_CONTAINER_WIDTH | integer | 600 | Set the width of the container table in pixels (px) |
| TABLE_WRAPPER_CELL_ALIGN | string | center | Set the align method of wrapper table cell |
| TABLE_CONTAINER_ALIGN | string | center | Set the align method of container table |
| ENABLE_GMAIL_ANDROID_RESIZE_FIX (Deprecated) | boolean |
true false (default) |
Boolean to include a spacer image the same size as TABLE_CONTAINER_WIDTH to prevent Gmail force scaling a wider email |
| ENABLE_GMAIL_IOS_FONT_FIX (Deprecated) | boolean |
true false (default) |
Boolean to include special divider block to prevent Gmail iOS app auto scaling fonts on wider emails |
| Other/Misc | |||
| PLACEHOLDER_IMG_URL | string | Absolute URL | Base URL path of where placeholder images are stored |
Several configuration options may be marked as "(Deprecated)", this is often due to email client specific changes that affect how the configuration option works since it was originally developed.
| Option | Deprecation note |
|---|---|
| ENABLE_OUTLOOK_WEBMAIL_RESET_CSS | Outlook.com is being migrated over to the Office 365 platform, the majority of Microsoft Accounts i.e. @live, @msn @hotmail, @outlook etc. should have already been migrated over, but there may still be a portion of the user base still present on the older Outlook.com platform. The purpose of this configuration variable was to reset the wrapping <div> element of the email body and normalise a crazy default line-height value via two CSS classes .ExternalClass and .ReadMsgBody. However, this reset will no longer be required once the older Outlook.com platform is retired completely. For now, the reset code remains enabled by default, but will likely be removed in the near future. |
| ENABLE_YAHOO_SHORTCUTS_CSS | Yahoo! Mail no longer highlights certain keywords in email campaigns, therefore there is no requirement to reset any .yshortcuts classes as they are no longer used. |
| ENABLE_GMAIL_ANDROID_RESIZE_FIX | Gmail is now starting to support CSS3, in addition the force scaling and font resizing quirks that these configuration options override on the Android and iOS Gmail apps are being removed from the client itself, so these options should be considered legacy. Currently not all Gmail clients are rendering with CSS3 support due to a phased rollout. |
| ENABLE_GMAIL_IOS_FONT_FIX |
The email boilerplate also contains samples of common techniques used in email campaigns. These samples are included on the guidelines version of the boilerplate only.
| Option | Type | Value | Purpose |
|---|---|---|---|
| ENABLE_HTML_SAMPLE_ANCHORS | boolean |
true (default) false |
Boolean to include an anchor HTML example for email usage |
| ENABLE_HTML_SAMPLE_CTA_BUTTONS | boolean |
true (default) false |
Boolean to include a sample of CTA buttons for email usage |
| ENABLE_HTML_SAMPLE_IMAGES | boolean |
true (default) false |
Boolean to include an image HTML example for email usage |
| ENABLE_HTML_SAMPLE_FLOATED_COLUMNS | boolean |
true (default) false |
Boolean to include a column layout for email usage |
| ENABLE_HTML_SAMPLE_ALIGN_BLOCK_ELEMENT | boolean |
true (default) false |
Boolean to include an block element align example for email usage |
| ENABLE_HTML_SAMPLE_FAUX_LISTS | boolean |
true (default) false |
Boolean to include a list layout using tables for email usage |
| ENABLE_HTML_SAMPLE_HORIZONTAL_SPACER | boolean |
true (default) false |
Boolean to include a horizontal spacer example using a table cell with line-height and height |
| ENABLE_HTML_SAMPLE_OUTLOOK_PAGE_BREAKS | boolean |
true (default) false |
Boolean to include a table example that shows how to avoid automatic page breaks in Outlook 2007+ |
| ENABLE_HTML_SAMPLE_OUTLOOK_TABLE_CSS_INHERITANCE | boolean |
true (default) false |
Boolean to include a table example that shows how to avoid CSS inheritance issues with table cells in Outlook 2007+ |