.config/coc/extensions/node_modules/coc-prettier/node_modules/stylelint/docs/user-guide/postcss-plugin.md

   1 # The stylelint PostCSS plugin
   2
   3 As with any other [PostCSS plugin](https://github.com/postcss/postcss#plugins), you can use stylelint's PostCSS plugin either with a PostCSS runner or with the PostCSS JS API directly.
   4
   5 *However, if a dedicated stylelint task runner plugin [is available](complementary-tools.md) (e.g. [gulp-stylelint](https://github.com/olegskl/gulp-stylelint) or [grunt-stylelint](https://github.com/wikimedia/grunt-stylelint)) we recommend you use that rather than this plugin, as they provide better reporting.*
   6
   7 ## Installation
   8
   9 stylelint is an [npm package](https://www.npmjs.com/package/stylelint). Install it using:
  10
  11 ```console
  12 npm install stylelint
  13 ```
  14
  15 ## Options
  16
  17 The plugin accepts an options object as argument, with the following properties:
  18
  19 ### `config`
  20
  21 A [stylelint configuration object](configuration.md).
  22
  23 If no `config` or `configFile` is passed, stylelint will look for a `.stylelintrc` configuration file.
  24
  25 ### `configFile`
  26
  27 The path to a JSON, YAML, or JS file that contains your [stylelint configuration object](configuration.md).
  28
  29 It should be either absolute or relative to the directory that your process is running from (`process.cwd()`). We'd recommend absolute.
  30
  31 ### `configBasedir`
  32
  33 An absolute path to the directory that relative paths defining `extends` and `plugins` are *relative to*.
  34
  35 This is only necessary if you passed an object directly through the `config` property. If you used
  36 `configFile`, this option is not necessary.
  37
  38 If the `config` object passed uses relative paths, e.g. for `extends` or `plugins`, you are going to have to pass a `configBasedir`. If not, you do not need this.
  39
  40 ### `configOverrides`
  41
  42 A partial stylelint configuration object whose properties will override the existing config object, whether that config was loaded via the `config` option or a `.stylelintrc` file.
  43
  44 The difference between the `configOverrides` and `config` options is this: If any `config` object is passed, stylelint does not bother looking for a `.stylelintrc` file and instead just uses whatever `config` object you've passed; but if you want to *both* load a `.stylelintrc` file *and* override specific parts of it, `configOverrides` does just that.
  45
  46 ### `ignoreDisables`
  47
  48 If `true`, all disable comments (e.g. `/* stylelint-disable block-no-empty */`) will be ignored.
  49
  50 You can use this option to see what your linting results would be like without those exceptions.
  51
  52 ### `ignorePath`
  53
  54 A path to a file containing patterns describing files to ignore. The path can be absolute or relative to `process.cwd()`. By default, stylelint looks for `.stylelintignore` in `process.cwd()`. See [Configuration](configuration.md#stylelintignore).
  55
  56 ## Usage examples
  57
  58 We recommend you lint your CSS before applying any transformations. You can do this by either:
  59
  60 -   creating a separate lint task that is independent of your build one.
  61 -   using the [`plugins` option](https://github.com/postcss/postcss-import#plugins) of [`postcss-import`](https://github.com/postcss/postcss-import) or [`postcss-easy-import`](https://github.com/TrySound/postcss-easy-import) to lint your files before any transformations.
  62 -   placing stylelint at the beginning of your plugin pipeline.
  63
  64 You'll also need to use a reporter. *The stylelint plugin registers warnings via PostCSS*. Therefore, you'll want to use it with a PostCSS runner that prints warnings or another PostCSS plugin whose purpose is to format and print warnings (e.g. [`postcss-reporter`](https://github.com/postcss/postcss-reporter)).
  65
  66 ### Example A
  67
  68 A separate lint task that uses the plugin via the PostCSS JS API to lint Less using [`postcss-less`](https://github.com/shellscape/postcss-less).
  69
  70 *Note: the stylelint PostCSS plugin, unlike the stylelint CLI and node API, doesn't have a `syntax` option. Instead, the syntax must be set within the [PostCSS options](https://github.com/postcss/postcss#options) as there can only be one parser/syntax in a pipeline.*
  71
  72 ```js
  73 var fs = require("fs")
  74 var less = require("postcss-less")
  75 var postcss = require("postcss")
  76
  77 // CSS to be processed
  78 var css = fs.readFileSync("input.css", "utf8")
  79
  80 postcss([
  81   require("stylelint")({ /* your options */ }),
  82   require("postcss-reporter")({ clearReportedMessages: true })
  83 ])
  84   .process(css, {
  85     from: "input.css",
  86     syntax: less
  87   })
  88   .then()
  89   .catch(err => console.error(err.stack))
  90 ```
  91
  92 The same pattern can be used to lint SCSS or [SugarSS](https://github.com/postcss/sugarss) syntax.
  93
  94 ### Example B
  95
  96 A combined lint and build task where the plugin is used via the PostCSS JS API, but within [`postcss-import`](https://github.com/postcss/postcss-import) (using the its `plugins` option) so that the source files are linted before any transformations.
  97
  98 ```js
  99 var fs = require("fs")
 100 var postcss = require("postcss")
 101 var stylelint = require("stylelint")
 102
 103 // CSS to be processed
 104 var css = fs.readFileSync("lib/app.css", "utf8")
 105
 106 postcss(
 107   [
 108     require("postcss-import")({
 109       plugins: [
 110         require("stylelint")({ /* your options */ })
 111       ]
 112     }),
 113     require("postcss-cssnext"),
 114     require("postcss-reporter")({ clearReportedMessages: true })
 115   ]
 116 )
 117   .process(css, { from: 'lib/app.css', to: 'app.css' })
 118   .then(function (result) {
 119     fs.writeFileSync('app.css', result.css);
 120     if ( result.map ) fs.writeFileSync('app.css.map', result.map);
 121   })
 122   .catch(err => console.error(err.stack))
 123 ```