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

   1 # PostCSS [![Travis Build Status][travis-img]][travis] [![AppVeyor Build Status][appveyor-img]][appveyor] [![Gitter][chat-img]][chat]
   2
   3 <img align="right" width="95" height="95"
   4      title="Philosopher’s stone, logo of PostCSS"
   5      src="http://postcss.github.io/postcss/logo.svg">
   6
   7 [appveyor-img]: https://img.shields.io/appveyor/ci/ai/postcss.svg?label=windows
   8 [travis-img]:   https://img.shields.io/travis/postcss/postcss.svg?label=unix
   9 [chat-img]:     https://img.shields.io/badge/Gitter-Join_the_PostCSS_chat-brightgreen.svg
  10 [appveyor]:     https://ci.appveyor.com/project/ai/postcss
  11 [travis]:       https://travis-ci.org/postcss/postcss
  12 [chat]:         https://gitter.im/postcss/postcss
  13
  14 PostCSS is a tool for transforming styles with JS plugins.
  15 These plugins can lint your CSS, support variables and mixins,
  16 transpile future CSS syntax, inline images, and more.
  17
  18 PostCSS is used by industry leaders including Google, Twitter, Alibaba,
  19 and Shopify. The [Autoprefixer] PostCSS plugin is one of the most popular
  20 CSS processors.
  21
  22 Twitter account:      [@postcss](https://twitter.com/postcss).
  23 VK.com page:          [postcss](https://vk.com/postcss).
  24 Support / Discussion: [Gitter](https://gitter.im/postcss/postcss).
  25
  26 [Autoprefixer]: https://github.com/postcss/autoprefixer
  27
  28 <a href="https://evilmartians.com/?utm_source=postcss">
  29   <img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg"
  30        alt="Sponsored by Evil Martians" width="236" height="54">
  31 </a>
  32
  33 ## Plugins
  34
  35 Currently, PostCSS has more than 200 plugins. You can find all of the plugins
  36 in the [plugins list] or in the [searchable catalog]. Below is a list
  37 of our favorite plugins — the best demonstrations of what can be built
  38 on top of PostCSS.
  39
  40 If you have any new ideas, [PostCSS plugin development] is really easy.
  41
  42 [searchable catalog]: http://postcss.parts
  43 [plugins list]:       https://github.com/postcss/postcss/blob/master/docs/plugins.md
  44
  45 ### Solve Global CSS Problem
  46
  47 * [`postcss-use`] allows you to explicitly set PostCSS plugins within CSS
  48   and execute them only for the current file.
  49 * [`postcss-modules`] and [`react-css-modules`] automatically isolate
  50   selectors within components.
  51 * [`postcss-autoreset`] is an alternative to using a global reset
  52   that is better for isolatable components.
  53 * [`postcss-initial`] adds `all: initial` support, which resets
  54   all inherited styles.
  55 * [`cq-prolyfill`] adds container query support, allowing styles that respond
  56   to the width of the parent.
  57
  58 ### Use Future CSS, Today
  59
  60 * [`autoprefixer`] adds vendor prefixes, using data from Can I Use.
  61 * [`postcss-cssnext`] allows you to use future CSS features today
  62   (includes `autoprefixer`).
  63
  64 ### Better CSS Readability
  65
  66 * [`precss`] contains plugins for Sass-like features, like variables, nesting,
  67   and mixins.
  68 * [`postcss-sorting`] sorts the content of rules and at-rules.
  69 * [`short`] adds and extends numerous shorthand properties.
  70
  71 ### Images and Fonts
  72
  73 * [`postcss-assets`] inserts image dimensions and inlines files.
  74 * [`postcss-sprites`] generates image sprites.
  75 * [`font-magician`] generates all the `@font-face` rules needed in CSS.
  76 * [`postcss-inline-svg`] allows you to inline SVG and customize its styles.
  77 * [`postcss-write-svg`] allows you to write simple SVG directly in your CSS.
  78
  79 ### Linters
  80
  81 * [`stylelint`] is a modular stylesheet linter.
  82 * [`stylefmt`] is a tool that automatically formats CSS
  83   according `stylelint` rules.
  84 * [`doiuse`] lints CSS for browser support, using data from Can I Use.
  85 * [`colorguard`] helps you maintain a consistent color palette.
  86
  87 ### Other
  88
  89 * [`lost`] is a feature-rich `calc()` grid system.
  90 * [`cssnano`] is a modular CSS minifier.
  91 * [`rtlcss`] mirrors styles for right-to-left locales.
  92
  93 [PostCSS plugin development]: https://github.com/postcss/postcss/blob/master/docs/writing-a-plugin.md
  94 [`postcss-inline-svg`]:       https://github.com/TrySound/postcss-inline-svg
  95 [`react-css-modules`]:        https://github.com/gajus/react-css-modules
  96 [`postcss-autoreset`]:        https://github.com/maximkoretskiy/postcss-autoreset
  97 [`postcss-write-svg`]:        https://github.com/jonathantneal/postcss-write-svg
  98 [`postcss-initial`]:          https://github.com/maximkoretskiy/postcss-initial
  99 [`postcss-sprites`]:          https://github.com/2createStudio/postcss-sprites
 100 [`postcss-modules`]:          https://github.com/outpunk/postcss-modules
 101 [`postcss-sorting`]:          https://github.com/hudochenkov/postcss-sorting
 102 [`postcss-cssnext`]:          http://cssnext.io/
 103 [`postcss-assets`]:           https://github.com/assetsjs/postcss-assets
 104 [`font-magician`]:            https://github.com/jonathantneal/postcss-font-magician
 105 [`autoprefixer`]:             https://github.com/postcss/autoprefixer
 106 [`cq-prolyfill`]:             https://github.com/ausi/cq-prolyfill
 107 [`postcss-use`]:              https://github.com/postcss/postcss-use
 108 [`css-modules`]:              https://github.com/css-modules/css-modules
 109 [`colorguard`]:               https://github.com/SlexAxton/css-colorguard
 110 [`stylelint`]:                https://github.com/stylelint/stylelint
 111 [`stylefmt`]:                 https://github.com/morishitter/stylefmt
 112 [`cssnano`]:                  http://cssnano.co/
 113 [`precss`]:                   https://github.com/jonathantneal/precss
 114 [`doiuse`]:                   https://github.com/anandthakker/doiuse
 115 [`rtlcss`]:                   https://github.com/MohammadYounes/rtlcss
 116 [`short`]:                    https://github.com/jonathantneal/postcss-short
 117 [`lost`]:                     https://github.com/peterramsing/lost
 118
 119 ## Syntaxes
 120
 121 PostCSS can transform styles in any syntax, not just CSS.
 122 If there is not yet support for your favorite syntax,
 123 you can write a parser and/or stringifier to extend PostCSS.
 124
 125 * [`sugarss`] is a indent-based syntax like Sass or Stylus.
 126 * [`postcss-scss`] allows you to work with SCSS
 127   *(but does not compile SCSS to CSS)*.
 128 * [`postcss-less`] allows you to work with Less
 129   *(but does not compile LESS to CSS)*.
 130 * [`postcss-js`] allows you to write styles in JS or transform
 131   React Inline Styles, Radium or JSS.
 132 * [`postcss-safe-parser`] finds and fixes CSS syntax errors.
 133 * [`midas`] converts a CSS string to highlighted HTML.
 134
 135 [`postcss-safe-parser`]: https://github.com/postcss/postcss-safe-parser
 136 [`postcss-less`]:        https://github.com/webschik/postcss-less
 137 [`postcss-scss`]:        https://github.com/postcss/postcss-scss
 138 [`postcss-js`]:          https://github.com/postcss/postcss-js
 139 [`sugarss`]:             https://github.com/postcss/sugarss
 140 [`midas`]:               https://github.com/ben-eb/midas
 141
 142 ## Articles
 143
 144 * [Some things you may think about PostCSS… and you might be wrong](http://julian.io/some-things-you-may-think-about-postcss-and-you-might-be-wrong/)
 145 * [What PostCSS Really Is; What It Really Does](http://davidtheclark.com/its-time-for-everyone-to-learn-about-postcss/)
 146 * [PostCSS Guides](http://webdesign.tutsplus.com/series/postcss-deep-dive--cms-889)
 147
 148 ## Usage
 149
 150 You can start using PostCSS in just two steps:
 151
 152 1. Find and add PostCSS extensions for your build tool.
 153 2. [Select plugins] and add them to your PostCSS process.
 154
 155 [Select plugins]: http://postcss.parts
 156
 157 ### Gulp
 158
 159 Use [`gulp-postcss`] and [`gulp-sourcemaps`].
 160
 161 ```js
 162 gulp.task('css', function () {
 163     var postcss    = require('gulp-postcss');
 164     var sourcemaps = require('gulp-sourcemaps');
 165
 166     return gulp.src('src/**/*.css')
 167         .pipe( sourcemaps.init() )
 168         .pipe( postcss([ require('autoprefixer'), require('precss') ]) )
 169         .pipe( sourcemaps.write('.') )
 170         .pipe( gulp.dest('build/') );
 171 });
 172 ```
 173
 174 [`gulp-sourcemaps`]: https://github.com/floridoo/gulp-sourcemaps
 175 [`gulp-postcss`]:    https://github.com/postcss/gulp-postcss
 176
 177 ### Webpack
 178
 179 Use [`postcss-loader`]:
 180
 181 ```js
 182 module.exports = {
 183     module: {
 184         loaders: [
 185             {
 186                 test:   /\.css$/,
 187                 loader: "style-loader!css-loader!postcss-loader"
 188             }
 189         ]
 190     },
 191     postcss: function () {
 192         return [require('autoprefixer'), require('precss')];
 193     }
 194 }
 195 ```
 196
 197 [`postcss-loader`]: https://github.com/postcss/postcss-loader
 198
 199 ### npm run / CLI
 200
 201 To use PostCSS from your command-line interface or with npm scripts
 202 there is [`postcss-cli`].
 203
 204 ```sh
 205 postcss --use autoprefixer -c options.json -o main.css css/*.css
 206 ```
 207
 208 [`postcss-cli`]: https://github.com/postcss/postcss-cli
 209
 210 ### CSS-in-JS
 211
 212 To apply PostCSS plugins to React Inline Styles, JSS, Radium
 213 and other CSS-in-JS, you can use [`postcss-js`] and transforms style objects.
 214
 215 ```js
 216 var postcss  = require('postcss-js');
 217 var prefixer = postcss.sync([ require('autoprefixer') ]);
 218
 219 prefixer({ display: 'flex' }); //=> { display: ['-webkit-box', '-webkit-flex', '-ms-flexbox', 'flex'] }
 220 ```
 221
 222 [`postcss-js`]: https://github.com/postcss/postcss-js
 223
 224 ### Runners
 225
 226 * **Grunt**: [`grunt-postcss`](https://github.com/nDmitry/grunt-postcss)
 227 * **HTML**: [`posthtml-postcss`](https://github.com/posthtml/posthtml-postcss)
 228 * **Stylus**: [`poststylus`](https://github.com/seaneking/poststylus)
 229 * **Rollup**: [`rollup-plugin-postcss`](https://github.com/egoist/rollup-plugin-postcss)
 230 * **Brunch**: [`postcss-brunch`](https://github.com/iamvdo/postcss-brunch)
 231 * **Broccoli**: [`broccoli-postcss`](https://github.com/jeffjewiss/broccoli-postcss)
 232 * **Meteor**: [`postcss`](https://atmospherejs.com/juliancwirko/postcss)
 233 * **ENB**: [`enb-postcss`](https://github.com/awinogradov/enb-postcss)
 234 * **Fly**: [`fly-postcss`](https://github.com/postcss/fly-postcss)
 235 * **Start**: [`start-postcss`](https://github.com/start-runner/postcss)
 236 * **Connect/Express**: [`postcss-middleware`](https://github.com/jedmao/postcss-middleware)
 237
 238 ### JS API
 239
 240 For other environments, you can use the JS API:
 241
 242 ```js
 243 var postcss = require('postcss');
 244 postcss([ require('autoprefixer'), require('cssnano') ])
 245     .process(css, { from: 'src/app.css', to: 'app.css' })
 246     .then(function (result) {
 247         fs.writeFileSync('app.css', result.css);
 248         if ( result.map ) fs.writeFileSync('app.css.map', result.map);
 249     });
 250 ```
 251
 252 Read the [PostCSS API documentation] for more details about the JS API.
 253
 254 All PostCSS runners should pass [PostCSS Runner Guidelines].
 255
 256 [PostCSS Runner Guidelines]: https://github.com/postcss/postcss/blob/master/docs/guidelines/runner.md
 257 [PostCSS API documentation]: https://github.com/postcss/postcss/blob/master/docs/api.md
 258
 259 ### Options
 260
 261 Most PostCSS runners accept two parameters:
 262
 263 * An array of plugins.
 264 * An object of options.
 265
 266 Common options:
 267
 268 * `syntax`: an object providing a syntax parser and a stringifier.
 269 * `parser`: a special syntax parser (for example, [SCSS]).
 270 * `stringifier`: a special syntax output generator (for example, [Midas]).
 271 * `map`: [source map options].
 272 * `from`: the input file name (most runners set it automatically).
 273 * `to`: the output file name (most runners set it automatically).
 274
 275 [source map options]: https://github.com/postcss/postcss/blob/master/docs/source-maps.md
 276 [Midas]:              https://github.com/ben-eb/midas
 277 [SCSS]:               https://github.com/postcss/postcss-scss
 278
 279 ### Node.js 0.10 and the Promise API
 280
 281 If you want to run PostCSS in Node.js 0.10, add the [Promise polyfill]:
 282
 283 ```js
 284 require('es6-promise').polyfill();
 285 var postcss = require('postcss');
 286 ```
 287
 288 [Promise polyfill]: https://github.com/jakearchibald/es6-promise