Merge branch 'main' into next

# Conflicts:
#	CONTRIBUTING.md
#	cspell.json
#	docs/options.md
#	package.json
#	scripts/build/bundler.mjs
#	src/language-css/loc.js
#	src/language-css/parser-postcss.js
#	src/language-css/utils/index.js
#	tests/format/js/arrows-bind/jsfmt.spec.js
#	tests/format/js/async-do-expressions/jsfmt.spec.js
#	tests/format/js/bind-expressions/jsfmt.spec.js
#	tests/format/js/classes/top-level-super/jsfmt.spec.js
#	tests/format/js/comments-pipeline-own-line/jsfmt.spec.js
#	tests/format/js/decorator-comments/jsfmt.spec.js
#	tests/format/js/decorators-export/jsfmt.spec.js
#	tests/format/js/decorators/jsfmt.spec.js
#	tests/format/js/do/jsfmt.spec.js
#	tests/format/js/export-default/escaped/jsfmt.spec.js
#	tests/format/js/export-extension/jsfmt.spec.js
#	tests/format/js/export-star/jsfmt.spec.js
#	tests/format/js/exports/jsfmt.spec.js
#	tests/format/js/invalid-code/jsfmt.spec.js
#	tests/format/js/logical-assignment/jsfmt.spec.js
#	tests/format/js/multiparser-invalid/jsfmt.spec.js
#	tests/format/js/no-semi-babylon-extensions/jsfmt.spec.js
#	tests/format/js/object-property-comment/jsfmt.spec.js
#	tests/format/js/partial-application/jsfmt.spec.js
#	tests/format/js/pipeline-operator/jsfmt.spec.js
#	tests/format/js/private-in/jsfmt.spec.js
#	tests/format/js/record/jsfmt.spec.js
#	tests/format/js/reserved-word/jsfmt.spec.js
#	tests/format/js/strings/jsfmt.spec.js
#	tests/format/js/throw_expressions/jsfmt.spec.js
#	tests/format/js/trailing-whitespace/jsfmt.spec.js
#	tests/format/js/v8_intrinsic/jsfmt.spec.js
#	tests/format/misc/errors/js/literal/jsfmt.spec.js
#	tests/format/misc/errors/js/object/jsfmt.spec.js
#	tests/format/misc/errors/js/variable-declarator/jsfmt.spec.js
#	tests/integration/__tests__/bundle.js
#	tsconfig.json
#	yarn.lock

docs/options.md

@@ -265,6 +265,7 @@ Valid options:
 - `"typescript"` (via [@typescript-eslint/typescript-estree](https://github.com/typescript-eslint/typescript-eslint)) _First available in v1.4.0_
 - `"espree"` (via [espree](https://github.com/eslint/espree)) _First available in v2.2.0_
 - `"meriyah"` (via [meriyah](https://github.com/meriyah/meriyah)) _First available in v2.2.0_
+- `"acorn"` (via [acorn](https://github.com/acornjs/acorn)) _First available in v2.6.0_
 - `"css"` (via [postcss](https://github.com/postcss/postcss)) _First available in v1.7.1_
 - `"scss"` (via [postcss-scss](https://github.com/postcss/postcss-scss)) _First available in v1.7.1_
 - `"less"` (via [postcss-less](https://github.com/shellscape/postcss-less) _First available in v1.7.1_
@@ -350,13 +351,13 @@ Note that “in tandem” doesn’t mean “at the same time”. When the two op
 
 _First available in v1.8.2_
 
-By default, Prettier will wrap markdown text as-is since some services use a linebreak-sensitive renderer, e.g. GitHub comment and BitBucket. In some cases you may want to rely on editor/viewer soft wrapping instead, so this option allows you to opt out with `"never"`.
+By default, Prettier will not change wrapping in markdown text since some services use a linebreak-sensitive renderer, e.g. GitHub comments and BitBucket. To have Prettier wrap prose to the print width, change this option to "always". If you want Prettier to force all prose blocks to be on a single line and rely on editor/viewer soft wrapping instead, you can use `"never"`.
 
 Valid options:
 
 - `"always"` - Wrap prose if it exceeds the print width.
-- `"never"` - Do not wrap prose.
-- `"preserve"` - Wrap prose as-is. _First available in v1.9.0_
+- `"never"` - Un-wrap each block of prose into one line.
+- `"preserve"` - Do nothing, leave prose as-is. _First available in v1.9.0_
 
 | Default      | CLI Override                                                | API Override                                                |
 | ------------ | ----------------------------------------------------------- | ----------------------------------------------------------- |

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).