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

   1 # Configuration
   2
   3 The linter *expects a configuration object*. You can either craft your own config or extend an existing one.
   4
   5 ## Loading the configuration object
   6
   7 Finding and loading of your configuration object is done with [cosmiconfig](https://github.com/davidtheclark/cosmiconfig). Starting from the current working directory, it will look for the following possible sources, in this order:
   8
   9 -   a `stylelint` property in `package.json`
  10 -   a `.stylelintrc` file
  11 -   a `stylelint.config.js` file exporting a JS object
  12
  13 The `.stylelintrc` file (without extension) can be in JSON or YAML format. Alternately, you can add a filename extension to designate JSON, YAML, or JS format: `.stylelintrc.json`, `.stylelintrc.yaml`, `.stylelintrc.yml`, `.stylelintrc.js`. You may want to use an extension so that your text editor can better interpret the file, and help with syntax checking and highlighting.
  14
  15 Once one of these is found and parsed, the search will stop and that object will be used.
  16
  17 The configuration search can be short-circuited by using either the `config` or `configFile` options.
  18
  19 ## The configuration object
  20
  21 The configuration object can have the following properties.
  22
  23 ### `rules`
  24
  25 Rules determine what the linter looks for and complains about. There are [over 150](rules.md) built into stylelint. *No rules are turned on by default*, so this is where you turn on everything you want to check. All the rules must be explicitly configured as *there are no default values*.
  26
  27 The `rules` property is *an object whose keys are rule names and values are rule configurations*. Each rule configuration fits one of the following formats:
  28
  29 -   a single value (the primary option)
  30 -   an array with two values (`[primary option, secondary options]`)
  31 -   `null` (to turn the rule off)
  32
  33 ```json
  34 {
  35   "rules": {
  36     "block-no-empty": null,
  37     "color-no-invalid-hex": true,
  38     "comment-empty-line-before": [ "always", {
  39       "ignore": ["stylelint-commands", "after-comment"]
  40     } ],
  41     "declaration-colon-space-after": "always",
  42     "indentation": ["tab", {
  43       "except": ["value"]
  44     }],
  45     "max-empty-lines": 2,
  46     "rule-empty-line-before": [ "always", {
  47       "except": ["first-nested"],
  48       "ignore": ["after-comment"]
  49     } ],
  50     "unit-whitelist": ["em", "rem", "%", "s"]
  51   }
  52 }
  53 ```
  54
  55 Specifying a primary option will turn a rule on. A complete list of primary rule options can be found in the [example configuration](example-config.md).
  56
  57 To turn a rule off (when extending a configuration) you can set the value of the rule to `null`:
  58
  59 ```json
  60 {
  61   "extends": "stylelint-config-standard",
  62   "rules": {
  63     "at-rule-empty-line-before": null
  64   }
  65 }
  66 ```
  67
  68 Many rules have secondary options which provide further customization. To set secondary options, a two-member array is used:
  69
  70 ```js
  71 "selector-pseudo-class-no-unknown": [true, {
  72   "ignorePseudoClasses": ["global"]
  73 }]
  74 ```
  75
  76 #### Turning rules off from within your CSS
  77
  78 Rules can be temporarily turned off by using special comments in your CSS. For example, you can either turn all the rules off:
  79
  80 ```css
  81 /* stylelint-disable */
  82 a {}
  83 /* stylelint-enable */
  84 ```
  85
  86 Or you can turn off individual rules:
  87
  88 ```css
  89 /* stylelint-disable selector-no-id, declaration-no-important  */
  90 #id {
  91   color: pink !important;
  92 }
  93 /* stylelint-enable */
  94 ```
  95
  96 You can turn off rules for individual lines only with a `/* stylelint-disable-line */` comment, after which you do not need to explicitly re-enable them:
  97
  98 ```css
  99 #id { /* stylelint-disable-line */
 100   color: pink !important; /* stylelint-disable-line declaration-no-important */
 101 }
 102 ```
 103
 104 You can also turn off rules for *the next line only* with a `/* stylelint-disable-next-line */` comment, after which you do not need to explicitly re-enable them:
 105
 106 ```css
 107 #id {
 108   /* stylelint-disable-next-line declaration-no-important */
 109   color: pink !important;
 110 }
 111 ```
 112
 113 Complex, overlapping disabling & enabling patterns are supported:
 114
 115 ```css
 116 /* stylelint-disable */
 117 /* stylelint-enable foo */
 118 /* stylelint-disable foo */
 119 /* stylelint-enable */
 120 /* stylelint-disable foo, bar */
 121 /* stylelint-disable baz */
 122 /* stylelint-enable baz, bar */
 123 /* stylelint-enable foo */
 124 ```
 125
 126 **Caveat:** Comments within *selector and value lists* are currently ignored.
 127
 128 #### Severities: error & warning
 129
 130 By default, all rules have an `"error"`-level severity. You can change this default by adding a `defaultSeverity` property to your configuration (see below).
 131
 132 To adjust any specific rule's severity, use the secondary option `severity`. The available values for `severity` are:
 133
 134 -   `"warning"`
 135 -   `"error"`
 136
 137 ```js
 138 // error-level severity examples
 139 { "indentation": 2 }
 140 { "indentation": [2] }
 141
 142 // warning-level severity examples
 143 { "indentation": [2, { "severity": "warning" } ] }
 144 { "indentation": [2, {
 145     "except": ["value"],
 146     "severity": "warning"
 147   }]
 148 }
 149 ```
 150
 151 Different reporters may use these severity levels in different way, e.g. display them differently, or exit the process differently.
 152
 153 #### Custom Messages
 154
 155 If you want to deliver a custom message when a rule is violated, you can do so in two ways: provide a `message` option for the rule, or write a custom formatter.
 156
 157 All rules accept a `message` secondary option that, if provided, will be substituted for whatever standard message would be provided. For example, the following rule configuration would substitute in a couple of custom message:
 158
 159 ```json
 160 {
 161   "color-hex-case": [ "lower", {
 162     "message": "Lowercase letters are easier to distinguish from numbers"
 163   } ],
 164   "indentation": [ 2, {
 165     "except": ["block"],
 166     "message": "Please use 2 spaces for indentation. Tabs make The Architect grumpy.",
 167     "severity": "warning"
 168   } ]
 169 }
 170 ```
 171
 172 Writing a [custom formatter](../developer-guide/formatters.md) gives you maximum control if you need serious customization.
 173
 174 ### `extends`
 175
 176 Your configuration can *extend* an existing configuration (whether your own or a third-party config). When one configuration extends another, it starts with the other's properties then adds to and overrides what's there.
 177
 178 You can extend an array of existing configurations, with each item in the array taking precedence over the previous item (so the second item overrides rules in the first, the third item overrides rules in the first and the second, and so on, the last item overrides everything else).
 179
 180 For example, extending the [`stylelint-config-standard`](https://github.com/stylelint/stylelint-config-standard) and then changing indentation to tabs and turning off the `number-leading-zero` rule:
 181
 182 ```json
 183 {
 184   "extends": "stylelint-config-standard",
 185   "rules": {
 186     "indentation": "tab",
 187     "number-leading-zero": null
 188   }
 189 }
 190 ```
 191
 192 Or starting with `stylelint-config-standard`, then layering `myExtendableConfig` on top of that, and then overriding the indentation rule:
 193
 194 ```json
 195 {
 196   "extends": [
 197     "stylelint-config-standard",
 198     "./myExtendableConfig"
 199   ],
 200   "rules": {
 201     "indentation": "tab"
 202   }
 203 }
 204 ```
 205
 206 The value of `"extends"` is a "locater" (or an array of "locaters") that is ultimately `require()`d, so can fit whatever format works with Node's `require.resolve()` algorithm. That means a "locater" can be:
 207
 208 -   The name of a module in `node_modules` (e.g. `stylelint-config-standard`; that module's `main` file must be a valid JSON configuration)
 209 -   An absolute path to a file (which makes sense if you're creating a JS object in a Node context and passing it in) with a `.js` or `.json` extension.
 210 -   A relative path to a file with a `.js` or `.json` extension, relative to the referencing configuration (e.g. if configA has `extends: "../configB"`, we'll look for `configB` relative to configA).
 211
 212 *Because of `extends`, you can create and use shareable stylelint configurations.* Use the `stylelint-config` keyword within your `package.json` if publishing your config to npm.
 213
 214 ### `plugins`
 215
 216 Plugins are rules or sets of rules built by the community that support methodologies, toolsets, *non-standard* CSS features, or very specific use cases.
 217
 218 To use one, add a `"plugins"` array to your config, containing "locaters" identifying the plugins you want to use. As with `extends`, above, a "locater" can be either an npm module name, an absolute path, or a path relative to the invoking configuration file.
 219
 220 Once the plugin is declared, within your `"rules"` object *you'll need to add options* for the plugin's rule(s), just like any standard rule. You will have to look at the plugin's documentation to know what the rule name should be.
 221
 222 ```json
 223 {
 224   "plugins": [
 225     "../special-rule.js"
 226   ],
 227   "rules": {
 228     "plugin/special-rule": "everything"
 229   }
 230 }
 231 ```
 232
 233 A "plugin" can provide a single rule or a set of rules. If the plugin you use provides a set, just invoke the module in your `"plugins"` configuration value, and use the rules it provides in `"rules"`. For example:
 234
 235 ```json
 236 {
 237   "plugins": [
 238     "../some-rule-set.js"
 239   ],
 240   "rules": {
 241     "some-rule-set/first-rule": "everything",
 242     "some-rule-set/second-rule": "nothing",
 243     "some-rule-set/third-rule": "everything"
 244   }
 245 }
 246 ```
 247
 248 ### `processors`
 249
 250 Processors are functions that hook into stylelint's pipeline, modifying code on its way into stylelint and modifying results on their way out.
 251
 252 *Processors can only be used with the CLI and the Node API, not with the PostCSS plugin.* (The PostCSS plugin will ignore them.)
 253
 254 Processors can enable stylelint to lint the CSS within non-stylesheet files. For example, you could lint the CSS within `<style>` tags in HTML, code blocks in Markdown, or strings in JavaScript.
 255
 256 To use one, add a `"processors"` array to your config, containing "locaters" identifying the processors you want to use. As with `extends`, above, a "locater" can be either an npm module name, an absolute path, or a path relative to the invoking configuration file.
 257
 258 ```json
 259 {
 260   "processors": ["stylelint-html-processor"],
 261   "rules": {..}
 262 }
 263 ```
 264
 265 If your processor has options, make that item an array whose first item is the "locator" and second item is the options object.
 266
 267 ```json
 268 {
 269   "processors": [
 270     "stylelint-html-processor",
 271     [ "some-other-processor", { "optionOne": true, "optionTwo": false } ]
 272   ],
 273   "rules": {..}
 274 }
 275 ```
 276
 277 ### `ignoreFiles`
 278
 279 Provide a glob or array of globs to ignore specific files.
 280
 281 *Note that this is not an efficient method for ignoring lots of files.* If you want to ignore a lot of files efficiently, use `.stylelintignore` or adjust your files globs.
 282
 283 If the globs are absolute paths, they are used as is. If they are relative, they are analyzed relative to
 284
 285 -   `configBasedir`, if it's provided;
 286 -   the config's filepath, if the config is a file that stylelint found a loaded;
 287 -   or `process.cwd()`.
 288
 289 By default, all `node_modules` and `bower_components` are ignored. Default values will be overridden if `ignoreFiles` is set.
 290
 291 The `ignoreFiles` property is stripped from extended configs: only the root-level config can ignore files.
 292
 293 ### `defaultSeverity`
 294
 295 The default severity level for all rules that do not have a severity specified in their secondary options. The available values for `severity` are:
 296
 297 -   `"warning"`
 298 -   `"error"`
 299
 300 ## `.stylelintignore`
 301
 302 You can use a `.stylelintignore` file (or point to another ignore patterns file) to ignore specific files.
 303
 304 These files will be excluded from the files glob before the file system is check at all, so it is an efficient method for ignoring lots of files.
 305
 306 The patterns in your `.stylelintignore` file must match [`.gitignore` syntax](https://git-scm.com/docs/gitignore). (Behind the scenes, [`node-ignore`](https://github.com/kaelzhang/node-ignore) parses your patterns.) One implication of this is that *your patterns in `.stylelintignore` are always analyzed relative to `process.cwd()`.*
 307
 308 stylelint will look for a `.stylelintignore` file in `process.cwd()`. You can also specify a path to your ignore patterns file (absolute or relative to `process.cwd()`) using the `--ignore-path` (in the CLI) and `ignorePath` (in JS) options.