From 81dfe56e1d7ab58561ba1949f5937a2736f67485 Mon Sep 17 00:00:00 2001 From: jeddy3 Date: Sun, 26 Sep 2021 09:25:17 +0100 Subject: [PATCH 01/28] Prepare docs for 14 --- CHANGELOG.md | 93 ++++++ CONTRIBUTING.md | 2 +- README.md | 15 +- docs/about/linting.md | 8 +- docs/about/syntaxes.md | 18 - docs/about/vision.md | 2 +- docs/developer-guide/processors.md | 2 +- docs/developer-guide/syntaxes.md | 57 ++-- docs/toc.md | 1 - docs/user-guide/configure.md | 348 ++++++++++---------- docs/user-guide/errors.md | 4 +- docs/user-guide/get-started.md | 123 ++++++- docs/user-guide/ignore-code.md | 1 - docs/user-guide/integrations/editor.md | 5 +- docs/user-guide/integrations/task-runner.md | 2 +- docs/user-guide/usage/cli.md | 34 +- docs/user-guide/usage/node-api.md | 2 +- docs/user-guide/usage/options.md | 76 +++-- lib/__tests__/standalone-syntax.test.js | 8 +- lib/getPostcssResult.js | 81 ++++- 20 files changed, 546 insertions(+), 336 deletions(-) delete mode 100644 docs/about/syntaxes.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 925d5bad6f..7074269cdd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,99 @@ All notable changes to this project are documented in this file. ## Head +This release contains breaking changes. We know these can be disruptive, but they were necessary to keep our dependencies up to date and stylelint free of security issues. + +The most significant change is that we no longer include PostCSS syntaxes (for languages like SCSS or CSS-in-JS libraries like styled-components) in stylelint. You will need to install these custom syntaxes yourself. **If you use stylelint to lint anything other than CSS, you will likely need to change your [configuration object](https://stylelint.io/user-guide/configure/).** + +### Migrating from version 13 of stylelint + +If you use stylelint to lint CSS, it's unlikely you'll need to make any changes. If you lint a language like SCSS, we recommend installing and [extending](https://stylelint.io/user-guide/configure#extends) a shared-config that includes the appropriate [PostCSS syntax](https://github.com/postcss/postcss#syntaxes) for you. For example, you can use the [stylelint-config-standard-scss]() shared-config for SCSS. + +First, install the shared-config as a dependency: + +```console +npm install --save-dev stylelint-config-standard-scss +``` + +Then, update your [configuration object](https://stylelint.io/user-guide/configure/) to use it: + +```json +{ + "extends": ["stylelint-config-standard-scss"], + "rules": { + .. + } +} +``` + +This shared-config extends stylelint to be compatible with SCSS. It configures the built-in rules for SCSS, and includes the [postcss-scss syntax](https://github.com/postcss/postcss-scss) and [stylelint-scss plugin](https://github.com/kristerkari/stylelint-scss) (a collection of rules specific to SCSS). + +Other shared-configs that include an appropriate PostCSS syntax are: + +- [stylelint-config-standard-styled-components] ??? + +If a shared-config isn't available for your choice of language or CSS-in-JS library, then you can install the appropriate [PostCSS syntax](https://github.com/postcss/postcss#syntaxes) yourself. For example, to lint [SugarSS](https://github.com/postcss/sugarss) install the syntax as a dependency: + +```console +npm install --save-dev sugarss +``` + +Then, update your configuration object to use it: + +```json +{ + "customSyntax": "sugarss", + "rules": { + .. + } +} +``` + +Other [PostCSS syntaxes](https://github.com/postcss/postcss#syntaxes) known to be compatible with stylelint include: + +- [postcss-scss](https://github.com/postcss/postcss-scss) +- [postcss-less](https://github.com/webschik/postcss-less) +- [postcss-sass](https://github.com/AleshaOleg/postcss-sass) + +If a PostCSS syntax doesn't exist for your choice of language or CSS-in-JS lribary, please consider creating it and sharing it with the community. It'll need to be compatible with version 8 of PostCSS. + +If you lint more than one styling language, then you can use the new [`overrides` property](docs/user-guides/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 custom-syntax 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: + +```console +npx stylelint "**/*.{css,sss}" +``` + +### Changes + - 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 index a88f59563d..9a5cdc0e89 100644 --- 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 index 521180338d..070fc02a7b 100644 --- a/README.md +++ b/README.md @@ -8,16 +8,19 @@ 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 - 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 + +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 +- lint your own custom rules as **plugins** ## Example output diff --git a/docs/about/linting.md b/docs/about/linting.md index 271989fe06..02236e102e 100644 --- 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 deleted file mode 100644 index 62d1265942..0000000000 --- a/docs/about/syntaxes.md +++ /dev/null @@ -1,18 +0,0 @@ -# Syntaxes - -There are many styling languages, ranging from CSS language extensions like SCSS to entirely different notations, e.g. CSS-in-JS objects. - -These styling languages can be embedded within other languages too. For example: - -- HTML `