Add docs for top level await parsing (#2115)

* Add docs for top level await parsing

* Typo

Co-Authored-By: Brian Ng <bng412@gmail.com>

* Update docs/plugin-syntax-top-level-await.md

Co-Authored-By: Huáng Jùnliàng <jlhwung@gmail.com>

docs/parser.md

@@ -34,9 +34,10 @@ mind. When in doubt, use `.parse()`.
   declarations can only appear at a program's top level. Setting this
   option to `true` allows them anywhere where a statement is allowed.
 
-- **allowAwaitOutsideFunction**: By default, `await` use is not allowed
-  outside of an async function. Set this to `true` to accept such
-  code.
+- **allowAwaitOutsideFunction**: By default, `await` use is only allowed
+  inside of an async function or, when the `topLevelAwait` plugin is enabled,
+  in the top-level scope of modules. Set this to `true` to also accept it in the
+  top-level scope of scripts.
 
 - **allowReturnOutsideFunction**: By default, a return statement at
   the top level raises an error. Set this to `true` to accept such
@@ -174,6 +175,7 @@ require("@babel/parser").parse("code", {
 | `partialApplication` ([proposal](https://github.com/babel/proposals/issues/32)) | `f(?, a)` |
 | `pipelineOperator` ([proposal](https://github.com/babel/proposals/issues/29)) | <code>a &#124;> b</code> |
 | `throwExpressions` ([proposal](https://github.com/babel/proposals/issues/23)) | `() => throw new Error("")` |
+| `topLevelAwait` ([proposal])(https://github.com/tc39/proposal-top-level-await/) | `await promise` in modules |
 
 #### Plugins options
 

docs/plugin-syntax-top-level-await.md

@@ -0,0 +1,49 @@
+---
+id: babel-plugin-syntax-top-level-await
+title: @babel/plugin-syntax-top-level-await
+sidebar_label: syntax-top-level-await
+---
+
+> #### Syntax only
+>
+> This plugin only enables parsing of this feature. Babel doesn't support transforming
+> top-level await, but you can use Rollup's `experimentalTopLevelAwait` or webpack@5's
+> `experiments.topLevelAwait` options.
+
+```js
+const val = await promise;
+
+export { val };
+```
+
+## Installation
+
+```sh
+npm install --save-dev @babel/plugin-syntax-top-level-await
+```
+
+## Usage
+
+### Via `.babelrc` (Recommended)
+
+**.babelrc**
+
+```json
+{
+  "plugins": ["@babel/plugin-syntax-top-level-await"]
+}
+```
+
+### Via CLI
+
+```sh
+babel --plugins @babel/plugin-syntax-top-level-await script.js
+```
+
+### Via Node API
+
+```javascript
+require("@babel/core").transform(code, {
+  plugins: ["@babel/plugin-syntax-top-level-await"],
+});
+```