www.aleph1.co.uk Git - yaffs-website/blob - node_modules/uncss/README.md

   1 # UnCSS
   2
   3 [![NPM version](https://img.shields.io/npm/v/uncss.svg)](https://www.npmjs.com/package/uncss)
   4 [![Linux Build Status](https://img.shields.io/travis/giakki/uncss/master.svg?label=Linux%20build)](https://travis-ci.org/giakki/uncss)
   5 [![Windows Build status](https://img.shields.io/appveyor/ci/giakki/uncss/master.svg?label=Windows%20build)](https://ci.appveyor.com/project/giakki/uncss/branch/master)
   6 [![Coverage Status](https://img.shields.io/coveralls/giakki/uncss.svg)](https://coveralls.io/r/giakki/uncss?branch=master)
   7 [![Dependency Status](https://img.shields.io/david/giakki/uncss.svg)](https://david-dm.org/giakki/uncss)
   8 [![devDependency Status](https://img.shields.io/david/dev/giakki/uncss.svg)](https://david-dm.org/giakki/uncss#info=devDependencies)
   9
  10 UnCSS is a tool that removes unused CSS from your stylesheets.
  11 It works across multiple files and supports Javascript-injected CSS.
  12
  13 ## How?
  14 The process by which UnCSS removes the unused rules is as follows:
  15
  16 1. The HTML files are loaded by [PhantomJS](https://github.com/Obvious/phantomjs) and JavaScript is executed.
  17 2. All the stylesheets are parsed by [PostCSS](https://github.com/postcss/postcss).
  18 3. `document.querySelector` filters out selectors that are not found in the HTML files.
  19 4. The remaining rules are converted back to CSS.
  20
  21 ## Installation:
  22
  23 ```shell
  24 npm install -g uncss
  25 ```
  26
  27 ## Usage
  28
  29 ### Within Node.js:
  30
  31 ```js
  32 var uncss = require('uncss');
  33
  34 var files   = ['my', 'array', 'of', 'HTML', 'files', 'or', 'http://urls.com'],
  35     options = {
  36         ignore       : ['#added_at_runtime', /test\-[0-9]+/],
  37         media        : ['(min-width: 700px) handheld and (orientation: landscape)'],
  38         csspath      : '../public/css/',
  39         raw          : 'h1 { color: green }',
  40         stylesheets  : ['lib/bootstrap/dist/css/bootstrap.css', 'src/public/css/main.css'],
  41         ignoreSheets : [/fonts.googleapis/],
  42         timeout      : 1000,
  43         htmlroot     : 'public',
  44         report       : false,
  45         uncssrc      : '.uncssrc'
  46     };
  47
  48 uncss(files, options, function (error, output) {
  49     console.log(output);
  50 });
  51
  52 /* Look Ma, no options! */
  53 uncss(files, function (error, output) {
  54     console.log(output);
  55 });
  56
  57 /* Specifying raw HTML */
  58 var rawHtml = '...';
  59
  60 uncss(rawHtml, options, function (error, output) {
  61     console.log(output);
  62 });
  63 ```
  64
  65 ### At build-time
  66 UnCSS can also be used in conjunction with other javascript build systems, such as [Grunt](https://github.com/gruntjs/grunt), [Broccoli](https://github.com/broccolijs/broccoli#readme) or [Gulp](https://github.com/gulpjs/gulp)!
  67
  68 - [grunt-uncss](https://github.com/addyosmani/grunt-uncss) – Thanks to [@addyosmani](https://github.com/addyosmani)
  69 - [gulp-uncss](https://github.com/ben-eb/gulp-uncss) – Thanks to [@ben-eb](https://github.com/ben-eb)
  70 - [broccoli-uncss](https://github.com/sindresorhus/broccoli-uncss) - Thanks to [@sindresorhus](https://github.com/sindresorhus)
  71
  72 ### From the command line:
  73
  74 ```
  75 Usage: uncss [options] <file or URL, ...>
  76     e.g. uncss http://getbootstrap.com/examples/jumbotron/ > stylesheet.css
  77
  78 Options:
  79
  80   -h, --help                            output usage information
  81   -V, --version                         output the version number
  82   -i, --ignore <selector, ...>          Do not remove given selectors
  83   -m, --media <media_query, ...>        Process additional media queries
  84   -C, --csspath <path>                  Relative path where the CSS files are located
  85   -s, --stylesheets <file, ...>         Specify additional stylesheets to process
  86   -S, --ignoreSheets <selector, ...>    Do not include specified stylesheets
  87   -r, --raw <string>                    Pass in a raw string of CSS
  88   -t, --timeout <milliseconds>          Wait for JS evaluation
  89   -H, --htmlroot <folder>               Absolute paths' root location
  90   -u, --uncssrc <file>                  Load these options from <file>
  91 ```
  92
  93 **Note that you can pass both local file paths (which are processed by [glob](https://github.com/isaacs/node-glob)) and URLs to the program.**
  94
  95 - **ignore** (Array): provide a list of selectors that should not be removed by UnCSS. For example, styles added by user interaction with the page (hover, click), since those are not detectable by UnCSS yet. Both literal names and regex patterns are recognized. Otherwise, you can add a comment before specific selectors:
  96
  97   ```css
  98   /* uncss:ignore */
  99   .selector1 {
 100       /* this rule will be ignored */
 101   }
 102
 103   .selector2 {
 104       /* this will NOT be ignored */
 105   }
 106   ```
 107
 108 - **media** (Array): By default UnCSS processes only stylesheets with media query "_all_", "_screen_", and those without one. Specify here which others to include.
 109
 110 - **csspath** (String): Path where the CSS files are related to the HTML files. By default, UnCSS uses the path specified in the `<link rel="stylesheet" href="path/to/file.css"/>`.
 111
 112 - **stylesheets** (Array): Use these stylesheets instead of those extracted from the HTML files.
 113
 114 - **ignoreSheets** (Array): Do not process these stylesheets, e.g. Google fonts. Accepts strings or regex patterns.
 115
 116 - **raw** (String): Give the task a raw string of CSS in addition to the existing stylesheet options; useful in scripting when your CSS hasn't yet been written to disk.
 117
 118 - **timeout** (Number): Specify how long to wait for the JS to be loaded.
 119
 120 - **htmlroot** (String): Where the project root is. Useful for example if you are running UnCSS on _local_ files that have absolute href to the stylesheets, i.e. `href="/css/style.css"`.
 121
 122 - **report** (Boolean): Return the report object in callback.
 123
 124 - **uncssrc** (String): Load all options from a JSON file. Regular expressions for the `ignore` and `ignoreSheets` options should be wrapped in quotation marks.
 125
 126   Example uncssrc file:
 127
 128   ```json
 129   {
 130       "ignore": [
 131           ".unused",
 132           "/^#js/"
 133       ],
 134       "stylesheets": [
 135           "css/override.css"
 136       ]
 137   }
 138   ```
 139
 140 ### As a PostCSS Plugin
 141
 142 UnCSS can be used as a [PostCSS](https://github.com/postcss/postcss) Plugin.
 143
 144 ```js
 145 postcss([ require('postcss-uncss').postcssPlugin ]);
 146 ```
 147
 148 See [PostCSS docs](https://github.com/postcss/postcss) for examples for your environment.
 149
 150 **Note:** Depending on your environment, you might not be able to use giakki/uncss as a PostCSS plugin since the plugin is not directly exported. In such cases, use the wrapper library [postcss-uncss](https://github.com/RyanZim/postcss-uncss).
 151
 152 #### Options
 153
 154 - **html** (Array): provide a list of html files to parse for selectors and elements. Usage of [globs](https://github.com/isaacs/node-glob) is allowed.
 155
 156 - **ignore** (Array): provide a list of selectors that should not be removed by UnCSS. For example, styles added by user interaction with the page (hover, click), since those are not detectable by UnCSS yet. Both literal names and regex patterns are recognized. Otherwise, you can add a comment before specific selectors in your css:
 157
 158   ```css
 159   /* uncss:ignore */
 160   .selector1 {
 161       /* this rule will be ignored */
 162   }
 163
 164   .selector2 {
 165       /* this will NOT be ignored */
 166   }
 167   ```
 168
 169 ##### Example Configuration
 170
 171 ```js
 172 {
 173   html: ['index.html', 'about.html', 'team/*.html'],
 174   ignore: ['.fade']
 175 }
 176 ```
 177
 178 ## License
 179 Copyright (c) 2013 Giacomo Martino. See the [LICENSE](/LICENSE.md) file for license rights and limitations (MIT).