From 331d278a3a52c68ce02c349e9a2f12f29048d7a1 Mon Sep 17 00:00:00 2001
From: Adam <adamhl@pm.me>
Date: Mon, 7 Feb 2022 19:44:47 +0100
Subject: [PATCH] Update plugin docs (#12259)

Co-authored-by: fisker Cheung <lionkay@gmail.com>
---
 docs/plugins.md | 27 ++++++++++++++++++++-------
 1 file changed, 20 insertions(+), 7 deletions(-)

diff --git a/docs/plugins.md b/docs/plugins.md
index 143a82e73..a227e74e0 100644
--- a/docs/plugins.md
+++ b/docs/plugins.md
@@ -3,7 +3,7 @@ id: plugins
 title: Plugins
 ---
 
-Plugins are ways of adding new languages to Prettier. Prettier’s own implementations of all languages are expressed using the plugin API. The core `prettier` package contains JavaScript and other web-focused languages built in. For additional languages you’ll need to install a plugin.
+Plugins are ways of adding new languages or formatting rules to Prettier. Prettier’s own implementations of all languages are expressed using the plugin API. The core `prettier` package contains JavaScript and other web-focused languages built in. For additional languages you’ll need to install a plugin.
 
 ## Using Plugins
 
@@ -13,25 +13,38 @@ Plugins are automatically loaded if you have them installed in the same `node_mo
 
 When plugins cannot be found automatically, you can load them with:
 
-- The [CLI](cli.md), via the `--plugin` and `--plugin-search-dir`:
+- The [CLI](cli.md), via `--plugin-search-dir` and `--plugin`:
 
   ```bash
-  prettier --write main.foo --plugin-search-dir=./dir-with-plugins --plugin=./foo-plugin
+  prettier --write main.foo --plugin-search-dir=./dir-with-plugins --plugin=prettier-plugin-foo
   ```
 
-  > Tip: You can set `--plugin` or `--plugin-search-dir` options multiple times.
+  > Tip: You can set `--plugin-search-dir` or `--plugin` options multiple times.
 
-- Or the [API](api.md), via the `plugins` and `pluginSearchDirs` options:
+- The [API](api.md), via the `pluginSearchDirs` and `plugins` options:
 
   ```js
   prettier.format("code", {
     parser: "foo",
     pluginSearchDirs: ["./dir-with-plugins"],
-    plugins: ["./foo-plugin"],
+    plugins: ["prettier-plugin-foo"],
   });
   ```
 
-Prettier expects each of `pluginSearchDirs` to contain `node_modules` subdirectory, where `@prettier/plugin-*`, `@*/prettier-plugin-*` and `prettier-plugin-*` will be searched. For instance, this can be your project directory or the location of global npm modules.
+- The [Configuration File](configuration.md):
+
+  ```json
+  {
+    "pluginSearchDirs": ["./dir-with-plugins"],
+    "plugins": ["prettier-plugin-foo"]
+  }
+  ```
+
+`pluginSearchDirs` and `plugins` are independent and one does not require the other.
+
+The paths that are provided to `pluginSearchDirs` will be searched for `@prettier/plugin-*`, `prettier-plugin-*`, and `@*/prettier-plugin-*`. For instance, these can be your project directory, a `node_modules` directory, the location of global npm modules, or any arbitrary directory that contains plugins.
+
+Strings provided to `plugins` are ultimately passed to `require()`, so you can provide a module/package name, a path, or anything else `require()` takes. (`pluginSearchDirs` works the same way. That is, valid plugin paths that it finds are passed to `require()`.)
 
 Providing at least one path to `--plugin-search-dir`/`pluginSearchDirs` turns off plugin autoloading in the default directory (i.e. `node_modules` above `prettier` binary).