`s
+- Raster images (like PNGs) instead of vector (like SVGs)
+- Inline CSS instead of embedded styles or external stylesheets
+
+[Can I Email?](https://www.caniemail.com/) and [Campaign Monitor’s guide to CSS](https://www.campaignmonitor.com/css/) are good references for HTML & CSS support in email.
+
+## HTML and CSS
+
+1. **Use `
` when creating new tables.** This negates any unwanted spacing and borders and tells screen readers to skip over the table’s tags and move straight into the content.
+2. **When in doubt, nest another table.** For finer control of your HTML, nest tables when building emails.
+3. **Use padding for spacing in table cells.** Margins aren’t fully supported on tables and container elements.
+4. **Use margin for typography.** Margins *are* fully supported for headlines, paragraphs, and lists.
+5. **Use `align` for layout instead of `float`, `grid`, or `flexbox`.** Floats aren’t supported in Outlook and email clients don’t have good support for modern CSS layout properties in general.
+6. **HTML attributes are still relevant.** Most styling is done using CSS. But because some email clients use antiquated rendering engines, they tend to better understand HTML attributes like `align`, `valign`, `height`, and `width`.
+7. **Define color as `#ffffff` instead of `#fff` or `rgb(1,2,3)`.** Six-digit hex is supported in inline CSS as well as HTML attributes like `bgcolor` that are still supported in email.
+8. **Don’t forget about [preview text](https://stackoverflow.design/email/guidelines/faq#what-is-preview-text?).** We can specify the text that appears beneath subject lines in many email clients. If preview text is not included, this space will be populated by the email’s content.
+
+## Images
+
+1. **Save images as PNG, GIF, or JPG instead of SVG.** SVG has almost no support in email, no matter how it’s referenced (inline, Base64, `.svg`).
+2. Save images as @2x and scale them down using HTML attributes. Since SVG isn’t supported, a 20x20 raster image coded like `` displays crisply on high-definition screens.
+
+## Accessibility
+
+1. Include `role="presentation"` on all tables used for layout. This prevents screen readers from reading aloud the structure of each table cell.
+2. **Include `aria-hidden="true"` on presentational elements.** This prevents screen readers from reading aloud something that's not content.
+3. **Use HTML1 semantic tags whenever possible.** Tags like `
` and `` allow screen readers to quickly jump from section to section. Tags like `` and `` give text more importance.
+4. **Include an `alt` attribute on every image.** Be descriptive and use `alt` to help readers “see” the email if images aren’t displayed. Use an empty `alt=""` for images a screen reader should skip (eg. decorative images). Screenreaders will dictate the filename of images without an `alt` attribute (eg. "icon dash checkmark dot png"). [More on alt text](https://stackoverflow.design/content/examples/alt-text/).
+5. **Avoid “Click Here” or “Learn More” link copy.** It helps an email avoid spam filters and gives context about the link to folks using screen readers or dictation software.
+6. **Create a plain text version of every email.** It helps us avoid spam filters, some email clients don’t support HTML, and some people just prefer plain text. They also respond better to things like changing font size, family, and color, and work well with screen magnifiers.
+
+## Testing
+
+Tools to ensure emails look as they should when they’re sent.
+
+- [Litmus](https://www.litmus.com/) and [Email on Acid](https://www.emailonacid.com/) allow us to preview screenshots of our emails across 90+ email clients on multiple devices. Both have code editors built in (Eg. [Litmus Builder](https://litmus.com/email-builder)), which helps troubleshoot and fix bugs in actual email clients.
+- [Parcel](https://useparcel.com/) - A web-based code editor built specifically for email development.
+- [Putsmail](https://putsmail.com/) - Send yourself test emails.
diff --git a/docs/content/components.md b/docs/content/components.md
new file mode 100644
index 00000000..b9b6a7bc
--- /dev/null
+++ b/docs/content/components.md
@@ -0,0 +1,359 @@
++++
+title = "Components"
+description = "About John Doe, a good human"
+template = "default-template.html"
+[extra]
+page_id = "components"
++++
+
+# Components
+
+## Tables
+
+`
`s are still the most dependable way to create layouts for HTML emails.
+
+
Some email clients will collapse the spacer’s height if there’s no content.
+
style="font-size: 0px;line-height: 0px;"
Some clients will add additional space inherited from the ’s font-size and line-height.
+
+
+## Typography
+
+It’s safe and accessible to use semantic HTML tags like ``, `
`, and `
` for text in email just as we do for the web. The main difference in email is that [CSS should be written inline](https://stackoverflow.design/email/guidelines/faq#why-do-we-have-to-write-css-inline?) to specify intended styles (like the color of an anchor tag) and zero out unintended defaults (like the default margin around a `
+
+
+#### Auto-detected links
+
+Some email clients auto-detect certain text strings (like dates, times, and locations) and automatically convert them into hyperlinks. We can’t *remove* the link, but we can make the link *appear* like the text around it by negating a few CSS styles.
+
+
+
Cerberus -
- Between mobile, Gmail, and Outlook, HTML email is a three-headed dog from hell.
-
-
-
-
Introduction
-
Coding regular emails is hard enough by itself. Making them responsive shouldn’t add to the headache. A few simple, but solid patterns are all that’s needed to optimize emails for small screens.
-
That’s what Cerberus is.
-
It’s just a few responsive email patterns that go a long way. The code blocks are compartmentalized so they may be used, removed, combined, and nested to build an email.
-
Each template contains code comments and has good support among popular email clients.
Cerberus is a small collection layout patterns for HTML email. The code is meant to be edited, adapted, and built upon.
-
The code is compartmentalized and annotated in an effort to explain what’s happening so you can add, edit, and remove code with some confidence.
-
This has been tested in all “popular” email clients, but not every email client out there. More on that here.
-
-
-
-
The Templates
-
-
-
- As the layout narrows, the email content reflows and resizes gracefully.
-
-
Fluid Template
-
Good for simple layouts such as transactional and single column emails.
-
This template focuses on a fluid layout that sizes itself using percentage-based widths to shrink horizontally on narrow screens. This email layout does not reconfigure at different screen sizes.
-
If you want a basic template to handle rich text and images, this is a good baseline.
-
-
- The email layout changes at breakpoints using media queries.
-
-
Responsive Template
-
Good for more complicated, shape-shifting email layouts that work on some mobile clients.
-
This template uses media queries to reconfigure the layout for different screen sizes for email clients that support media queries. However, mobile clients that don’t support media queries or the <style> tag will display a shrunk version of the desktop layout instead. This applies to some versions of Gmail (still) and Yahoo, as well as a number of international email clients (more info on that here).
-
If you’re already comfortable with media queries, the learning curve is relatively low. If total device coverage isn’t required, you can create a responsive email the same way you create a responsive website.
-
-
- The email layout stacks without media queries.
-
-
Hybrid Template
-
This template uses a hybrid approach to reconfigure the layout for different screen sizes for email clients regardless of media query support. At its core, it uses max-width and min-width to impose rigid baselines (allowing some movement) and imposes a fixed, wide width for Outlook who is shackled to desktop anyway. Once a mobile-friendly baseline is set, media queries progressively enhance the email further in clients that support it.
-
If you have some email design experience, this template optimizes every popular email client. All the extra Outlook code can make these templates quite large and your maths have to be spot on for multi-column layouts.
Templates in the archived-versions folder are not currently being maintained and should be considered unsupported and deprecated. They are kept around for historical purposes. 💫
-
-
-
-
Client Support
-
Cerberus is tested in the most popular email clients as reported by Litmus and my own email campaigns. I’ve focused on the following clients:
-
-
-
Desktop
-
Outlook 2000/02/03/07/10/13/16 (Windows)
-
Windows 10 Mail
-
Outlook 2011/16 (Mac)
-
Apple Mail 9/10
-
Thunderbird
-
-
-
Web (Chrome, FF, IE)
-
Gmail (IMAP, Business
-
Outlook.com
-
Yahoo
-
Aol
-
Office 365 Web
-
Comcast
-
Web.de
-
GMX.de
-
freenet.de
-
T-Online.de
-
Mail.ru
-
Terra Mail
-
-
-
Mobile Apps
-
iOS Mail (iPhone 5 and up, iPad, iPad Mini)
-
Gmail (iOS+Android, all account types)
-
Google Inbox (iOS)
-
Mail (Android 6.0)
-
Yahoo (iOS)
-
Outlook (iOS)
-
Alto Mail (iOS)
-
-
-
When I say “tested”, I mean “email doesn’t fall apart”. I don’t mean "Everything is pixel perfect in Outlook" or “I found a way to make media queries work everywhere.” They don’t.
-
There are multiple versions of Gmail. Cerberus works pretty well in all of them. Rémi Parmentier created an excellent graphic explaining Gmail’s capabilities in this article.
-
Any client not listed above should be considered untested. If you feel I’ve left out a popular email client or can suggest a non-destabilizing fix for one, please submit an issue!
-
For what it’s worth, Litmus (who does test every email client) includes Cerberus in its Email Builder, so there’s that.
-
-
-
Known Issues
-
Not necessarily a bug with the code in this repo, but a few things that could trip you up.
-
-
Some ESPs don’t like URLs in HTML comments (example issue). In this case, you can remove the URLs or even the entire HTML comment.
-
-
-
-
A Word on CSS Inliners
-
I recommend against using a CSS inliners with Cerberus. Here’s why:
-
-
Cerberus is supposed to be simple and should not require a dependency like a CSS inliner.
-
The placement of Cerberus’s CSS is already optimized. The CSS in the <head> is meant only for email clients that parse CSS in this location. It doesn’t need to be inlined.
-
There are some CSS selectors like :hover that don’t inline so well and throw errors in some CSS inliners.
-
Inlining leads to code bloat. Not only does this impact download speeds, but some email clients like Gmail and iOS Outlook truncate messages after they exceed a certain file size.
-
-
I’m a fan of using snippets, available most code editors. I understand CSS inliners help many folks, but if you use one with Cerberus, please do so at your own risk. I recommend Lee Munroe’s CSS inliner and hear good things about Roadie.
-
-
-
Contributing
-
If you would like to help, please @reply me on Twitter or open an issue to discuss your idea. I’m forever interested in reducing the entropy of this code. I’m most interested in:
-
-
Fixing existing code that’s broken.
-
Reducing the amount of code in existing patterns.
-
Improving the documentation.
-
-
Please be mindful there are three templates that share a lot of code. Many changes apply to all three.
-
Please branch off the main branch instead of master.
-
-
-
Resources
-
Things that directly helped (and continue to help) build Cerberus.
Hello! I’m Ted Goas, the core author and maintainer. I’m a designer & front-end developer working on websites, web apps, and HTML emails. And I enjoy talking shop on Twitter.
` displays crisply on high-definition screens.
+
+## Accessibility
+
+1. Include `role="presentation"` on all tables used for layout. This prevents screen readers from reading aloud the structure of each table cell.
+2. **Include `aria-hidden="true"` on presentational elements.** This prevents screen readers from reading aloud something that's not content.
+3. **Use HTML1 semantic tags whenever possible.** Tags like `
- 
- 
- 
- 
- 
- 