.config/coc/extensions/node_modules/coc-prettier/node_modules/postcss-less/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 Wikipedia, Twitter, Alibaba,
  19 and JetBrains. 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 For PostCSS commercial support (consulting, improving the front-end culture
  27 of your company, PostCSS plugins), contact [Evil Martians](https://evilmartians.com/?utm_source=postcss)
  28 at <surrender@evilmartians.com>.
  29
  30 [Autoprefixer]: https://github.com/postcss/autoprefixer
  31
  32 <a href="https://evilmartians.com/?utm_source=postcss">
  33   <img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg"
  34        alt="Sponsored by Evil Martians" width="236" height="54">
  35 </a>
  36
  37 ## Plugins
  38
  39 Currently, PostCSS has more than 200 plugins. You can find all of the plugins
  40 in the [plugins list] or in the [searchable catalog]. Below is a list
  41 of our favorite plugins — the best demonstrations of what can be built
  42 on top of PostCSS.
  43
  44 If you have any new ideas, [PostCSS plugin development] is really easy.
  45
  46 [searchable catalog]: http://postcss.parts
  47 [plugins list]:       https://github.com/postcss/postcss/blob/master/docs/plugins.md
  48
  49 ### Solve Global CSS Problem
  50
  51 * [`postcss-use`] allows you to explicitly set PostCSS plugins within CSS
  52   and execute them only for the current file.
  53 * [`postcss-modules`] and [`react-css-modules`] automatically isolate
  54   selectors within components.
  55 * [`postcss-autoreset`] is an alternative to using a global reset
  56   that is better for isolatable components.
  57 * [`postcss-initial`] adds `all: initial` support, which resets
  58   all inherited styles.
  59 * [`cq-prolyfill`] adds container query support, allowing styles that respond
  60   to the width of the parent.
  61
  62 ### Use Future CSS, Today
  63
  64 * [`autoprefixer`] adds vendor prefixes, using data from Can I Use.
  65 * [`postcss-cssnext`] allows you to use future CSS features today
  66   (includes `autoprefixer`).
  67 * [`postcss-image-set-polyfill`] emulates [`image-set`] function logic for all browsers
  68
  69 ### Better CSS Readability
  70
  71 * [`precss`] contains plugins for Sass-like features, like variables, nesting,
  72   and mixins.
  73 * [`postcss-sorting`] sorts the content of rules and at-rules.
  74 * [`postcss-utilities`] includes the most commonly used shortcuts and helpers.
  75 * [`short`] adds and extends numerous shorthand properties.
  76
  77 ### Images and Fonts
  78
  79 * [`postcss-assets`] inserts image dimensions and inlines files.
  80 * [`postcss-sprites`] generates image sprites.
  81 * [`font-magician`] generates all the `@font-face` rules needed in CSS.
  82 * [`postcss-inline-svg`] allows you to inline SVG and customize its styles.
  83 * [`postcss-write-svg`] allows you to write simple SVG directly in your CSS.
  84
  85 ### Linters
  86
  87 * [`stylelint`] is a modular stylesheet linter.
  88 * [`stylefmt`] is a tool that automatically formats CSS
  89   according `stylelint` rules.
  90 * [`doiuse`] lints CSS for browser support, using data from Can I Use.
  91 * [`colorguard`] helps you maintain a consistent color palette.
  92
  93 ### Other
  94
  95 * [`postcss-rtl`] combines both-directional (left-to-right and right-to-left) styles in one CSS file.
  96 * [`cssnano`] is a modular CSS minifier.
  97 * [`lost`] is a feature-rich `calc()` grid system.
  98 * [`rtlcss`] mirrors styles for right-to-left locales.
  99
 100 [PostCSS plugin development]: https://github.com/postcss/postcss/blob/master/docs/writing-a-plugin.md
 101 [`postcss-inline-svg`]:       https://github.com/TrySound/postcss-inline-svg
 102 [`react-css-modules`]:        https://github.com/gajus/react-css-modules
 103 [`postcss-autoreset`]:        https://github.com/maximkoretskiy/postcss-autoreset
 104 [`postcss-write-svg`]:        https://github.com/jonathantneal/postcss-write-svg
 105 [`postcss-utilities`]: https://github.com/ismamz/postcss-utilities
 106 [`postcss-initial`]:          https://github.com/maximkoretskiy/postcss-initial
 107 [`postcss-sprites`]:          https://github.com/2createStudio/postcss-sprites
 108 [`postcss-modules`]:          https://github.com/outpunk/postcss-modules
 109 [`postcss-sorting`]:          https://github.com/hudochenkov/postcss-sorting
 110 [`postcss-cssnext`]:          http://cssnext.io
 111 [`postcss-image-set-polyfill`]: https://github.com/SuperOl3g/postcss-image-set-polyfill
 112 [`postcss-assets`]:           https://github.com/assetsjs/postcss-assets
 113 [`font-magician`]:            https://github.com/jonathantneal/postcss-font-magician
 114 [`autoprefixer`]:             https://github.com/postcss/autoprefixer
 115 [`cq-prolyfill`]:             https://github.com/ausi/cq-prolyfill
 116 [`postcss-rtl`]:              https://github.com/vkalinichev/postcss-rtl
 117 [`postcss-use`]:              https://github.com/postcss/postcss-use
 118 [`css-modules`]:              https://github.com/css-modules/css-modules
 119 [`colorguard`]:               https://github.com/SlexAxton/css-colorguard
 120 [`stylelint`]:                https://github.com/stylelint/stylelint
 121 [`stylefmt`]:                 https://github.com/morishitter/stylefmt
 122 [`cssnano`]:                  http://cssnano.co
 123 [`precss`]:                   https://github.com/jonathantneal/precss
 124 [`doiuse`]:                   https://github.com/anandthakker/doiuse
 125 [`rtlcss`]:                   https://github.com/MohammadYounes/rtlcss
 126 [`short`]:                    https://github.com/jonathantneal/postcss-short
 127 [`lost`]:                     https://github.com/peterramsing/lost
 128 [`image-set`]:                https://drafts.csswg.org/css-images-3/#image-set-notation
 129
 130 ## Syntaxes
 131
 132 PostCSS can transform styles in any syntax, not just CSS.
 133 If there is not yet support for your favorite syntax,
 134 you can write a parser and/or stringifier to extend PostCSS.
 135
 136 * [`sugarss`] is a indent-based syntax like Sass or Stylus.
 137 * [`postcss-scss`] allows you to work with SCSS
 138   *(but does not compile SCSS to CSS)*.
 139 * [`postcss-sass`] allows you to work with Sass
 140     *(but does not compile Sass to CSS)*.
 141 * [`postcss-less`] allows you to work with Less
 142   *(but does not compile LESS to CSS)*.
 143 * [`postcss-less-engine`] allows you to work with Less
 144   *(and DOES compile LESS to CSS using true Less.js evaluation)*.
 145 * [`postcss-js`] allows you to write styles in JS or transform
 146   React Inline Styles, Radium or JSS.
 147 * [`postcss-safe-parser`] finds and fixes CSS syntax errors.
 148 * [`midas`] converts a CSS string to highlighted HTML.
 149
 150 [`sugarss`]:             https://github.com/postcss/sugarss
 151 [`postcss-scss`]:        https://github.com/postcss/postcss-scss
 152 [`postcss-sass`]:        https://github.com/AleshaOleg/postcss-sass
 153 [`postcss-less`]:        https://github.com/webschik/postcss-less
 154 [`postcss-less-engine`]: https://github.com/Crunch/postcss-less
 155 [`postcss-js`]:          https://github.com/postcss/postcss-js
 156 [`postcss-safe-parser`]: https://github.com/postcss/postcss-safe-parser
 157 [`midas`]:               https://github.com/ben-eb/midas
 158
 159 ## Articles
 160
 161 * [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)
 162 * [What PostCSS Really Is; What It Really Does](http://davidtheclark.com/its-time-for-everyone-to-learn-about-postcss)
 163 * [PostCSS Guides](http://webdesign.tutsplus.com/series/postcss-deep-dive--cms-889)
 164
 165 More articles and videos you can find on [awesome-postcss](https://github.com/jjaderg/awesome-postcss) list.
 166
 167 ## Books
 168
 169 * [Mastering PostCSS for Web Design](https://www.packtpub.com/web-development/mastering-postcss-web-design) by Alex Libby, Packt. (June 2016)
 170
 171 ## Usage
 172
 173 You can start using PostCSS in just two steps:
 174
 175 1. Find and add PostCSS extensions for your build tool.
 176 2. [Select plugins] and add them to your PostCSS process.
 177
 178 [Select plugins]: http://postcss.parts
 179
 180 ### Webpack
 181
 182 Use [`postcss-loader`] in `webpack.config.js`:
 183
 184 ```js
 185 module.exports = {
 186     module: {
 187         loaders: [
 188             {
 189                 test: /\.css$/,
 190                 exclude: /node_modules/,
 191                 use: [
 192                     {
 193                         loader: 'style-loader',
 194                     },
 195                     {
 196                         loader: 'css-loader',
 197                         options: {
 198                             sourceMap: true,
 199                             importLoaders: 1,
 200                         }
 201                     },
 202                     {
 203                         loader: 'postcss-loader',
 204                         options: {
 205                             sourceMap: 'inline',
 206                         }
 207                     }
 208                 ]
 209             }
 210         ]
 211     }
 212 }
 213 ```
 214
 215 Then create `postcss.config.js`:
 216
 217 ```js
 218 module.exports = {
 219     plugins: [
 220         require('precss'),
 221         require('autoprefixer')
 222     ]
 223 }
 224 ```
 225
 226 [`postcss-loader`]: https://github.com/postcss/postcss-loader
 227
 228 ### Gulp
 229
 230 Use [`gulp-postcss`] and [`gulp-sourcemaps`].
 231
 232 ```js
 233 gulp.task('css', function () {
 234     var postcss    = require('gulp-postcss');
 235     var sourcemaps = require('gulp-sourcemaps');
 236
 237     return gulp.src('src/**/*.css')
 238         .pipe( sourcemaps.init() )
 239         .pipe( postcss([ require('precss'), require('autoprefixer') ]) )
 240         .pipe( sourcemaps.write('.') )
 241         .pipe( gulp.dest('build/') );
 242 });
 243 ```
 244
 245 [`gulp-sourcemaps`]: https://github.com/floridoo/gulp-sourcemaps
 246 [`gulp-postcss`]:    https://github.com/postcss/gulp-postcss
 247
 248 ### npm run / CLI
 249
 250 To use PostCSS from your command-line interface or with npm scripts
 251 there is [`postcss-cli`].
 252
 253 ```sh
 254 postcss --use autoprefixer -c options.json -o main.css css/*.css
 255 ```
 256
 257 [`postcss-cli`]: https://github.com/postcss/postcss-cli
 258
 259 ### Browser
 260
 261 If you want to compile CSS string in browser (for instance, in live edit
 262 tools like CodePen), just use [Browserify] or [webpack]. They will pack
 263 PostCSS and plugins files into a single file.
 264
 265 To apply PostCSS plugins to React Inline Styles, JSS, Radium
 266 and other [CSS-in-JS], you can use [`postcss-js`] and transforms style objects.
 267
 268 ```js
 269 var postcss  = require('postcss-js');
 270 var prefixer = postcss.sync([ require('autoprefixer') ]);
 271
 272 prefixer({ display: 'flex' }); //=> { display: ['-webkit-box', '-webkit-flex', '-ms-flexbox', 'flex'] }
 273 ```
 274
 275 [`postcss-js`]: https://github.com/postcss/postcss-js
 276 [Browserify]:   http://browserify.org/
 277 [webpack]:      https://webpack.github.io/
 278 [CSS-in-JS]:    https://github.com/MicheleBertoli/css-in-js
 279
 280 ### Runners
 281
 282 * **Grunt**: [`grunt-postcss`](https://github.com/nDmitry/grunt-postcss)
 283 * **HTML**: [`posthtml-postcss`](https://github.com/posthtml/posthtml-postcss)
 284 * **Stylus**: [`poststylus`](https://github.com/seaneking/poststylus)
 285 * **Rollup**: [`rollup-plugin-postcss`](https://github.com/egoist/rollup-plugin-postcss)
 286 * **Brunch**: [`postcss-brunch`](https://github.com/brunch/postcss-brunch)
 287 * **Broccoli**: [`broccoli-postcss`](https://github.com/jeffjewiss/broccoli-postcss)
 288 * **Meteor**: [`postcss`](https://atmospherejs.com/juliancwirko/postcss)
 289 * **ENB**: [`enb-postcss`](https://github.com/awinogradov/enb-postcss)
 290 * **Fly**: [`fly-postcss`](https://github.com/postcss/fly-postcss)
 291 * **Start**: [`start-postcss`](https://github.com/start-runner/postcss)
 292 * **Connect/Express**: [`postcss-middleware`](https://github.com/jedmao/postcss-middleware)
 293
 294 ### JS API
 295
 296 For other environments, you can use the JS API:
 297
 298 ```js
 299 const fs = require('fs');
 300 const postcss = require('postcss');
 301 const precss = require('precss');
 302 const autoprefixer = require('autoprefixer');
 303
 304 fs.readFile('src/app.css', (err, css) => {
 305     postcss([precss, autoprefixer])
 306         .process(css, { from: 'src/app.css', to: 'dest/app.css' })
 307         .then(result => {
 308             fs.writeFile('dest/app.css', result.css);
 309             if ( result.map ) fs.writeFile('dest/app.css.map', result.map);
 310         });
 311 });
 312 ```
 313
 314 Read the [PostCSS API documentation] for more details about the JS API.
 315
 316 All PostCSS runners should pass [PostCSS Runner Guidelines].
 317
 318 [PostCSS Runner Guidelines]: https://github.com/postcss/postcss/blob/master/docs/guidelines/runner.md
 319 [PostCSS API documentation]: http://api.postcss.org/postcss.html
 320
 321 ### Options
 322
 323 Most PostCSS runners accept two parameters:
 324
 325 * An array of plugins.
 326 * An object of options.
 327
 328 Common options:
 329
 330 * `syntax`: an object providing a syntax parser and a stringifier.
 331 * `parser`: a special syntax parser (for example, [SCSS]).
 332 * `stringifier`: a special syntax output generator (for example, [Midas]).
 333 * `map`: [source map options].
 334 * `from`: the input file name (most runners set it automatically).
 335 * `to`: the output file name (most runners set it automatically).
 336
 337 [source map options]: https://github.com/postcss/postcss/blob/master/docs/source-maps.md
 338 [Midas]:              https://github.com/ben-eb/midas
 339 [SCSS]:               https://github.com/postcss/postcss-scss
 340
 341 ### Node.js 0.10 and the Promise API
 342
 343 If you want to run PostCSS in Node.js 0.10, add the [Promise polyfill]:
 344
 345 ```js
 346 require('es6-promise').polyfill();
 347 var postcss = require('postcss');
 348 ```
 349
 350 [Promise polyfill]: https://github.com/jakearchibald/es6-promise
 351
 352 ## Editors & IDE Integration
 353
 354 ### Atom
 355
 356 * [`language-postcss`] adds PostCSS and [SugarSS] highlight.
 357 * [`source-preview-postcss`] previews your output CSS in a separate, live pane.
 358
 359 [SugarSS]: https://github.com/postcss/sugarss
 360
 361 ### Sublime Text
 362
 363 * [`Syntax-highlighting-for-PostCSS`] adds PostCSS highlight.
 364
 365 [`Syntax-highlighting-for-PostCSS`]: https://github.com/hudochenkov/Syntax-highlighting-for-PostCSS
 366 [`source-preview-postcss`]:          https://atom.io/packages/source-preview-postcss
 367 [`language-postcss`]:                https://atom.io/packages/language-postcss
 368
 369 ### Vim
 370
 371 * [`postcss.vim`] adds PostCSS highlight.
 372
 373 [`postcss.vim`]: https://github.com/stephenway/postcss.vim
 374
 375 ### WebStorm
 376
 377 WebStorm 2016.3 [has] built-in PostCSS support.
 378
 379 [has]: https://blog.jetbrains.com/webstorm/2016/08/webstorm-2016-3-early-access-preview/