Prepare 15.0.0 docs

CONTRIBUTING.md

@@ -5,15 +5,13 @@ Thank you for wanting to contribute.
 To help out, you can:
 
 - get involved in any open [issue](https://github.com/stylelint/stylelint/issues) or [pull request](https://github.com/stylelint/stylelint/pulls)
-- maintain [community custom syntaxes](docs/developer-guide/syntaxes.md)
 - create, enhance and debug rules using [our guide](docs/developer-guide/rules.md)
 - improve the [documentation](docs/)
 - add [new tests](https://github.com/stylelint/stylelint/issues?q=is%3Aopen+is%3Aissue+label%3A%22type%3A+tests%22) to _absolutely anything_
 - improve the [performance of rules](docs/developer-guide/rules.md#improve-the-performance-of-a-rule)
 - open [new issues](https://github.com/stylelint/stylelint/issues/new/choose) about your ideas for making Stylelint better
-- create or contribute to [integrations](docs/user-guide/integrations/editor.md), like our plugin for [VS Code](https://github.com/stylelint/vscode-stylelint)
 
-Not only will you help Stylelint thrive, but you may learn a thing or two — about CSS, PostCSS, Node, ES2015, unit testing, open-source software, and more. We want to encourage contributions! If you want to participate but couldn't, please [give us feedback](https://github.com/stylelint/stylelint/issues/new) about what we could do better.
+Not only will you help Stylelint thrive, but you may learn a thing or two — about CSS, PostCSS, Node.js, unit testing, open-source software, and more. We want to encourage contributions! If you want to participate but couldn't, please [give us feedback](https://github.com/stylelint/stylelint/issues/new) about what we could do better.
 
 ## Code contributions
 
@@ -25,7 +23,7 @@ To start coding, you'll need the:
 Then:
 
 1. [Fork and clone](https://guides.github.com/activities/forking/) the Stylelint repository.
-2. Install all the dependencies with `npm ci`.
+2. Install all the dependencies with `npm install`.
 
 ### Run tests
 
@@ -52,8 +50,6 @@ You can write code to:
 - [fix a bug in a rule](docs/developer-guide/rules.md#fix-a-bug-in-a-rule)
 - [improve the performance of a rule](docs/developer-guide/rules.md#improve-the-performance-of-a-rule)
 
-And many more things, including [writing system tests](docs/developer-guide/system-tests.md) and improving the [documentation](docs/).
-
 ### Format code
 
 We use [Prettier](https://prettier.io/) (with [a Husky and lint-staged precommit](https://prettier.io/docs/en/precommit.html)) to format your code automatically.

README.md

@@ -4,43 +4,41 @@
 [![Build Status](https://github.com/stylelint/stylelint/workflows/Testing/badge.svg)](https://github.com/stylelint/stylelint/actions/workflows/testing.yml?query=branch%3Amain)
 [![npm downloads](https://img.shields.io/npm/dm/stylelint)](https://npmcharts.com/compare/stylelint?minimal=true)
 
-A mighty, modern linter that helps you avoid errors and enforce conventions in your styles.
+A mighty CSS linter that helps you avoid errors and enforce conventions.
 
 ## Features
 
 It's mighty as it:
 
 - has over **100 built-in rules** for modern CSS syntax and features
-- supports **plugins** so you can create your own rules
+- supports **plugins** so you can create your own custom rules
 - automatically **fixes problems** where possible
-- is **well tested** with over 15000 unit tests
-- supports **shareable configs** that you can extend or create
-- is **unopinionated** so that you can customize it to your exact needs
-- **complements pretty printers** like Prettier
-- has a **growing community** and is used by Google, GitHub and WordPress
+- supports **shareable configs** that you can create or extend
+- can **be customized** to your exact needs
+- has **15k unit tests** making it robust
+- is **trusted by companies worldwide** like Google and GitHub
 
-And can be extended to:
+And it can be extended to:
 
-- parse **CSS-like syntaxes** like SCSS, Sass, Less and SugarSS
-- extract **embedded styles** from HTML, Markdown and CSS-in-JS object & template literals
+- extract **embedded styles** from HTML, Markdown and CSS-in-JS template literals
+- parse **CSS-like languages** like SCSS, Sass, Less and SugarSS
 
 ## How it'll help you
 
 It'll help you **avoid errors**, for example:
 
-- invalid things, e.g. malformed hex colors and named grid areas
-- unknown things, e.g. units and functions that aren't in the CSS specs
-- valid things that are problematic, e.g. duplicated selectors and overridden properties
+- invalid things, e.g. malformed grid areas
+- valid things that are problematic, e.g. duplicate selectors
+- unknown things, e.g. misspelled property names
 
 And **enforce conventions**, for example:
 
-- what units, functions, at-rules etc are allowed
-- consistent patterns for selector names, at-rule names, custom properties etc
-- maximum specificity or maximum quantity of each selector type
-- your preferred notation for color functions, font weight etc
-- consistent empty lines before constructs
+- disallow things, e.g. specific units
+- enforce naming patterns, e.g. for custom properties
+- set limits, e.g. the number of ID selectors
+- specify notations, e.g. for modern color functions
 
-We recommend using Stylelint alongside a pretty printer like Prettier. Linters and pretty printers are complementary tools that work together to help you write consistent and error-free code that is well-formatted.
+We recommend using a pretty printer like Prettier alongside Stylelint. Linters and pretty printers are complementary tools that work together to help you write consistent and error-free code.
 
 ## Example output
 
@@ -50,23 +48,17 @@ We recommend using Stylelint alongside a pretty printer like Prettier. Linters a
 
 - User guide
   - [Getting started](docs/user-guide/get-started.md)
-  - [Configuration](docs/user-guide/configure.md)
+  - [Customizing](docs/user-guide/customize.md)
+  - [Configuring](docs/user-guide/configure.md)
   - [Rules](docs/user-guide/rules.md)
-  - Usage
-    - [CLI](docs/user-guide/usage/cli.md)
-    - [Node.js API](docs/user-guide/usage/node-api.md)
-    - [PostCSS plugin](docs/user-guide/usage/postcss-plugin.md)
-    - [Options](docs/user-guide/usage/options.md)
-  - Integrations
-    - [Editor integrations](docs/user-guide/integrations/editor.md)
-    - [Task runner integrations](docs/user-guide/integrations/task-runner.md)
-    - [Other integrations](docs/user-guide/integrations/other.md)
   - [Ignoring code](docs/user-guide/ignore-code.md)
-  - [Combining rules](docs/user-guide/combine.md)
-  - [Using regex](docs/user-guide/regex.md)
+  - [CLI](docs/user-guide/cli.md)
+  - [Node.js API](docs/user-guide/node-api.md)
+  - [PostCSS plugin](docs/user-guide/postcss-plugin.md)
+  - [Options](docs/user-guide/options.md)
   - [Errors & warnings](docs/user-guide/errors.md)
 - Developer guide
-  - [Working on rules](docs/developer-guide/rules.md)
+  - [Writing rules](docs/developer-guide/rules.md)
   - [Writing plugins](docs/developer-guide/plugins.md)
   - [Writing custom syntaxes](docs/developer-guide/syntaxes.md)
   - [Writing custom formatters](docs/developer-guide/formatters.md)

SUPPORT.md

@@ -4,14 +4,12 @@ One of our frequently visited documentation sections might answer your query:
 
 - [Turning off rules](docs/user-guide/configure.md#rules)
 - [Ignoring code](docs/user-guide/ignore-code.md)
-- [Using regexes to configure rules](docs/user-guide/regex.md)
-- [Combining rules to enforce your code style](docs/user-guide/combine.md)
 
 If they don't, then post your query on [Stack Overflow](https://stackoverflow.com/questions/tagged/stylelint).
 
-Only create a [new issue](https://github.com/stylelint/stylelint/issues/new/choose) if:
+Only create a [new issue](https://github.com/stylelint/stylelint/issues/new/choose) if you:
 
-- you think you've found a bug
-- you have a feature request
+- think you've found a bug
+- have a feature request
 
 If you're upgrading, read our [CHANGELOG](CHANGELOG.md) to learn what changes to expect in the latest version.

docs/about/vision.md

@@ -4,8 +4,8 @@ A linter and validator for CSS that is:
 
 - complete - coverage of all standard CSS syntax
 - extensible - multiple points of extension
-- configurable - no defaults and options to tailor the linter
-- robust - comprehensive test coverage and a wide range of fixtures
+- configurable - options to tailor the linter
+- robust - comprehensive test coverage
 - consistent - conventions for behavior, naming and documentation
 - performant - tools to test and improve performance
 
@@ -23,7 +23,7 @@ Provide multiple points of extensions, including:
 - [custom syntaxes](../developer-guide/syntaxes.md) - use any PostCSS-compatible syntax to support other CSS-like languages and containers
 - [extendable configs](../user-guide/configure.md#extends) - extend and share configurations
 - [formatters](../developer-guide/formatters.md) - format Stylelint result objects
-- [plugins](../developer-guide/plugins.md) - build community rules to support methodologies, toolsets, non-standard CSS features, other languages (like SCSS) or very specific use cases
+- [plugins](../developer-guide/plugins.md) - build custom rules to support methodologies, toolsets, non-standard CSS features, other languages (like SCSS) or very specific use cases
 
 ## Robust
 

docs/developer-guide/plugins.md

@@ -1,8 +1,8 @@
 # Writing plugins
 
-Plugins are rules and sets of rules built by the community. They might support a particular methodology or toolset, or apply to non-standard constructs and features, or be for specific use cases.
+Plugins are custom rules and sets of custom rules. They might support a particular methodology or toolset, apply to non-standard constructs and features, or be for specific use cases.
 
-We recommend your plugin adheres to [Stylelint's conventions](rules.md) for:
+We recommend your custom rules adhere to our [rule conventions](rules.md) for:
 
 - names
 - options
@@ -210,7 +210,7 @@ it("doesn't warn for fileless sources", async () => {
 });
 ```
 
-Alternatively, if you don't want to use Jest you'll find more tools in [awesome stylelint](https://github.com/stylelint/awesome-stylelint#tools).
+Alternatively, if you don't want to use Jest you'll find more testing tool in [Awesome Stylelint](https://github.com/stylelint/awesome-stylelint#readme).
 
 ## `stylelint.utils`
 
@@ -288,7 +288,7 @@ All of the rule functions are available at `stylelint.rules`. This allows you to
 
 A typical use-case is to build in more complex conditionals that the rule's options allow for. For example, maybe your codebase uses special comment directives to customize rule options for specific stylesheets. You could build a plugin that checks those directives and then runs the appropriate rules with the right options (or doesn't run them at all).
 
-All rules share a common signature. They are a function that accepts two arguments: a primary option and a secondary options object. And that functions returns a function that has the signature of a PostCSS plugin, expecting a PostCSS root and result as its arguments.
+All rules share a common signature. They are a function that accepts two arguments: a primary option and a secondary options object. And that function returns a function that has the signature of a PostCSS plugin, expecting a PostCSS root and result as its arguments.
 
 Here's an example of a plugin that runs `declaration-no-important` only if there is a special directive `@@check-declaration-no-important` somewhere in the stylesheet:
 
@@ -317,18 +317,18 @@ In addition to the standard parsers mentioned in the ["Working on rules"](rules.
 
 - [postcss-resolve-nested-selector](https://github.com/davidtheclark/postcss-resolve-nested-selector): given a (nested) selector in a PostCSS AST, return an array of resolved selectors.
 
-Have a look through [Stylelint's internal utils](https://github.com/stylelint/stylelint/tree/main/lib/utils) and if you come across one that you need in your plugin, then please consider helping us extract it out into an external module.
+Have a look through [Stylelint's internal utils](https://github.com/stylelint/stylelint/tree/main/lib/utils) and if you come across one that you need in your plugin, then please consider helping us extract it into an external module.
 
 ## Peer dependencies
 
 You should express, within the `peerDependencies` key (and **not** within the `dependencies` key) of your plugin's `package.json`, what version(s) of Stylelint your plugin can be used with. This is to ensure that different versions of Stylelint are not unexpectedly installed.
 
-For example, to express that your plugin can be used with Stylelint versions 7 and 8:
+For example, to express that your plugin can be used with Stylelint versions 14 and 15:
 
 ```json
 {
   "peerDependencies": {
-    "stylelint": "^7.0.0 || ^8.0.0"
+    "stylelint": "^14.0.0 || ^15.0.0"
   }
 }
 ```

docs/developer-guide/rules.md

@@ -1,4 +1,4 @@
-# Working on rules
+# Writing rules
 
 Please help us create, enhance, and debug our rules!
 
@@ -15,23 +15,63 @@ A rule must be:
 
 And have a:
 
-- clear and unambiguous finished state
-- singular purpose; don't overlap with other rules
+- unambiguous finished state
+- singular purpose that doesn't overlap with other rules
 
-It's name is split into two parts:
+Its name is split into two parts:
 
 - the [_thing_](http://apps.workflower.fi/vocabs/css/en) the rule applies to, e.g. `at-rule`
 - what the rule is checking, e.g. `disallowed-list`
 
 Unless it applies to the whole source, then there is no first part.
 
+### Write tests
+
+You should add test cases for all patterns that are:
+
+- considered problems
+- _not_ considered problems
+
+You should use:
+
+- realistic CSS, avoiding the use of ellipses
+- the minimum amount of code possible, e.g. use an empty rule if targetting selectors
+- `{}` for empty rules, rather than `{ }`
+- the `a` type selector by default
+- the `@media` at-rules by default
+- the `color` property by default
+- the `red` value by default
+- the `(min-)width` media feature by default
+- _foo_, _bar_ and _baz_ for names, e.g. `.foo`, `#bar`, `--baz`
+
+You should:
+
+- vary column and line positions across your tests
+- include at least one test that has 2 warnings
+- test non-standard syntax in the `isStandardSyntax*` utilities, not in the rule itself
+
+#### Commonly overlooked edge-cases
+
+You should ask yourself how does your rule handle:
+
+- variables (e.g. `var(--custom-property)`)?
+- CSS strings (e.g. `content: "anything goes";`)?
+- CSS comments (e.g. `/* anything goes */`)?
+- empty functions (e.g. `var()`)?
+- `url()` functions, including data URIs (e.g. `url(anything/goes.jpg)`)?
+- vendor prefixes (e.g. `@-webkit-keyframes name {}`)?
+- case sensitivity (e.g. `@KEYFRAMES name {}`)?
+- a pseudo-class _combined_ with a pseudo-element (e.g. `a:hover::before`)?
+- nesting (e.g. do you resolve `& a {}`, or check it as is?)?
+- whitespace and punctuation (e.g. comparing `rgb(0,0,0)` with `rgb(0, 0, 0)`)?
+
 ### Write the rule
 
 When writing the rule, you should:
 
 - make the rule strict by default
 - add secondary `ignore` options to make the rule more permissive
-- not include code specific to language extensions, e.g. SCSS
+- not include code specific to language extensions like SCSS
 
 You should make use of the:
 
@@ -171,40 +211,6 @@ if (context.fix) {
 report(/* .. */);
 ```
 
-### Write tests
-
-Each rule must have tests that cover all patterns that:
-
-- are considered problems
-- should _not_ be considered problems
-
-You should test errors in multiple positions, not the same place every time and use:
-
-- realistic CSS, and avoid the use of ellipses
-- the minimum amount of code possible, e.g. if the rule targets selectors then use an empty rule, e.g. `{}`
-- separate `testRule`s when testing non-standard syntax and set the `customSyntax` property
-- `{}` for empty rules, rather than `{ }`
-- the `a` type selector by default
-- the `@media` at-rules by default
-- the `color` property by default
-- the `red` value by default
-- _foo_, _bar_ and _baz_ for names, e.g. `.foo`, `#bar`, `--baz`
-
-#### Commonly overlooked edge-cases
-
-You should ask yourself how does your rule handle:
-
-- variables (e.g. `var(--custom-property)`)?
-- CSS strings (e.g. `content: "anything goes";`)?
-- CSS comments (e.g. `/* anything goes */`)?
-- empty functions (e.g. `var()`)?
-- `url()` functions, including data URIs (e.g. `url(anything/goes.jpg)`)?
-- vendor prefixes (e.g. `@-webkit-keyframes name {}`)?
-- case sensitivity (e.g. `@KEYFRAMES name {}`)?
-- a pseudo-class _combined_ with a pseudo-element (e.g. `a:hover::before`)?
-- nesting (e.g. do you resolve `& a {}`, or check it as is?)?
-- whitespace and punctuation (e.g. comparing `rgb(0,0,0)` with `rgb(0, 0, 0)`)?
-
 ### Write the README
 
 Each rule is accompanied by a README in the following format:
@@ -258,8 +264,8 @@ The final step is to add references to the new rule in the following places:
 You should:
 
 1. Get ready to [contribute code](../../CONTRIBUTING.md#code-contributions).
-2. Change the rule's validation to allow for the new option.
-3. Add new unit tests to test the option.
+2. Add new unit tests to test the option.
+3. Change the rule's validation to allow for the new option.
 4. Add (as little as possible) logic to the rule to make the tests pass.
 5. Add documentation about the new option.
 

docs/developer-guide/syntaxes.md

@@ -1,20 +1,10 @@
 # Writing custom syntaxes
 
-Custom syntaxes are [PostCSS syntaxes](https://github.com/postcss/postcss#syntaxes) written by the community to support other styling languages and CSS-in-JS libraries using the [`customSyntax` option](../user-guide/usage/options.md#customsyntax).
+Custom syntaxes are [PostCSS](https://github.com/postcss/postcss) syntaxes written by the community to support other styling languages, e.g. SCSS, and containers, e.g. HTML, using the [`customSyntax` option](../user-guide/options.md#customsyntax).
 
-To write one, familiarize yourself with PostCSS's [how to write custom syntax](https://github.com/postcss/postcss/blob/main/docs/syntax.md) guide.
+To write one, familiarize yourself with PostCSS's [how to write custom syntax](https://github.com/postcss/postcss/blob/main/docs/syntax.md) guide. You can use one of the existing custom syntaxes from [Awesome Stylelint](https://github.com/stylelint/awesome-stylelint/#readme) for reference.
 
-Existing syntaxes that you can use for reference include:
-
-- [postcss-scss](https://www.npmjs.com/package/postcss-scss)
-- [postcss-less](https://www.npmjs.com/package/postcss-less)
-- [postcss-html](https://www.npmjs.com/package/postcss-html)
-- [postcss-lit](https://www.npmjs.com/package/postcss-lit)
-- [@linaria/postcss-linaria](https://www.npmjs.com/package/@linaria/postcss-linaria)
-
-The latter three use `Document` nodes, [introduced in PostCSS 8.3](https://github.com/postcss/postcss/releases/tag/8.3.0) to support files with multiple roots.
-
-After publishing your custom syntax, we recommend creating a shared-config that:
+After publishing your custom syntax, we recommend creating a shared config that:
 
 - extends the [standard config](https://github.com/stylelint/stylelint-config-standard)
 - bundles your custom syntax