docs: add Troubleshooting page (#18181)

* docs: add Troubleshooting page

* Add a mention of updating to the latest

* Separated into sections

* Tweaked plugin uniquely

* Tweaked plugin uniquely (2)

* Apply suggestions from code review

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

* no quotes

* Fixed up docs links post-merge

* One last link fix: configuration-file(-new)

* Update docs/src/use/troubleshooting/index.md

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

---------

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

docs/src/use/troubleshooting/couldnt-determine-the-plugin-uniquely.md

@@ -0,0 +1,54 @@
+---
+title: ESLint couldn't determine the plugin … uniquely
+eleventyNavigation:
+    key: couldn't determine plugin uniquely
+    parent: troubleshooting
+    title: ESLint couldn't determine the plugin … uniquely
+---
+
+## Symptoms
+
+When using the [legacy ESLint config system](../configure/configuration-files-deprecated), you may see this error running ESLint after installing dependencies:
+
+```plaintext
+ESLint couldn't determine the plugin "${pluginId}" uniquely.
+
+- ${filePath} (loaded in "${importerName}")
+- ${filePath} (loaded in "${importerName}")
+...
+
+Please remove the "plugins" setting from either config or remove either plugin installation.
+```
+
+## Cause
+
+ESLint configuration files allow loading in plugins that may include other plugins.
+A plugin package might be specified as a dependency of both your package and one or more ESLint plugins.
+Legacy ESLint configuration files may use `extends` to include other configurations.
+Those configurations may depend on plugins to provide certain functionality in the configuration.
+
+For example, if your config depends on `eslint-plugin-a@2` and `eslint-plugin-b@3`, and you extend `eslint-config-b` that depends on `eslint-plugin-a@1`, then the `eslint-plugin-a` package might have two different versions on disk:
+
+* `node_modules/eslint-plugin-a`
+* `node_modules/eslint-plugin-b/node_modules/eslint-plugin-a`
+
+If the legacy ESLint configuration system sees that both plugins exists in multiple places with different versions, it won't know which one to use.
+
+Note that this issue is only present in the legacy eslintrc configurations.
+The new ["flat" config system](../configure/configuration-files) has you `import` the dependencies yourself, removing the need for ESLint to attempt to determine their version uniquely.
+
+## Resolution
+
+Common resolutions for this issue include:
+
+* Upgrading all versions of all packages to their latest version
+* Running `npm dedupe` or the equivalent package manager command to deduplicate packages, if their version ranges are compatible
+* Using `overrides` or the equivalent package manager `package.json` field, to force a specific version of a plugin package
+    * Note that this may cause bugs in linting if the plugin package had breaking changes between versions
+
+## Resources
+
+For more information, see:
+
+* [Configure Plugins](../configure/plugins) for documentation on how to extend from plugins
+* [Create Plugins](../../extend/plugins#configs-in-plugins) for documentation on how to define plugins

docs/src/use/troubleshooting/couldnt-find-the-config.md

@@ -0,0 +1,62 @@
+---
+title: ESLint couldn't find the config … to extend from
+eleventyNavigation:
+    key: couldn't find the config to extend from
+    parent: troubleshooting
+    title: ESLint couldn't find the config … to extend from
+---
+
+## Symptoms
+
+When using the [legacy ESLint config system](../configure/configuration-files-deprecated), you may see this error running ESLint after installing dependencies:
+
+```plaintext
+ESLint couldn't find the config "${configName}" to extend from. Please check that the name of the config is correct.
+
+The config "${configName}" was referenced from the config file in "${importerName}".
+```
+
+## Cause
+
+ESLint configuration files specify shareable configs by their package name in the `extends` array.
+That package name is passed to the Node.js `require()`, which looks up the package under local `node_modules/` directories.
+For example, the following ESLint config will first try to load a module located at `node_modules/eslint-config-yours`:
+
+```js
+module.exports = {
+    extends: ["eslint-config-yours"],
+};
+```
+
+The error is output when you attempt to extend from a configuration and the package for that configuration is not found in any searched `node_modules/`.
+
+Common reasons for this occurring include:
+
+*   Not running `npm install` or the equivalent package manager command
+*   Mistyping the case-sensitive name of the package and/or configuration
+
+### Config Name Variations
+
+Note that ESLint supports several config name formats:
+
+* The `eslint-config-` config name prefix may be omitted for brevity, e.g. `extends: ["yours"]`
+    * [`@` npm scoped packages](https://docs.npmjs.com/cli/v10/using-npm/scope) put the `eslint-config-` prefix after the org scope, e.g. `extends: ["@org/yours"]` to load from `@org/eslint-config-yours`
+* A `plugin:` prefix indicates a config is loaded from a shared plugin, e.g. `extends: [plugin:yours/recommended]` to load from `eslint-plugin-yours`
+
+## Resolution
+
+Common resolutions for this issue include:
+
+* Upgrading all versions of all packages to their latest version
+* Adding the config as a `devDependency` in your `package.json`
+* Running `npm install` or the equivalent package manager command
+* Checking that the name in your config file matches the name of the config package
+
+## Resources
+
+For more information, see:
+
+* [Legacy ESLint configuration files](../configure/configuration-files-deprecated#using-a-shareable-configuration-package) for documentation on the legacy ESLint configuration format
+    * [Legacy ESLint configuration files > Using a shareable configuration package](../configure/configuration-files-deprecated#using-a-shareable-configuration-package) for documentation on using shareable configurations
+* [Share Configurations](../../extend/shareable-configs) for documentation on how to define standalone shared configs
+* [Create Plugins > Configs in Plugins](../../extend/plugins#configs-in-plugins) for documentation on how to define shared configs in plugins

docs/src/use/troubleshooting/couldnt-find-the-plugin.md

@@ -0,0 +1,65 @@
+---
+title: ESLint couldn't find the plugin …
+eleventyNavigation:
+    key: couldn't find the plugin
+    parent: troubleshooting
+    title: ESLint couldn't find the plugin …
+---
+
+## Symptoms
+
+When using the [legacy ESLint config system](../configure/configuration-files-deprecated), you may see this error running ESLint after installing dependencies:
+
+```plaintext
+ESLint couldn't find the plugin "${pluginName}".
+
+(The package "${pluginName}" was not found when loaded as a Node module from the directory "${resolvePluginsRelativeTo}".)
+
+It's likely that the plugin isn't installed correctly. Try reinstalling by running the following:
+
+    npm install ${pluginName}@latest --save-dev
+
+The plugin "${pluginName}" was referenced from the config file in "${importerName}".
+```
+
+## Cause
+
+[Legacy ESLint configuration files](../configure/configuration-files-deprecated) specify shareable configs by their package name.
+That package name is passed to the Node.js `require()`, which looks up the package under local `node_modules/` directories.
+For example, the following ESLint config will first try to load a module located at `node_modules/eslint-plugin-yours`:
+
+```js
+module.exports = {
+    extends: ["plugin:eslint-plugin-yours/config-name"],
+};
+```
+
+If the package is not found in any searched `node_modules/`, ESLint will print the aforementioned error.
+
+Common reasons for this occurring include:
+
+*   Not running `npm install` or the equivalent package manager command
+*   Mistyping the case-sensitive name of the plugin
+
+### Plugin Name Variations
+
+Note that the `eslint-plugin-` plugin name prefix may be omitted for brevity, e.g. `extends: ["yours"]`.
+
+[`@` npm scoped packages](https://docs.npmjs.com/cli/v10/using-npm/scope) put the `eslint-plugin-` prefix after the org scope, e.g. `extends: ["@org/yours"]` to load from `@org/eslint-plugin-yours`.
+
+## Resolution
+
+Common resolutions for this issue include:
+
+* Upgrading all versions of all packages to their latest version
+* Adding the plugin as a `devDependency` in your `package.json`
+* Running `npm install` or the equivalent package manager command
+* Checking that the name in your config file matches the name of the plugin package
+
+## Resources
+
+For more information, see:
+
+* [Legacy ESLint configuration files](../configure/configuration-files-deprecated#using-a-shareable-configuration-package) for documentation on the legacy ESLint configuration format
+* [Configure Plugins](../configure/plugins) for documentation on how to extend from plugins
+* [Create Plugins](../../extend/plugins#configs-in-plugins) for documentation on how to define plugins

docs/src/use/troubleshooting/index.md

@@ -0,0 +1,18 @@
+---
+title: Troubleshooting
+eleventyNavigation:
+    key: troubleshooting
+    title: Troubleshooting
+    parent: use eslint
+    order: 8
+---
+
+This page serves as a reference for common issues working with ESLint.
+
+* [`ESLint couldn't determine the plugin … uniquely`](./couldnt-determine-the-plugin-uniquely)
+* [`ESLint couldn't find the config … to extend from`](./couldnt-find-the-config)
+* [`ESLint couldn't find the plugin …`](./couldnt-find-the-plugin)
+
+Issues oftentimes can be resolved by updating the to latest versions of the `eslint` package and any related packages, such as for ESLint shareable configs and plugins.
+
+If you still can't figure out the problem, please stop by <https://eslint.org/chat/help> to chat with the team.

messages/plugin-conflict.js

@@ -15,7 +15,7 @@ module.exports = function(it) {
 
 Please remove the "plugins" setting from either config or remove either plugin installation.
 
-If you still can't figure out the problem, please stop by https://eslint.org/chat/help to chat with the team.
+If you still can't figure out the problem, please see https://eslint.org/docs/latest/use/troubleshooting.
 `;
 
     return result;

messages/plugin-invalid.js

@@ -11,6 +11,6 @@ module.exports = function(it) {
 
 "${configName}" was referenced from the config file in "${importerName}".
 
-If you still can't figure out the problem, please stop by https://eslint.org/chat/help to chat with the team.
+If you still can't figure out the problem, please see https://eslint.org/docs/latest/use/troubleshooting.
 `.trimStart();
 };

messages/plugin-missing.js

@@ -14,6 +14,6 @@ It's likely that the plugin isn't installed correctly. Try reinstalling by runni
 
 The plugin "${pluginName}" was referenced from the config file in "${importerName}".
 
-If you still can't figure out the problem, please stop by https://eslint.org/chat/help to chat with the team.
+If you still can't figure out the problem, please see https://eslint.org/docs/latest/use/troubleshooting.
 `.trimStart();
 };