docs: Plugin docs cleanup & expansion (#16862)

* docs: Plugin docs cleanup & expansion

* more edits

* Add intro paragraph

* copy edits

* Update docs/src/extend/plugins.md

Co-authored-by: Amaresh  S M  <amareshsm13@gmail.com>

* Apply suggestions from code review

Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com>

* MD feedback

* implement MD feedback

* Apply suggestions from code review

Co-authored-by: Nitin Kumar <snitin315@gmail.com>
Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com>

---------

Co-authored-by: Amaresh  S M  <amareshsm13@gmail.com>
Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com>
Co-authored-by: Nitin Kumar <snitin315@gmail.com>
Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com>

docs/src/extend/custom-processors.md

@@ -2,9 +2,9 @@
 title: Custom Processors
 eleventyNavigation:
     key: custom processors
-    parent: extend eslint
+    parent: create plugins
     title: Custom Processors
-    order: 5
+    order: 2
 
 ---
 You can also create custom processors that tell ESLint how to process files other than JavaScript.

docs/src/extend/custom-rules.md

@@ -2,9 +2,9 @@
 title: Custom Rules
 eleventyNavigation:
     key: custom rules
-    parent: extend eslint
+    parent: create plugins
     title: Custom Rules
-    order: 3
+    order: 1
 
 ---
 

docs/src/extend/plugins.md

@@ -8,6 +8,10 @@ eleventyNavigation:
 
 ---
 
+An ESLint plugin is an extension for ESLint that adds additional rules and configuration options. Plugins let you customize your ESLint configuration to enforce rules that are not included in the core ESLint package. Plugins can also provide additional environments, custom processors, and configurations.
+
+## Name a Plugin
+
 Each plugin is an npm module with a name in the format of `eslint-plugin-<plugin-name>`, such as `eslint-plugin-jquery`. You can also use scoped packages in the format of `@<scope>/eslint-plugin-<plugin-name>` such as `@jquery/eslint-plugin-jquery` or even `@<scope>/eslint-plugin` such as `@jquery/eslint-plugin`.
 
 ## Create a Plugin
@@ -16,7 +20,7 @@ The easiest way to start creating a plugin is to use the [Yeoman generator](http
 
 ### Rules in Plugins
 
-Plugins can expose additional rules for use in ESLint. To do so, the plugin must export a `rules` object containing a key-value mapping of rule ID to rule. The rule ID does not have to follow any naming convention (so it can just be `dollar-sign`, for instance).
+Plugins can expose custom rules for use in ESLint. To do so, the plugin must export a `rules` object containing a key-value mapping of rule ID to rule. The rule ID does not have to follow any naming convention (so it can just be `dollar-sign`, for instance). To learn more about creating custom rules in plugins, refer to [Custom Rules](custom-rules).
 
 ```js
 module.exports = {
@@ -78,7 +82,9 @@ module.exports = {
 
 ### Configs in Plugins
 
-You can bundle configurations inside a plugin by specifying them under the `configs` key. This can be useful when you want to provide not just code style, but also some custom rules to support it. Multiple configurations are supported per plugin. Note that it is not possible to specify a default configuration for a given plugin and that users must specify in their configuration file when they want to use one.
+You can bundle configurations inside a plugin by specifying them under the `configs` key. This can be useful when you want to bundle a set of custom rules with additional configuration. Multiple configurations are supported per plugin.
+
+You can include individual rules from a plugin in a config that's also included in the plugin. In the config, 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.
 
 ```js
 // eslint-plugin-myPlugin
@@ -103,25 +109,33 @@ module.exports = {
                 "eslint-plugin-myPlugin/yet-another-rule": "error"
             }
         }
+    },
+    rules: {
+        "my-rule": {/* rule definition */},
+        "another-rule": {/* rule definition */},
+        "yet-another-rule": {/* rule definition */}
     }
 };
 ```
 
-If the example plugin above were called `eslint-plugin-myPlugin`, the `myConfig` and `myOtherConfig` configurations would then be usable by extending off of `"plugin:myPlugin/myConfig"` and `"plugin:myPlugin/myOtherConfig"`, respectively.
+Plugins cannot force a specific configuration to be used. Users must manually include a plugin's configurations in their configuration file.
+
+If the example plugin above were called `eslint-plugin-myPlugin`, the `myConfig` and `myOtherConfig` configurations would then be usable in a configuration file by extending `"plugin:myPlugin/myConfig"` and `"plugin:myPlugin/myOtherConfig"`, respectively.
 
 ```json
+// .eslintrc.json
+
 {
     "extends": ["plugin:myPlugin/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 [Configure Plugins](../use/configure/plugins#configure-plugins) for more information.
-
 ### Peer Dependency
 
-To make clear that the plugin requires ESLint to work correctly you have to declare ESLint as a `peerDependency` in your `package.json`.
-The plugin support was introduced in ESLint version `0.8.0`. Ensure the `peerDependency` points to ESLint `0.8.0` or later.
+To make clear that the plugin requires ESLint to work correctly, you must declare ESLint as a peer dependency by mentioning it in the `peerDependencies` field of your plugin's `package.json`.
+
+Plugin support was introduced in ESLint version `0.8.0`. Ensure the `peerDependencies` points to ESLint `0.8.0` or later.
 
 ```json
 {
@@ -131,11 +145,11 @@ The plugin support was introduced in ESLint version `0.8.0`. Ensure the `peerDep
 }
 ```
 
-### Testing
+## Testing
 
 ESLint provides the [`RuleTester`](../integrate/nodejs-api#ruletester) utility to make it easy to test the rules of your plugin.
 
-### Linting
+## Linting
 
 ESLint plugins should be linted too! It's suggested to lint your plugin with the `recommended` configurations of:
 
@@ -147,13 +161,7 @@ ESLint plugins should be linted too! It's suggested to lint your plugin with the
 
 In order to make your plugin available to the community you have to publish it on npm.
 
-Recommended keywords:
+To make it easy for others to find your plugin, add these [keywords](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#keywords) to your `package.json` file:
 
 * `eslint`
 * `eslintplugin`
-
-Add these keywords into your `package.json` file to make it easy for others to find.
-
-## Further Reading
-
-* [npm Developer Guide](https://docs.npmjs.com/misc/developers)

docs/src/extend/shareable-configs.md

@@ -4,7 +4,7 @@ eleventyNavigation:
     key: share configs
     parent: extend eslint
     title: Share Configurations
-    order: 6
+    order: 3
 
 ---
 

docs/src/integrate/nodejs-api.md

@@ -4,7 +4,7 @@ eleventyNavigation:
     key: node.js api
     parent: extend eslint
     title: Node.js API Reference
-    order: 7
+    order: 6
 ---
 
 While ESLint is designed to be run on the command line, it's possible to use ESLint programmatically through the Node.js API. The purpose of the Node.js API is to allow plugin and tool authors to use the ESLint functionality directly, without going through the command line interface.