stylelint · jeddy3 · Oct 10, 2021 · Sep 26, 2021 · Sep 26, 2021 · Sep 26, 2021
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,8 @@ All notable changes to this project are documented in this file.
 
 ## Head
 
+[Migrating to `14.0.0` guide](docs/migration-guide/to-14.md).
+
 - Security: addressed ReDoS issue with regex in `indentation` ([#5539](https://github.com/stylelint/stylelint/pull/5539)).
 - Removed: `configOverrides` option ([#5530](https://github.com/stylelint/stylelint/pull/5530)).
 - Removed: `syntax` option ([#5297](https://github.com/stylelint/stylelint/pull/5297)).

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -5,7 +5,7 @@ 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)
-- improve our [support for non-standard syntaxes](docs/about/syntaxes.md)
+- 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_

diff --git a/README.md b/README.md
@@ -8,24 +8,62 @@ A mighty, modern linter that helps you avoid errors and enforce conventions in y
 
 It's mighty as it:
 
-- understands the **latest CSS syntax** including custom properties and level 4 selectors
-- extracts **embedded styles** from HTML, markdown and CSS-in-JS object & template literals
-- parses **CSS-like syntaxes** like SCSS, Sass, Less and SugarSS
-- has over **170 built-in rules** to catch errors, apply limits and enforce stylistic conventions
-- supports **plugins** so you can create your own rules or make use of plugins written by the community
+- understands **modern** CSS syntax and features
+- has over **170 built-in rules** to catch errors and enforce conventions
+- supports **plugins** so you can create your own rules
 - automatically **fixes** the majority of stylistic violations
 - 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
-- has a **growing community** and is used by [Facebook](https://code.facebook.com/posts/879890885467584/improving-css-quality-at-facebook-and-beyond/), [GitHub](https://github.com/primer/stylelint-config-primer) and [WordPress](https://github.com/WordPress-Coding-Standards/stylelint-config-wordpress)
+- has a **growing community** and is used by Google, GitHub and WordPress
+
+And 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
 
 ## Example output
 
 ![Example](https://github.com/stylelint/stylelint/raw/master/example.png?raw=true)
 
-## Getting started
-
-You'll find steps to [get started in our User guide](docs/user-guide/get-started.md).
+## Guides
+
+- User guide
+  - [Getting started](docs/user-guide/get-started.md)
+  - [Configuration](docs/user-guide/configure.md)
+  - Rules
+    - [List of rules](docs/user-guide/rules/list.md)
+    - [About rules](docs/user-guide/rules/about.md)
+    - [Combining rules](docs/user-guide/rules/combine.md)
+    - [Using regex in rules](docs/user-guide/rules/regex.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)
+    - [Shared 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)
+  - [Errors & warnings](docs/user-guide/errors.md)
+- Developer guide
+  - [Working on 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)
+  - [Writing system tests](docs/developer-guide/system-tests.md)
+  - [Writing processors](docs/developer-guide/processors.md)
+- Migration guide
+  - [Migrating to 14.0.0](docs/migration-guide/to-14.md)
+- Maintainer guide
+  - [Managing issues](docs/maintainer-guide/issues.md)
+  - [Managing pull requests](docs/maintainer-guide/pull-requests.md)
+  - [Performing releases](docs/maintainer-guide/releases.md)
+- About
+  - [Vision](docs/about/vision.md)
+  - [Linting](docs/about/linting.md)
+  - [Semantic versioning](docs/about/semantic-versioning.md)
 
 ## Contributors
 

diff --git a/docs/about/linting.md b/docs/about/linting.md
@@ -11,9 +11,9 @@ There are two approaches to enforcing stylistic conventions:
 - a machine algorithmically pretty prints the code (usually based on a maximum line length)
 - a human initially formats the code, and a machine fixes-up/warns-about any mistakes
 
-The former is handled by pretty printers, like [prettier](https://github.com/prettier/prettier), whereas the latter is catered for by the built-in [stylistic rules](../user-guide/rules/list.md#stylistic-issues). If you use a pretty printer, you'll want to use [`stylelint-config-recommended`](https://github.com/stylelint/stylelint-config-recommended), which only turns on [possible error](../user-guide/rules/list.md#possible-errors) rules.
+The former is handled by pretty printers, like [Prettier](https://github.com/prettier/prettier), whereas the latter is catered for by the built-in [stylistic rules](../user-guide/rules/list.md#stylistic-issues). If you use a pretty printer, you'll want to use [`stylelint-config-standard`](https://github.com/stylelint/stylelint-config-standard) and [`stylelint-config-prettier`](https://github.com/prettier/stylelint-config-prettier), which turns off any imcompatible rules.
 
-Additionally, the built-in stylistic rules and plugins are configurable to support a diverse range of stylistic conventions. For example, ordering properties within declaration blocks is a divisive topic, where there isn't a dominant convention. The [`stylelint-order`](https://www.npmjs.com/package/stylelint-order) plugin can be configured to lint and fix a diverse range of ordering conventions.
+The built-in stylistic rules and plugins are configurable to support a diverse range of stylistic conventions. For example, ordering properties within declaration blocks is a divisive topic, where there isn't a dominant convention. The [`stylelint-order`](https://www.npmjs.com/package/stylelint-order) plugin can be configured to lint and fix a diverse range of ordering conventions.
 
 Another example is the use of single-line rules for sets of _related_ rules, e.g.
 
@@ -29,6 +29,6 @@ You can configure the built-in stylistic rules to allow both multi-line and sing
 
 ## Validators
 
-Validators like [csstree](https://github.com/csstree/csstree) identify invalid code such as misformed hex colors and unknown language features.
+Validators like [CSSTree](https://github.com/csstree/csstree) identify invalid code such as misformed hex colors, unknown language features or invalid property and value pairs.
 
-However, as a stop-gap, while these tools mature stylelint provides rules for the simplest of cases.
+However, as a stop-gap, stylelint provides rules for the simplest of cases while these tools mature.
diff --git a/docs/about/syntaxes.md b/docs/about/syntaxes.md
diff --git a/docs/about/vision.md b/docs/about/vision.md
@@ -45,7 +45,7 @@ Provide multiple points of extensions, including:
 - [plugins](../developer-guide/plugins.md) - build community rules to support methodologies, toolsets, non-standard CSS features, or very specific use cases
 - [extendable configs](../user-guide/configure.md#extends) - extend and share configurations
 - [formatters](../developer-guide/formatters.md) - format stylelint result objects
-- [custom syntax](syntaxes.md) - use any PostCSS-compatible syntax module
+- [custom syntax](../user-guide/usage/options.md#customSyntax) - use any PostCSS-compatible syntax module
 
 ## Robust
 

diff --git a/docs/developer-guide/formatters.md b/docs/developer-guide/formatters.md
@@ -1,4 +1,4 @@
-# Writing formatters
+# Writing custom formatters
 
 A formatter is a function with the following signature:
 

diff --git a/docs/developer-guide/plugins.md b/docs/developer-guide/plugins.md
@@ -58,9 +58,9 @@ For your plugin rule to work with the [standard configuration format](../user-gu
 - the primary option
 - optionally, a secondary options object
 
-If your plugin rule supports [autofixing](rules.md#add-autofix), then `ruleFunction` should also accept a third argument: `context`. You should try to support the `disableFix` option in your secondary options object. Within the rule, don't perform autofixing if the user has passed a `disableFix` option for your rule.
+If your plugin rule supports [autofixing](rules.md#add-autofix), then `ruleFunction` should also accept a third argument: `context`.
 
-`ruleFunction` should return a function that is essentially a little [PostCSS plugin](https://github.com/postcss/postcss/blob/master/docs/writing-a-plugin.md). It takes 2 arguments:
+`ruleFunction` should return a function that is essentially a little [PostCSS plugin](https://github.com/postcss/postcss/blob/main/docs/writing-a-plugin.md). It takes 2 arguments:
 
 - the PostCSS Root (the parsed AST)
 - the PostCSS LazyResult

diff --git a/docs/developer-guide/processors.md b/docs/developer-guide/processors.md
@@ -2,7 +2,7 @@
 
 Processors are functions that hook into stylelint's pipeline, modifying code on its way into stylelint and modifying results on their way out.
 
-**Their use is discouraged in favor of [PostCSS syntaxes](../about/syntaxes.md).**
+**Their use is discouraged in favor of [custom syntaxes](syntaxes.md).**
 
 Processor modules are functions that accept an options object and return an object with the following the functions, which hook into the processing of each file:
 

diff --git a/docs/developer-guide/syntaxes.md b/docs/developer-guide/syntaxes.md
@@ -1,35 +1,29 @@
-# Working on syntaxes
+# Writing custom syntaxes
 
-Please help us enhance and debug the [syntaxes](../about/syntaxes.md) we use in stylelint:
+Custom syntaxes are [PostCSS syntaxes](https://github.com/postcss/postcss#syntaxes) written by the community to support other styling languages or CSS-in-JS libraries using the [`customSyntax` option](../user-guide/usage/options.md#customSyntax)
 
-- [postcss-css-in-js](https://github.com/stylelint/postcss-css-in-js)
-- [postcss-html](https://github.com/gucong3000/postcss-html)
-- [postcss-less](https://github.com/webschik/postcss-less)
-- [postcss-markdown](https://github.com/stylelint/postcss-markdown)
-- [postcss-sass](https://github.com/AleshaOleg/postcss-sass)
-- [postcss-scss](https://github.com/postcss/postcss-scss)
-
-To contribute to a syntax, you should:
-
-1. Familiarize yourself with PostCSS's [how to write custom syntax](https://github.com/postcss/postcss/blob/master/docs/syntax.md) guide.
-2. Use the [`syntax: *` labels](https://github.com/stylelint/stylelint/labels?utf8=%E2%9C%93&q=syntax%3A) to identify which syntax is behind an issue.
-3. Go to the repository for that syntax.
-4. Read their contributing guidelines.
-
-## Workarounds
-
-Fixing bugs in syntaxes can take time. stylelint can work around these bug by turning off autofix for incompatible sources. Autofix can then remain safe to use while contributors try to fix the underlying issue.
+To write one, familiarize yourself with PostCSS's [how to write custom syntax](https://github.com/postcss/postcss/blob/main/docs/syntax.md) guide.
 
-### Current workarounds
+Existing syntaxes that you can use for reference include:
 
-stylelint currently turns off autofix for sources that contain:
-
-- ~~nested tagged template literals ([issue #4119](https://github.com/stylelint/stylelint/issues/4119))~~
-
-### Add a workaround
-
-To add a new workaround, you should:
-
-1. Add code to [`lib/lintSource.js`](https://github.com/stylelint/stylelint/blob/master/lib/lintSource.js) to detect the incompatible pattern.
-2. Add a corresponding test to [`lib/__tests__/standalone-fix.test.js`](https://github.com/stylelint/stylelint/blob/master/lib/__tests__/standalone-fix.test.js).
-3. Document the workaround in [`docs/developer-guides/syntaxes.md`](https://github.com/stylelint/stylelint/blob/master/docs/developer-guide/syntaxes.md).
+- [postcss-scss](https://github.com/postcss/postcss-scss)
+- [postcss-less](https://github.com/shellscape/postcss-less)
+
+We recommend creating a shared-config that:
+
+- extends the [standard config](https://github.com/stylelint/stylelint-config-standard)
+- bundles your custom syntax
+- turns off any incompatible built-in rules
+
+For example, if you're creating a syntax for a CSS-in-JS library called "foo" then we recommend creating a shared-config called "stylelint-config-standard-foo" with the following content:
+
+```json
+{
+  "extends": ["stylelint-config-standard"],
+  "customSyntax": "postcss-foo",
+  "rules": {
+    "at-rule-no-unknown": null,
+    ..
+  }
+}
+```
diff --git a/docs/migration-guide/to-14.md b/docs/migration-guide/to-14.md
@@ -0,0 +1,132 @@
+# Migrating to 14.0.0
+
+This release contains breaking changes. We know these can be disruptive, but they were needed to keep our dependencies up to date and stylelint free of security issues.
+
+## Users
+
+There are five changes that may affect you:
+
+- the `syntax` option and automatic inferral of syntax was removed
+- Node.js 10 support was dropped
+- the rules deprecated in 13.7.0 were removed
+- the `configOverrides` option was removed
+- the `function-calc-no-invalid` rule was removed
+
+### `syntax` option and automatic inferral of syntax
+
+stylelint no longer includes syntaxes that:
+
+- parse CSS-like syntaxes like SCSS, Sass, Less and SugarSS
+- extract embedded styles from HTML, Markdown and CSS-in-JS object & template literals
+
+If you use stylelint to lint anything other than CSS files, you will need to install and configure these syntaxes yourself. You can use the [`customSyntax` option](../user-guide/usage/options.md#customSyntax) to do this, which is now available in the configuration object.
+
+For example, to lint SCSS.
+
+First, install the [postcss-scss](https://www.npmjs.com/package/postcss-scss) syntax as a dependency:
+
+```shell
+npm install --save-dev postcss-scss
+```
+
+Then, update your configuration object to use it:
+
+```json
+{
+  "customSyntax": "postcss-scss",
+  "rules": {
+    ..
+  }
+}
+```
+
+For other languages and embedded styles, we suggest the following [PostCSS syntaxes](https://github.com/postcss/postcss#syntaxes):
+
+- Less language (`.less`) use [postcss-less](https://www.npmjs.com/package/postcss-less)
+- Sass language (`.sass`) use [postcss-sass](https://www.npmjs.com/package/postcss-sass)
+- SugarSS language (`.sss`) use [sugarss](https://www.npmjs.com/package/sugarss)
+- CSS-in-JS embeds (`.js`, `.jsx`, `.ts` etc.) use [@stylelint/postcss-css-in-js](https://www.npmjs.com/package/@stylelint/postcss-css-in-js)
+- HTML, XML and HTML-like embeds (`.html`, `.xml`, `.svelte`, `.vue` etc.) use [postcss-html](https://www.npmjs.com/package/postcss-html)
+- Markdown embeds (`.md`, `.markdown` etc.) use [postcss-markdown](https://www.npmjs.com/package/postcss-markdown)
+
+(The [postcss-html](https://www.npmjs.com/package/postcss-html) and [postcss-markdown](https://www.npmjs.com/package/postcss-markdown) packages need a maintainer. The [@stylelint/postcss-css-in-js](https://www.npmjs.com/package/@stylelint/postcss-css-in-js) package [has issues](https://github.com/stylelint/stylelint/issues/4574). It will likely to be deprecated in the future in favour of smaller syntaxes that focus on only one library).
+
+If you lint more than one styling language, then you can use the new [`overrides` property](../user-guide/configure.md#overrides). For example, to lint both CSS and [SugarSS](https://github.com/postcss/sugarss) you can update your configuration object to include:
+
+```json
+{
+  "extends": ["stylelint-config-standard"],
+  "overrides": [
+    {
+      "files": ["**/*.sss"],
+      "customSyntax": "sugarss",
+      "rules": {
+        "block-closing-brace-empty-line-before": null,
+        "block-closing-brace-newline-after": null,
+        "block-closing-brace-newline-before": null,
+        "block-closing-brace-space-before": null,
+        "block-opening-brace-newline-after": null,
+        "block-opening-brace-space-after": null,
+        "block-opening-brace-space-before": null,
+        "declaration-block-semicolon-newline-after": null,
+        "declaration-block-semicolon-space-after": null,
+        "declaration-block-semicolon-space-before": null,
+        "declaration-block-trailing-semicolon": null
+      }
+    }
+  ]
+}
+```
+
+Which will extend the [offical standard config](https://github.com/stylelint/stylelint-config-standard), then use the `overrides` property to set the `customSyntax` property and turn off the rules that check braces and semicolons for SugarSS files.
+
+You can then use stylelint to lint both CSS and SugarSS files:
+
+```shell
+npx stylelint "**/*.{css,sss}"
+```
+
+### Node.js 10
+
+Support for Node.js 10 was dropped. You should use the following or higher versions of Node.js:
+
+- 12.20.0
+- 14.13.1
+- 16.0.0
+
+### Rules deprecated in 13.7.0
+
+The rules deprecated in 13.7.0 were removed. You should refer to the [list of alternatives in the 13.7.0 CHANGELOG entry](../../CHANGELOG.md#1370) and use them instead.
+
+### `configOverrides` option
+
+The `configOverrides` option has been removed. Use the [`overrides` property](../user-guide/configure.md#overrides) in the configuration object instead.
+
+### `function-calc-no-invalid` rule
+
+The `function-calc-no-invalid` has be removed. You should remove it from your configuration object.
+
+## Plugin authors
+
+There are two changes that may affect you:
+
+- version 8 of PostCSS is now used in stylelint
+- a [`disableFix` secondary option](../user-guide/configure.md#disableFix) was added
+
+### PostCSS 8
+
+The behaviour of the parser has changed in PostCSS version 8. The following is now parsed as a `Declaration` when it was previously parsed as a `Rule`:
+
+```css
+foo: {
+  bar: baz;
+}
+```
+
+If your plugin targets this construct, you'll need to update your logic.
+
+Even though version 8 of PostCSS is used in stylelint, you can't use the [new Visitor API](https://github.com/postcss/postcss/releases/tag/8.0.0) as stylelint plugins are converted to use `Once` by stylelint itself. You should continue to use the `walk*` API.
+
+### `disableFix` secondary option
+
+We previously suggested plugin authors provide this option. It is now available in stylelint itself, and you should remove the option from your plugin.