Improve documentation for the parser option (#5129)

- Warn about setting parser at the top level. Refs. #4638.
- Remove top level parser from examples. Instead show the most common
options (I also removed printWidth, since we don't recommend changing
it). Refs. #4638.
- Show how to configure the flow parser for .js files. Refs. #4638.
- Update valid options for the parser option, including links and "since
version".
- Clarify babylon vs flow.

docs/options.md

@@ -160,17 +160,29 @@ These options cannot be used with `cursorOffset`.
 
 Specify which parser to use.
 
-Both the `babylon` and `flow` parsers support the same set of JavaScript features (including Flow). Prettier automatically infers the parser from the input file path, so you shouldn't have to change this setting.
+Prettier automatically infers the parser from the input file path, so you shouldn't have to change this setting.
 
-Built-in parsers:
+Both the `babylon` and `flow` parsers support the same set of JavaScript features (including Flow type annotations). They might differ in some edge cases, so if you run into one of those you can try `flow` instead of `babylon`.
 
-- [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon)
-- [`flow`](https://github.com/facebook/flow/tree/master/src/parser)
-- [`typescript`](https://github.com/JamesHenry/typescript-estree) _Since v1.4.0_
-- [`postcss`](https://github.com/postcss/postcss) _Since v1.4.0_
-- [`json`](https://github.com/babel/babylon/tree/f09eb3200f57ea94d51c2a5b1facf2149fb406bf#babylonparseexpressioncode-options) _Since v1.5.0_
-- [`graphql`](https://github.com/graphql/graphql-js/tree/master/src/language) _Since v1.5.0_
-- [`markdown`](https://github.com/wooorm/remark/tree/master/packages/remark-parse) _Since v1.8.0_
+Valid options:
+
+- `"babylon"` (via [@babel/parser](https://github.com/babel/babel/tree/master/packages/babel-parser))
+- `"flow"` (via [flow-parser](https://github.com/facebook/flow/tree/master/src/parser))
+- `"typescript"` (via [typescript-estree](https://github.com/JamesHenry/typescript-estree)) _Since v1.4.0_
+- `"css"` (via [postcss-scss](https://github.com/postcss/postcss-scss) and [postcss-less](https://github.com/shellscape/postcss-less), autodetects which to use) _Since v1.7.1_
+- `"scss"` (same parsers as `"css"`, prefers postcss-scss) _Since v1.7.1_
+- `"less"` (same parsers as `"css"`, prefers postcss-less) _Since v1.7.1_
+- `"json"` (via [@babel/parser parseExpression](https://babeljs.io/docs/en/next/babel-parser.html#babelparserparseexpressioncode-options)) _Since v1.5.0_
+- `"json5"` (same parser as `"json"`, but outputs as [json5](https://json5.org/)) _Since v1.13.0_
+- `"json-stringify"` (same parser as `"json"`, but outputs like `JSON.stringify`) _Since v1.13.0_
+- `"graphql"` (via [graphql/language](https://github.com/graphql/graphql-js/tree/master/src/language)) _Since v1.5.0_
+- `"markdown"` (via [remark-parse](https://github.com/wooorm/remark/tree/master/packages/remark-parse)) _Since v1.8.0_
+- `"vue"` (uses several parsers) _Since 1.10.0_
+- `"yaml"` (via [yaml](https://github.com/eemeli/yaml) and [yaml-unist-parser](https://github.com/ikatyang/yaml-unist-parser)) _Since 1.14.0_
+
+<!-- TODO: Uncomment and move below "markdown" above when 1.15.0 is released.
+- `"mdx"` (same parser as `"markdown"`, with some custom overrides) _Since 1.15.0_
+-->
 
 [Custom parsers](api.md#custom-parser-api) are also supported. _Since v1.5.0_
 
@@ -184,7 +196,7 @@ Note: the default value was `"babylon"` until v1.13.0.
 
 Specify the input filepath. This will be used to do parser inference.
 
-For example, the following will use `postcss` parser:
+For example, the following will use the CSS parser:
 
 ```bash
 cat foo | prettier --stdin-filepath foo.css