Package Exports

gulp-email-remove-unused-css

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (gulp-email-remove-unused-css) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

gulp-email-remove-unused-css

Remove unused CSS from email templates

If you have any difficulties with the output of this plugin, please use the email-remove-unused-css issue tracker.

Online web app: EmailComb
PostHTML plugin: posthtml-email-remove-unused-css
The core library: email-remove-unused-css.

Install
Example
- Options
Regarding removing unused CSS from web pages & competition
Contributing
Licence

Install

Install using npm:

$ npm install --save-dev gulp-email-remove-unused-css

Example

var gulp = require('gulp');
var remove = require('gulp-email-remove-unused-css');

gulp.task('default', function () {
  return gulp.src('site.css')
    .pipe(remove({
      whitelist: ['.ExternalClass', '.ReadMsgBody', '.yshortcuts', '.Mso*', '.maxwidth-apple-mail-fix', '#outlook', '.module-*']
    }))
    .pipe(gulp.dest('./out'));
});

Options

Since the main purpose of this library is to clean email HTML, it needs to cater for email code specifics. One of them is that CSS styles will contain fix or hack styles, meant for email software. For example, here are few of them:

#outlook a { padding:0; }
.ExternalClass, .ReadMsgBody { width:100%; }
.ExternalClass, .ExternalClass div, .ExternalClass font, .ExternalClass p, .ExternalClass span, .ExternalClass td { line-height:100%; }

Obviously, you will not be using the above classes and id's in the <body> of your HTML code, what means they would get removed — they are present in <head> only. To avoid that, pass the classes and id's in the whitelist key's value, as an array, for example:

.pipe(remove({
  whitelist: ['.ExternalClass', '.ReadMsgBody', '.yshortcuts', '.Mso*', '.maxwidth-apple-mail-fix', '#outlook']
}))

You can also use a glob, for example in order to whitelist classes module-1, module-2 ... module-99, module-100, you can simply whitelist them as module-*:

.pipe(remove({
  whitelist: ['.ExternalClass', '.ReadMsgBody', '.yshortcuts', '.Mso*', '.maxwidth-apple-mail-fix', '#outlook', '.module-*']
}))
// => all class names that begin with ".module-" will not be touched by this library.

Regarding removing unused CSS from web pages & competition

This library is meant to be used on any HTML where there are no external stylesheets and there are no JavaScript which could add or remove classes or id's dynamically. It's quite rare to find a web page that would be like that, but it's the case for all email newsletters and this library is aimed at cleaning email HTML code. If your website's HTML is like that, this library will work perfectly fine on it as well. Email HTML and website HTML are both the same markup language.

If you need more advanced CSS removal tools, check out uncss and gulp-uncss which runs a headless browser and are capable to parse external stylesheets. However, it's by magnitude slower and it's definitely an overkill for email HTML code.

There's also more direct competitor, postcss-remove-unused which uses Cheerio, but:

postcss-remove-unused is tied with PostCSS and can't be used outside of it. Its testing is also tied to PostCSS and dependent on it. On other hand, this library is only a Gulp wrapper for email-remove-unused-css which is tool-independent (reads string, outputs string). I'm a strong believer that core functionality should be decoupled from the wrappers, PostHTML, PostCSS, Gulp, Grunt, font-end interfaces or anything else. In the past I decoupled Detergent's core from its front-end.
postcss-remove-unused doesn't remove id's, while this library does. It's important because some of email code hacks are based on id's, for example, #outlook a {padding: 0; } which causes "View in browser" toolbar menu link to appear on Outlook 2010. Style cleaning library must recognise id's in order to white-list them.

Contributing

If you see anything incorrect whatsoever, do raise an issue. If you file a pull request, I'll do my best to merge it quickly. If you have any comments on the code, including ideas how to improve something, don't hesitate to contact me by email.

If something doesn't work as you wished or you don't understand the inner workings of this library, do raise an issue. I'm happy to explain what's happening. Often some part of my README documentation is woolly, and I can't spot it myself. I need user feedback.

Also, if you miss a feature, request it by raising an issue as well.

I know it never happens, but if you would ever forked it and worked on a new feature, before filing a pull request, please make sure code is following the rules set in .eslintrc and npm run test passes fine. It's basically an airbnb-base rules preset of eslint with few exceptions: 1. No semicolons. 2. Allow plus-plus in for loops. See ./eslintrc.

I dropped JS Standard because it misses many useful ESLint rules and has been neglected by its maintainers, it's currently using a half-year-old version of ESLint.

Cheers!

Licence

MIT License (MIT)

Copyright (c) 2017 Codsen Ltd, Roy Revelt

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.