.config/coc/extensions/node_modules/coc-prettier/node_modules/stylelint/lib/rules/at-rule-empty-line-before/README.md

   1 # at-rule-empty-line-before
   2
   3 Require or disallow an empty line before at-rules.
   4
   5 ```css
   6 a {}
   7           /* ← */
   8 @media {} /* ↑ */
   9 /**          ↑
  10  *   This line */
  11 ```
  12
  13 If the at-rule is the very first node in a stylesheet then it is ignored. `@import` in Less will also be ignored.
  14
  15 The `--fix` option on the [command line](../../../docs/user-guide/cli.md#autofixing-errors) can automatically fix all of the problems reported by this rule. We recommend to enable [`indentation`](../indentation/README.md) rule for better autofixing results with this rule.
  16
  17 ## Options
  18
  19 `string`: `"always"|"never"`
  20
  21 ### `"always"`
  22
  23 There *must always* be an empty line before at-rules.
  24
  25 The following patterns are considered violations:
  26
  27 ```css
  28 a {} @media {}
  29 ```
  30
  31 ```css
  32 a {}
  33 @media {}
  34 ```
  35
  36 The following patterns are *not* considered violations:
  37
  38 ```css
  39 a {}
  40
  41 @media {}
  42 ```
  43
  44 ### `"never"`
  45
  46 There *must never* be an empty line before at-rules.
  47
  48 The following patterns are considered violations:
  49
  50 ```css
  51 a {}
  52
  53 @media {}
  54 ```
  55
  56 The following patterns are *not* considered violations:
  57
  58 ```css
  59 a {} @media {}
  60 ```
  61
  62 ```css
  63 a {}
  64 @media {}
  65 ```
  66
  67 ## Optional secondary options
  68
  69 ### `except: ["after-same-name", "inside-block", "blockless-after-same-name-blockless", "blockless-after-blockless", "first-nested"]`
  70
  71 #### `"after-same-name"`
  72
  73 Reverse the primary option for at-rules that follow another at-rule with the same name.
  74
  75 This means that you can group your at-rules by name.
  76
  77 For example, with `"always"`:
  78
  79 The following patterns are *not* considered violations:
  80
  81 ```css
  82 @charset "UTF-8";
  83
  84 @import url(x.css);
  85 @import url(y.css);
  86
  87 @media (min-width: 100px) {}
  88 @media (min-width: 200px) {}
  89 ```
  90
  91 ```css
  92 a {
  93
  94   @extends .foo;
  95   @extends .bar;
  96
  97   @include x;
  98   @include y {}
  99 }
 100 ```
 101
 102 #### `"inside-block"`
 103
 104 Reverse the primary option for at-rules that are nested.
 105
 106 For example, with `"always"`:
 107
 108 The following patterns are considered violations:
 109
 110 ```css
 111 a {
 112
 113   @extend foo;
 114   color: pink;
 115 }
 116
 117 b {
 118   color: pink;
 119
 120   @extend foo;
 121 }
 122 ```
 123
 124 The following patterns are *not* considered violations:
 125
 126 ```css
 127 a {
 128   @extend foo;
 129   color: pink;
 130 }
 131
 132 b {
 133   color: pink;
 134   @extend foo;
 135 }
 136 ```
 137
 138 #### `"blockless-after-same-name-blockless"`
 139
 140 Reverse the primary option for blockless at-rules that follow another blockless at-rule with the same name.
 141
 142 This means that you can group your blockless at-rules by name.
 143
 144 Shared-line comments do not affect this option.
 145
 146 For example, with `"always"`:
 147
 148 The following patterns are *not* considered violations:
 149
 150 ```css
 151 @charset "UTF-8";
 152
 153 @import url(x.css);
 154 @import url(y.css);
 155 ```
 156
 157 ```css
 158 @charset "UTF-8";
 159
 160 @import url(x.css); /* comment */
 161 @import url(y.css);
 162 ```
 163
 164 ```css
 165 a {
 166
 167   @extends .foo;
 168   @extends .bar;
 169
 170   @include loop;
 171   @include doo;
 172 }
 173 ```
 174
 175 #### `"blockless-after-blockless"`
 176
 177 Reverse the primary option for at-rules within a blockless group.
 178
 179 Shared-line comments do not affect this option.
 180
 181 For example, with `"always"`:
 182
 183 The following patterns are considered violations:
 184
 185 ```css
 186 @import url(x.css);
 187
 188 @import url(y.css);
 189
 190 @media print {}
 191 ```
 192
 193 The following patterns are *not* considered violations:
 194
 195 ```css
 196 @import url(x.css);
 197 @import url(y.css);
 198
 199 @media print {}
 200 ```
 201
 202 ```css
 203 @import url(x.css); /* comment */
 204 @import url(y.css);
 205
 206 @media print {}
 207 ```
 208
 209 #### `"first-nested"`
 210
 211 Reverse the primary option for at-rules that are nested and the first child of their parent node.
 212
 213 For example, with `"always"`:
 214
 215 The following patterns are considered violations:
 216
 217 ```css
 218 a {
 219
 220   @extend foo;
 221   color: pink;
 222 }
 223
 224 b {
 225   color: pink;
 226   @extend foo;
 227 }
 228 ```
 229
 230 The following patterns are *not* considered violations:
 231
 232 ```css
 233 a {
 234   @extend foo;
 235   color: pink;
 236 }
 237
 238 b {
 239   color: pink;
 240
 241   @extend foo;
 242 }
 243 ```
 244
 245 ### `ignore: ["after-comment", "inside-block", "blockless-after-same-name-blockless", "blockless-after-blockless"]`
 246
 247 #### `"after-comment"`
 248
 249 Ignore at-rules that come after a comment.
 250
 251 Shared-line comments do not trigger this option.
 252
 253 The following patterns are *not* considered violations:
 254
 255 ```css
 256 /* comment */
 257 @media {}
 258 ```
 259
 260 ```css
 261 /* comment */
 262
 263 @media {}
 264 ```
 265
 266 ```css
 267 @media {} /* comment */
 268
 269 @media {}
 270 ```
 271
 272 #### `"inside-block"`
 273
 274 Ignore at-rules that are inside a declaration block.
 275
 276 For example, with `"always"`:
 277
 278 The following patterns are *not* considered violations:
 279
 280 ```css
 281 a {
 282   @extend foo;
 283   color: pink;
 284 }
 285
 286 a {
 287
 288   @extend foo;
 289   color: pink;
 290 }
 291
 292 b {
 293   color: pink;
 294   @extend foo;
 295 }
 296
 297 b {
 298   color: pink;
 299
 300   @extend foo;
 301 }
 302 ```
 303
 304 #### `"blockless-after-same-name-blockless"`
 305
 306 Ignore blockless at-rules that follow another blockless at-rule with the same name.
 307
 308 This means that you can group your blockless at-rules by name.
 309
 310 For example, with `"always"`:
 311
 312 The following patterns are *not* considered violations:
 313
 314 ```css
 315
 316 @charset "UTF-8";
 317
 318 @import url(x.css);
 319 @import url(y.css);
 320 ```
 321
 322 ```css
 323 a {
 324
 325   @extends .foo;
 326   @extends .bar;
 327
 328   @include loop;
 329   @include doo;
 330 }
 331 ```
 332
 333 #### `"blockless-after-blockless"`
 334
 335 Ignore blockless at-rules that follow another blockless at-rule.
 336
 337 For example, with `"always"`:
 338
 339 The following patterns are *not* considered violations:
 340
 341 ```css
 342 @import url(x.css);
 343
 344 @import url(y.css);
 345
 346 @media print {}
 347 ```
 348
 349 ```css
 350 @import url(x.css);
 351 @import url(y.css);
 352
 353 @media print {}
 354 ```
 355
 356 ### `ignoreAtRules: ["array", "of", "at-rules"]`
 357
 358 Ignore specified at-rules.
 359
 360 For example, with `"always"`.
 361
 362 Given:
 363
 364 ```js
 365 ["import"]
 366 ```
 367
 368 The following patterns are *not* considered violations:
 369
 370 ```css
 371 @charset "UTF-8";
 372 @import {}
 373 ```