docs: Configuring Plugins page intro, page tweaks, and rename (#16534)

* docs: plugins config intro + tweaks * refactor intro/page name * refactor page to reflect parsers separate from plugins * copy edits * Apply suggestions from code review Co-authored-by: Nitin Kumar <snitin315@gmail.com> * Apply suggestions from code review Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com> * Update docs/src/user-guide/configuring/plugins.md * change titles to non gerund + inline links * add custom environments bullet point * Apply suggestions from code review Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com> * update anchor links Co-authored-by: Nitin Kumar <snitin315@gmail.com> Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com>
eslint · Dec 2, 2022 · 0311d81 · 0311d81
1 parent 57089b1
commit 0311d81
Show file tree

Hide file tree

Showing 4 changed files with 99 additions and 88 deletions.
diff --git a/docs/src/developer-guide/working-with-plugins.md b/docs/src/developer-guide/working-with-plugins.md
@@ -144,7 +144,7 @@ overrides:
     processor: a-plugin/markdown
 ```
 
-See [Specifying Processor](../user-guide/configuring/plugins#specifying-processor) for details.
+See [Specifying Processor](../user-guide/configuring/plugins#specify-a-processor) for details.
 
 #### File Extension-named Processor
 
@@ -205,7 +205,7 @@ If the example plugin above were called `eslint-plugin-myPlugin`, the `myConfig`
 
 ```
 
-**Note:** Please note that configuration will not enable any of the plugin's rules by default, and instead should be treated as a standalone config. This means that you must specify your plugin name in the `plugins` array as well as any rules you want to enable that are part of the plugin. Any plugin rules must be prefixed with the short or long plugin name. See [Configuring Plugins](../user-guide/configuring/plugins#configuring-plugins) for more information.
+**Note:** Please note that configuration will not enable any of the plugin's rules by default, and instead should be treated as a standalone config. This means that you must specify your plugin name in the `plugins` array as well as any rules you want to enable that are part of the plugin. Any plugin rules must be prefixed with the short or long plugin name. See [Configuring Plugins](../user-guide/configuring/plugins#configure-plugins) for more information.
 
 ### Peer Dependency
 

diff --git a/docs/src/user-guide/configuring/configuration-files.md b/docs/src/user-guide/configuring/configuration-files.md
@@ -281,7 +281,7 @@ module.exports = {
 
 A [plugin](https://eslint.org/docs/developer-guide/working-with-plugins) is an npm package that can add various extensions to ESLint. A plugin can perform numerous functions, including but not limited to adding new rules and exporting [shareable configurations](https://eslint.org/docs/developer-guide/working-with-plugins#configs-in-plugins). Make sure the package has been installed in a directory where ESLint can require it.
 
-The `plugins` [property value](./plugins#configuring-plugins) can omit the `eslint-plugin-` prefix of the package name.
+The `plugins` [property value](./plugins#configure-plugins) can omit the `eslint-plugin-` prefix of the package name.
 
 The `extends` property value can consist of:
 

diff --git a/docs/src/user-guide/configuring/index.md b/docs/src/user-guide/configuring/index.md
@@ -47,9 +47,9 @@ All of these options give you fine-grained control over how ESLint treats your c
 
 [**Plugins**](plugins)
 
-* [Specifying Parser](./plugins#specifying-parser)
-* [Specifying Processor](./plugins#specifying-processor)
-* [Configuring Plugins](./plugins#configuring-plugins)
+* [Configuring Plugins](./plugins#configure-plugins)
+* [Specifying Processors](./plugins#specify-a-processor)
+* [Configuring Parsers](./plugins#configure-a-parser)
 
 [**Ignoring Code**](ignoring-code)
 

diff --git a/docs/src/user-guide/configuring/plugins.md b/docs/src/user-guide/configuring/plugins.md
@@ -1,93 +1,25 @@
 ---
-title: Plugins
+title: Plugins & Parsers
 eleventyNavigation:
     key: configuring plugins
     parent: configuring
-    title: Configuring Plugins
+    title: Configuring Plugins & Parsers
     order: 4
 
 ---
 
-## Specifying Parser
+You can extend ESLint with plugins in a variety of different ways. Plugins can include:
 
-By default, ESLint uses [Espree](https://github.com/eslint/espree) as its parser. You can optionally specify that a different parser should be used in your configuration file so long as the parser meets the following requirements:
+* Custom rules to validate if your code meets a certain expectation, and what to do if it does not meet that expectation.
+* Custom configurations.
+* Custom environments.
+* Custom processors to extract JavaScript code from other kinds of files or preprocess code before linting.
 
-1. It must be a Node module loadable from the config file where the parser is used. Usually, this means you should install the parser package separately using npm.
-1. It must conform to the [parser interface](../../developer-guide/working-with-custom-parsers).
-
-Note that even with these compatibilities, there are no guarantees that an external parser will work correctly with ESLint and ESLint will not fix bugs related to incompatibilities with other parsers.
-
-To indicate the npm module to use as your parser, specify it using the `parser` option in your `.eslintrc` file. For example, the following specifies to use Esprima instead of Espree:
-
-```json
-{
-    "parser": "esprima",
-    "rules": {
-        "semi": "error"
-    }
-}
-```
-
-The following parsers are compatible with ESLint:
-
-* [Esprima](https://www.npmjs.com/package/esprima)
-* [@babel/eslint-parser](https://www.npmjs.com/package/@babel/eslint-parser) - A wrapper around the [Babel](https://babeljs.io) parser that makes it compatible with ESLint.
-* [@typescript-eslint/parser](https://www.npmjs.com/package/@typescript-eslint/parser) - A parser that converts TypeScript into an ESTree-compatible form so it can be used in ESLint.
-
-Note when using a custom parser, the `parserOptions` configuration property is still required for ESLint to work properly with features not in ECMAScript 5 by default. Parsers are all passed `parserOptions` and may or may not use them to determine which features to enable.
-
-## Specifying Processor
-
-Plugins may provide processors. Processors can extract JavaScript code from other kinds of files, then let ESLint lint the JavaScript code or processors can convert JavaScript code in preprocessing for some purpose.
-
-To specify processors in a configuration file, use the `processor` key with the concatenated string of a plugin name and a processor name by a slash. For example, the following enables the processor `a-processor` that the plugin `a-plugin` provided:
-
-```json
-{
-    "plugins": ["a-plugin"],
-    "processor": "a-plugin/a-processor"
-}
-```
-
-To specify processors for specific kinds of files, use the combination of the `overrides` key and the `processor` key. For example, the following uses the processor `a-plugin/markdown` for `*.md` files.
-
-```json
-{
-    "plugins": ["a-plugin"],
-    "overrides": [
-        {
-            "files": ["*.md"],
-            "processor": "a-plugin/markdown"
-        }
-    ]
-}
-```
+You can also use custom parsers to convert JavaScript code into an abstract syntax tree for ESLint to evaluate. You might want to add a custom parser if your code isn't compatible with ESLint's default parser, Espree.
 
-Processors may make named code blocks such as `0.js` and `1.js`. ESLint handles such a named code block as a child file of the original file. You can specify additional configurations for named code blocks in the `overrides` section of the config. For example, the following disables the `strict` rule for the named code blocks which end with `.js` in markdown files.
+## Configure Plugins
 
-```json
-{
-    "plugins": ["a-plugin"],
-    "overrides": [
-        {
-            "files": ["*.md"],
-            "processor": "a-plugin/markdown"
-        },
-        {
-            "files": ["**/*.md/*.js"],
-            "rules": {
-                "strict": "off"
-            }
-        }
-    ]
-}
-```
-
-ESLint checks the file path of named code blocks then ignores those if any `overrides` entry didn't match the file path. Be sure to add an `overrides` entry if you want to lint named code blocks other than `*.js`.
-
-## Configuring Plugins
-
-ESLint supports the use of third-party plugins. Before using the plugin, you have to install it using npm.
+ESLint supports the use of third-party plugins. Before using a plugin, you have to install it using npm.
 
 To configure plugins inside of a configuration file, use the `plugins` key, which contains a list of plugin names. The `eslint-plugin-` prefix can be omitted from the plugin name.
 
@@ -111,14 +43,16 @@ And in YAML:
 
 **Notes:**
 
-1. Plugins are resolved relative to the config file. In other words, ESLint will load the plugin as a user would obtain by running `require('eslint-plugin-pluginname')` in the config file.
+1. Plugins are resolved relative to the config file. In other words, ESLint loads the plugin as a user would obtain by running `require('eslint-plugin-pluginname')` in the config file.
 2. Plugins in the base configuration (loaded by `extends` setting) are relative to the derived config file. For example, if `./.eslintrc` has `extends: ["foo"]` and the `eslint-config-foo` has `plugins: ["bar"]`, ESLint finds the `eslint-plugin-bar` from `./node_modules/` (rather than `./node_modules/eslint-config-foo/node_modules/`) or ancestor directories. Thus every plugin in the config file and base configurations is resolved uniquely.
 
 ### Naming convention
 
 #### Include a plugin
 
-The `eslint-plugin-` prefix can be omitted for non-scoped packages
+The `eslint-plugin-` prefix can be omitted for both non-scoped and scoped packages.
+
+A non-scoped package:
 
 ```js
 {
@@ -130,7 +64,7 @@ The `eslint-plugin-` prefix can be omitted for non-scoped packages
 }
 ```
 
-The same rule does apply to scoped packages:
+A scoped package:
 
 ```js
 {
@@ -145,7 +79,7 @@ The same rule does apply to scoped packages:
 
 #### Use a plugin
 
-When using rules, environments or configs defined by plugins, they must be referenced following the convention:
+Rules, environments, and configurations defined in plugins must be referenced with the following convention:
 
 * `eslint-plugin-foo` → `foo/a-rule`
 * `@foo/eslint-plugin` → `@foo/a-config`
@@ -178,3 +112,80 @@ For example:
     // ...
 }
 ```
+
+### Specify a Processor
+
+Plugins may provide processors. Processors can extract JavaScript code from other kinds of files, then let ESLint lint the JavaScript code. Alternatively, processors can convert JavaScript code during preprocessing.
+
+To specify processors in a configuration file, use the `processor` key with the concatenated string of a plugin name and a processor name by a slash. For example, the following enables the processor `a-processor` that the plugin `a-plugin` provided:
+
+```json
+{
+    "plugins": ["a-plugin"],
+    "processor": "a-plugin/a-processor"
+}
+```
+
+To specify processors for specific kinds of files, use the combination of the `overrides` key and the `processor` key. For example, the following uses the processor `a-plugin/markdown` for `*.md` files.
+
+```json
+{
+    "plugins": ["a-plugin"],
+    "overrides": [
+        {
+            "files": ["*.md"],
+            "processor": "a-plugin/markdown"
+        }
+    ]
+}
+```
+
+Processors may make named code blocks such as `0.js` and `1.js`. ESLint handles such a named code block as a child file of the original file. You can specify additional configurations for named code blocks in the `overrides` section of the config. For example, the following disables the `strict` rule for the named code blocks which end with `.js` in markdown files.
+
+```json
+{
+    "plugins": ["a-plugin"],
+    "overrides": [
+        {
+            "files": ["*.md"],
+            "processor": "a-plugin/markdown"
+        },
+        {
+            "files": ["**/*.md/*.js"],
+            "rules": {
+                "strict": "off"
+            }
+        }
+    ]
+}
+```
+
+ESLint checks the file path of named code blocks then ignores those if any `overrides` entry didn't match the file path. Be sure to add an `overrides` entry if you want to lint named code blocks other than `*.js`.
+
+## Configure a Parser
+
+By default, ESLint uses [Espree](https://github.com/eslint/espree) as its parser. You can optionally specify that a different parser should be used in your configuration file if the parser meets the following requirements:
+
+1. It must be a Node module loadable from the config file where the parser is used. Usually, this means you should install the parser package separately using npm.
+1. It must conform to the [parser interface](../../developer-guide/working-with-custom-parsers).
+
+Note that even with these compatibilities, there are no guarantees that an external parser works correctly with ESLint. ESLint does not fix bugs related to incompatibilities with other parsers.
+
+To indicate the npm module to use as your parser, specify it using the `parser` option in your `.eslintrc` file. For example, the following specifies to use Esprima instead of Espree:
+
+```json
+{
+    "parser": "esprima",
+    "rules": {
+        "semi": "error"
+    }
+}
+```
+
+The following parsers are compatible with ESLint:
+
+* [Esprima](https://www.npmjs.com/package/esprima)
+* [@babel/eslint-parser](https://www.npmjs.com/package/@babel/eslint-parser) - A wrapper around the [Babel](https://babeljs.io) parser that makes it compatible with ESLint.
+* [@typescript-eslint/parser](https://www.npmjs.com/package/@typescript-eslint/parser) - A parser that converts TypeScript into an ESTree-compatible form so it can be used in ESLint.
+
+Note that when using a custom parser, the `parserOptions` configuration property is still required for ESLint to work properly with features not in ECMAScript 5 by default. Parsers are all passed `parserOptions` and may or may not use them to determine which features to enable.