Fix plugin API in globally installed Prettier and introduce optional --plugin-search-dir (#4192)

* Fix plugin API in globally installed Prettier and introduce optional --plugin-search-dir

* Use find-parent-dir instead of find-up and test autoloading (with mocked fn)

* Add two test cases where --plugin-search-dir is not .

* Do not mutate pluginSearchDirs argument in load-plugins.js

* Do not test automatic plugin resolution as mocking of "find-parent-dir" does not work due to rollup

* Document --plugin-search-dir / pluginSearchDirs and improve spacing

* Address @ikatyang's review comments

* Fix require path for third-party

* Undo alphabetic sorting of third-party scripts

docs/plugins.md

@@ -7,31 +7,36 @@ title: Plugins (Beta)
 
 > The plugin API is in a **beta** state as of Prettier 1.10 and the API may change in the next release!
 
-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-focussed languages built in. For additional languages you'll need to install a plugin.
+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.
 
 ## Using Plugins
 
-Plugins are automatically loaded if you have them installed in your `package.json`. Prettier plugin package names must start with `@prettier/plugin-` or `prettier-plugin-` to be registered.
+Plugins are automatically loaded if you have them installed in the same `node_modules` directory where `prettier` is located. Plugin package names must start with `@prettier/plugin-` or `prettier-plugin-` to be registered.
 
-If the plugin is unable to be found automatically, you can load them with:
+When plugins cannot be found automatically, you can load them with:
 
-* The [CLI](./cli.md), via the `--plugin` flag:
+* The [CLI](./cli.md), via the `--plugin` and `--plugin-search-dir`:
 
   ```bash
-  prettier --write main.foo --plugin=./foo-plugin
+  prettier --write main.foo --plugin-search-dir=./dir-with-plugins --plugin=./foo-plugin
   ```
 
-  > Tip: You can pass multiple `--plugin` flags.
+  > Tip: You can set `--plugin` or `--plugin-search-dir` options multiple times.
 
-* Or the [API](./api.md), via the `plugins` field:
+* Or the [API](./api.md), via the `plugins` and `pluginSearchDirs` options:
 
   ```js
   prettier.format("code", {
     parser: "foo",
+    pluginSearchDirs: ["./dir-with-plugins"],
     plugins: ["./foo-plugin"]
   });
   ```
 
+Prettier expects each of `pluginSearchDirs` to contain `node_modules` subdirectory, where `@prettier/plugin-*` and `prettier-plugin-*` will be searched. For instance, this can be your project directory or the location of global npm modules.
+
+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).
+
 ## Official Plugins
 
 * [`@prettier/plugin-python`](https://github.com/prettier/plugin-python)