From 3c1e2498460345147f3ff721212050f02b8be6c5 Mon Sep 17 00:00:00 2001
From: Logan Smyth <loganfsmyth@gmail.com>
Date: Mon, 27 Aug 2018 21:14:27 -0700
Subject: [PATCH] Add a bunch of docs for options and config files.

---
 docs/babelconfigjs.md    | 112 ------
 docs/babelrc.md          | 112 ------
 docs/cli.md              |   2 +-
 docs/config-files.md     | 229 ++++++++++++
 docs/configuration.md    |  10 +-
 docs/core.md             | 152 +++++---
 docs/env.md              |  10 +-
 docs/faq.md              |   2 +-
 docs/options.md          | 766 +++++++++++++++++++++++++++++++++++++++
 docs/parser.md           |  17 +-
 docs/preset-env.md       |  34 +-
 docs/preset-react.md     |   2 +-
 docs/presets.md          |   6 +-
 docs/register.md         |   7 +-
 docs/roadmap.md          |   8 +-
 docs/standalone.md       |   2 +-
 docs/v7-migration-api.md |   6 +-
 docs/v7-migration.md     |   6 +-
 website/i18n/en.json     | 206 +++++------
 website/sidebars.json    |   4 +-
 20 files changed, 1254 insertions(+), 439 deletions(-)
 delete mode 100644 docs/babelconfigjs.md
 delete mode 100644 docs/babelrc.md
 create mode 100644 docs/config-files.md
 create mode 100644 docs/options.md

diff --git a/docs/babelconfigjs.md b/docs/babelconfigjs.md
deleted file mode 100644
index 1adc4a915b..0000000000
--- a/docs/babelconfigjs.md
+++ /dev/null
@@ -1,112 +0,0 @@
----
-title: babel.config.js
-id: babelconfigjs
----
-
-## Lookup behavior
-
-The lookup behavior is direct as Babel will only look for a `babel.config.js` in the root directory (where your `package.json` is by default). If configuration is needed, see [specifying the root folder](babelconfigjs.md#specifying-the-root-folder).
-
-## Merging behavior
-
-Unlike other formats (see the [configuration guide](configuration.md)), Babel won't try to merge configurations.
-
-```js
-project
-├── package.json
-├── babel.config.js
-├── node_modules
-│   └── depA
-│       ├── .babelrc // ignored
-│       └── index.js // babel.config.js will be used
-└── src
-    ├── .babelrc // ignored
-    └── index.js // babel.config.js will be used
-```
-
-> Note: the configuration defined in `babel.config.js` is applied to your entire project.
-
-## Dynamic configuration
-
-Since it's just a regular JavaScript file, you can write any arbitrary logic or use the Nodejs API:
-
-```js
-const pkg = require("./package.json");
-
-module.exports = function () {
-  const plugins = [ ... ];
-
-  if (pkg.authors.includes("Fieri")) {
-    plugins.push(...);
-  }
-
-  return { plugins };
-}
-```
-
-### Environment
-
-A conditional configuration is useful when you want to use certain plugins/presets based on the current environment, for example:
-
-```js
-module.exports = function () {
-  const plugins = [ ... ];
-
-  if (process.env["REMOVE_DEBUG"] === 1) {
-    plugins.push("babel-plugin-remove-console-debug");
-  }
-
-  return { plugins };
-}
-```
-
-You can invoke it using the CLI:
-
-```sh
-REMOVE_DEBUG=1 babel file.js
-```
-
-## API
-
-Babel will pass an object as first argument, called `api` here.
-
-```js
-module.exports = function (api) {
-  const babelEnv = api.env();
-
-  return { ... };
-}
-```
-
-### `api.env()`
-
-Returns Babel's environment, you can configure it using the `BABEL_ENV` environment variable.
-
-### `api.version`
-
-Returns Babel's core version.
-
-### `api.cache()`
-
-// TODO
-
-## Specifying the root folder
-
-You can pass a `root` in the Babel configuration, see [@Babel/core's documentation](babel-core.md#options).
-
-## Extending other `.babelrc`
-
-To allow people to opt into `.babelrc` usage, potentially for local development; you can specify a list of `.babelrc` to use.
-
-For example using `babel-loader`:
-
-```js
-test: /\.js$/,
-loader: "babel-loader",
-options: {
-  babelrc: [
-    ".",
-    "../some-linked-package"
-  ]
-}
-```
diff --git a/docs/babelrc.md b/docs/babelrc.md
deleted file mode 100644
index 7c2203e77e..0000000000
--- a/docs/babelrc.md
+++ /dev/null
@@ -1,112 +0,0 @@
----
-title: .babelrc
-id: babelrc
----
-
-## Lookup behavior
-
-Babel will look for a `.babelrc` in the current directory (which defaults to cwd). For example if you are using a monorepo and you run Babel from the `packageA`:
-
-```js
-project
-├── .babelrc // ignored
-└── monorepo
-    └── packageA
-        ├── package.json
-        └── ...
-```
-
-Use `"babelrc": false` in [options](core.md#options) to stop lookup behavior, or provide the [`--no-babelrc` CLI flag](babel-cli.md#babel-ignoring-babelrc).
-
-## Merging behavior
-
-If Babel finds other `.babelrc` files while transpiling files in subfolder, it will merge the configuration together.
-
-> Note that it can lead to undefined behaviors, and we recommend to use [`babel.config.js` documentation](babelconfigjs.md) instead.
-
-## `"overrides"`
-
-Babel takes this idea from [ESLint](http://eslint.org/docs/user-guide/configuring#example-configuration). This gives you the ability to apply a configuration to specific files.
-
-Every config object can specify a `test`/`include`/`exclude` (like Webpack).
-Each item allows an `item`, or `array of items` that can be a `string`, `RegExp`, or `function`.
-
-"overrides" is an array of sub-configs that apply on top of the base configs that will apply based on their `test`/`include`/`exclude` values.
-
-Example of compiling client code against browsers while the rest of the server code is compiled against node.
-
-```json
-{
-  "presets": [
-    ["env", { 
-      "targets": { "node": "current" },
-    }],
-  ],
-  "overrides": [{
-    "test": "./client",
-    "presets": [
-      ["env", { 
-        "targets": { "browsers": ["last 2 versions"] },
-      }],
-    ],
-  }],
-}
-```
-
-## `env` (environment) option
-
-You can use the `env` option to set specific options when in a certain environment:
-
-```json
-{
-  "env": {
-    "production": {
-      "plugins": ["@babel/plugin-transform-classes"]
-    }
-  }
-}
-```
-
-Options specific to a certain environment are merged into and overwrite non-env specific options.
-
-The `env` key will be taken from `process.env.BABEL_ENV`, when this is not available then it uses
-`process.env.NODE_ENV` if even that is not available then it defaults to `"development"`.
-
-
-#### `envName`
-
-Instead of setting an environment variable, one can pass `envName` or `--env-name` explicitly.
-
-#### Setting an environment variable
-
-Or you can set this environment variable implicitly with the following:
-
-**Unix**
-
-At the start of a command:
-
-```sh
-BABEL_ENV=production YOUR_COMMAND_HERE
-```
-
-Or as a separate command:
-
-```sh
-export BABEL_ENV=production
-```
-
-```sh
-YOUR_COMMAND_HERE
-```
-
-**Windows**
-
-```sh
-SET BABEL_ENV=production
-```
-
-```sh
-YOUR_COMMAND_HERE
-```
-
-> If you want your command to work across platforms, you can use [`cross-env`](https://www.npmjs.com/package/cross-env)
diff --git a/docs/cli.md b/docs/cli.md
index 9ddaedc4f4..0cb989d8e0 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -147,4 +147,4 @@ npx babel --no-babelrc script.js --out-file script-compiled.js --presets=es2015,
 
 ### Advanced Usage
 
-There are many more options available in the babel CLI, see [options](core.md/#options), `babel --help` and other sections for more information.
+There are many more options available, see [options](options.md), `babel --help` and other sections for more information.
diff --git a/docs/config-files.md b/docs/config-files.md
new file mode 100644
index 0000000000..f940400de7
--- /dev/null
+++ b/docs/config-files.md
@@ -0,0 +1,229 @@
+---
+title: Config Files
+id: config-files
+---
+
+## Configuration File Types
+
+Babel has two parallel config file formats, which can be used together, or independently.
+
+* Project-wide configuration
+* File-relative configuration
+  * `.babelrc` (and `.babelrc.js`) files
+  * `package.json` files with a `"babel"` key
+
+
+## Project-wide configuration
+
+New in Babel 7.x, Babel has as concept of a ["root"](options.md#root) directory, which defaults
+to the current working directory. For project-wide configuration, Babel will automatically search
+for a `"babel.config.js"` in this root directory. Alternatively, users can use an explicit
+["configFile"](options.md#configFile) value to override the default config file search behavior.
+
+Because project-wide config files are separated from the physical location of the config
+file, they can be ideal for configuration that must apply broadly, even allowing
+plugins and presets to easily apply to files in `node_modules` or in symlinked packages,
+which were traditionally quite painful to configure in Babel 6.x.
+
+The primary downside of this project-wide config is that, because it relies on the working
+directory, it can be more painful to use in monorepos if the working directory is not the monorepo root.
+For example, if you have
+
+```text
+babel.config.js
+packages/
+  mod1/
+    package.json
+    src/index.js
+  mod2/
+    package.json
+    src/index.js
+```
+and the individual packages are responsible for running their builds (and their working
+directory for Babel is the individual packages), the `babel.config.js` file will not be automatically
+loaded, and users will be required to set the path to it manually.
+
+Project-wide configs can also be disable by setting ["configFile"](options.md#configFile) to `false`.
+
+## File-relative configuration
+
+Babel loads `.babelrc` (and `.babelrc.js` / `package.json#babel`) files by searching up the
+directory structure starting from the ["filename"](options.md#filename) being compiled. This can
+be powerful because it allows you to create independent configurations for subsections of
+a repository. File-relative configurations are also [merge](options.md#merging) over top of
+project-wide config values, making them potentially useful for specific overrides, though that can
+also be accomplished through ["overrides"](options.md#overrides).
+
+There are a few edge cases to consider when using a file-relative config:
+* Searching will stop once a directory containing a `package.json` is found, so a relative config
+  only applies within a single package.
+* The ["filename"](options.md#filename) being compiled must be inside of
+  ["babelrcRoots"](options.md#babelrcRoots) packages, or else searching will be skipped entirely.
+
+File-relative configs can also be disable by setting ["babelrc"](options.md#babelrc) to `false`.
+
+### 6.x vs 7.x `.babelrc` loading
+
+Users coming from Babel 6.x will likely trip up on these two edge cases, which are new in Babel 7.x.
+These two restrictions were added to address common footguns in Babel 6.x:
+
+* `.babelrc` files applied to `node_modules` dependencies, often unexpectedly.
+* `.babelrc` files _failed_ to apply to symlinked `node_modules` when people expected them to behave like normal dependencies.
+* `.babelrc` files _in_ `node_modules` dependencies would be detected, even though the plugins and
+  presets inside they were generally not installed, and may not even be valid in the version of
+  Babel compiling the file.
+
+These cases will _primarily_ cause issues for users with a monorepo structure, because if you
+have
+```text
+.babelrc
+packages/
+  mod1/
+    package.json
+    src/index.js
+  mod2/
+    package.json
+    src/index.js
+```
+the config will now be entirely ignored, because it is across a package boundary.
+
+One alternative would be to reate a `.babelrc` in each sub-package that uses ["extends"](options.md#extends) as
+```json
+{ "extends": "../../.babelrc" }
+```
+Unfortunately, this approach can be a bit repetitive, and depending on how Babel is being used,
+could require setting ["babelrcRoots"](options.md#babelrcRoots).
+
+Given that, it may be more desirable to rename the `.babelrc` to be a
+[project-wide "babel.config.js"](#project-wide-configuration). As mentioned in the project-wide
+section above, this may then require explicitly setting ["configFile"](options.md#configFile)
+since Babel will not find the config file if the working directory isn't correct.
+
+
+## Config Format
+
+The format of individual config files themselves separates into JS files vs [JSON5](https://json5.org/) files.
+
+### JSON5
+
+Any file that isn't a `.js` file will be parsed as JSON5 and should contain an object matching
+the [options](options.md) format that Babel accepts.
+
+### JavaScript
+
+Any `.js` file will be `require()`ed and should export either a configuration object, or a function
+that will return a configuration object when called. The main benefit being that users can include
+JS logic to build up their config structures, potentially allowing config logic to be shared
+more easily. `.js` files can be used as [project-wide configuration](#project-wide-configuration) or
+via `.babelrc.js` files for [file-relative configuration](#file-relative-configuration).
+
+Function-returning configs are given a few special powers because they can access an API exposed
+by Babel itself. See [Config Function API](#config-function-api) for more information.
+
+## Config Function API
+
+JS config files may export a function that will be passed config function API:
+
+```js
+module.exports = function(api) {
+  return {};
+}
+```
+
+The `api` object exposes everthing Babel itself exposes from its index module, along with
+config-file specific APIs:
+
+### `api.version`
+
+Type: `string`<br />
+
+The version string for the Babel version that is loading the config file.
+
+### `api.cache`
+
+JS configs are great because they can compute a config on the fly, but the downside
+there is that it makes caching harder. Babel wants to avoid re-executing the
+config function every time a file is compiled, because then it would also need to
+re-execute any plugin and preset functions referenced in that config.
+
+The avoid this, Babel expects users of config functions to tell it how to manage
+caching within a config file.
+
+* `api.cache.forever()` - Permacache the computed config and never call the function again.
+* `api.cache.never()` - Do not cache this config, and re-execute the function every time.
+* `api.cache.using(() => process.env.NODE_ENV)` - Cache based on the value of `NODE_ENV`.
+  Any time the `using` callback returns a value other than the one that was expected, the overall
+  config function will be called again and a new entry will be added to the cache.
+* `api.cache.invalidate(() => process.env.NODE_ENV)` - Cache based on the value of `NODE_ENV`.
+  Any time the `using` callback returns a value other than the one that was expected, the overall
+  config function will be called again and all entries in the cache will be replaced with the result.
+
+Since the actual callback result is used to check if the cache entry is valid, it is recommended
+that:
+
+* Callbacks should be small and side-effect free.
+* Callbacks should return values with the smallest range possible. For example, the
+  `.using(() => process.env.NODE_ENV)` usage above is not idea because it would create an unknown
+  number of cache entries depending on how many values of `NODE_ENV` are detected. It would be
+  safer to do `.using(() => process.env.NODE_ENV === "development")` because they the cache entry
+  can only ever be `true` or `false`.
+
+, which also includes access to Babel's own ["envName"](options.md#envName)
+
+### `api.env(...)`
+
+Since `NODE_ENV` is a fairly common way to toggle behavior, Babel also includes an API function
+meant specifically for that. This API is used as a quick way to check the
+["envName"](options.md#envName) that Babel was loaded with, which takes `NODE_ENV` into account
+if no other overriding environment is set.
+
+It has a few different forms:
+
+* `api.env("production")` returns `true` if `envName === "production"`.
+* `api.env(["development", "test"])` returns `true` if `["development", "test"].includes(envName)`.
+* `api.env()` returns the current `envName` string.
+* `api.env(envName => envName.startsWith("test-"))` returns `true` if the env starts with "test-".
+
+This function internally makes use of `api.cache` mentioned below to ensure that
+Babel is aware that this build depends on a specific `envName`.
+
+
+### `api.caller(cb)`
+
+This API is used as a way to access the `caller` data that has been passed to Babel.
+Since many instances of Babel may be running in the same process with different `caller`
+values, this API is designed to automatically configure `api.cache`, the same way `api.env()` does.
+
+The `caller` value is available as the first parameter of the callback function. It is best used
+with something like
+```js
+function isBabelRegister(caller) {
+  return !!(caller && caller.name === "@babel/register");
+}
+
+module.exports = function(api) {
+  const isRegister = api.caller(isBabelRegister);
+
+  return {
+    // ...
+  };
+}
+```
+to toggle configuration behavior based on a specific environment.
+
+
+### `api.assertVersion(range)`
+
+While `api.version` can be useful in general, it's sometimes nice to just declare your version.
+This API exposes a simple way to do that with:
+```js
+module.exports = function(api) {
+  api.assertVersion("^7.2");
+
+  return {
+    // ...
+  };
+};
+```
+
+
diff --git a/docs/configuration.md b/docs/configuration.md
index 8e85b36316..a1d2fc6e9c 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -5,7 +5,7 @@ title: Configure Babel
 
 Babel can be configured! Many other tools have similar configs: ESLint (`.eslintrc`), Prettier (`.prettierrc`).
 
-All Babel API [options](core.md#options) are allowed. However if the option requires JavaScript, you may need to use a `.babelrc.js` file.
+All Babel API [options](options.md) are allowed. However if the option requires JavaScript, you may want to use a Javascript [configuration file](config-files.md).
 
 ## What's your use case?
 
@@ -14,13 +14,13 @@ All Babel API [options](core.md#options) are allowed. However if the option requ
 
 > [`babel.config.js`](#babelconfigjs) is for you!
 
-- You have a static configuration?
+- You have a static configuration that only applies to your simple single package?
 
 > [`.babelrc`](#babelrc) is for you!
 
 - The Guy Fieri is your hero?
 
-> We recommend to use the [`babel.config.js`](#babelconfigjs) format. [Babel itself is using it](https://github.com/babel/babel/blob/master/babel.config.js).
+> We recommend to use the [`babel.config.js`](config-files.md#project-wide-configuration) format. [Babel itself is using it](https://github.com/babel/babel/blob/master/babel.config.js).
 
 ## `babel.config.js`
 
@@ -38,7 +38,7 @@ module.exports = function () {
 }
 ```
 
-Checkout the [`babel.config.js` documentation](babelconfigjs.md) to see more configuration options.
+Checkout the [`babel.config.js` documentation](config-files.md#project-wide-configuration) to see more configuration options.
 
 ## `.babelrc`
 
@@ -51,7 +51,7 @@ Create a file called `.babelrc` with the following content in your project.
 }
 ```
 
-Checkout the [.babelrc documentation](babelrc.md) to see more configuration options.
+Checkout the [.babelrc documentation](config-files.md#file-relative-configuration) to see more configuration options.
 
 ### `package.json`
 
diff --git a/docs/core.md b/docs/core.md
index 1a27d404b3..65c440dcb5 100644
--- a/docs/core.md
+++ b/docs/core.md
@@ -10,7 +10,7 @@ import { transform } from "@babel/core";
 import * as babel from "@babel/core";
 ```
 
-All transformations will use your local configuration files (`.babelrc` or in `package.json`). See [options](#options) to disable it.
+All transformations will use your local [configuration files](config-files.md).
 
 
 ## transform
@@ -60,6 +60,27 @@ result.map;
 result.ast;
 ```
 
+## transformAsync
+
+> babel.transformAsync(code: string, [options?](#options): Object)
+
+Transforms the passed in `code`. Returning an promise for an object with the
+generated code, source map, and AST.
+
+```js
+babel.transformAsync(code, options) // => Promise<{ code, map, ast }>
+```
+
+**Example**
+
+```js
+babel.transformAsync("code();", options).then(result => {
+  result.code;
+  result.map;
+  result.ast;
+});
+```
+
 
 ## transformFile
 
@@ -98,6 +119,26 @@ babel.transformFileSync("filename.js", options).code;
 ```
 
 
+## transformFileAsync
+
+> babel.transformFileAsync(filename: string, [options?](#options): Object)
+
+Promise version of `babel.transformFile`. Returns a promise for the transformed
+contents of the `filename`.
+
+```js
+babel.transformFileAsync(filename, options) // => Promise<{ code, map, ast }>
+```
+
+**Example**
+
+```js
+babel.transformFileAsync("filename.js", options).then(result => {
+  result.code;
+});
+```
+
+
 ## transformFromAst
 
 > babel.transformFromAst(ast: Object, code?: string, [options?](#options): Object, callback: Function): FileNode | null
@@ -129,9 +170,54 @@ const parsedAst = babel.parse(sourceCode, { allowReturnOutsideFunction: true });
 const { code, map, ast } = babel.transformFromAstSync(parsedAst, sourceCode, options);
 ```
 
+## transformFromAstAsync
+
+> babel.transformFromAstAsync(ast: Object, code?: string, [options?](#options): Object)
+
+Given an [AST](https://astexplorer.net/), transform it.
+
+```js
+const sourceCode = "if (true) return;";
+babel.parseAsync(sourceCode, { allowReturnOutsideFunction: true })
+  .then(parsedAst => {
+    return babel.transformFromAstSync(parsedAst, sourceCode, options);
+  })
+  .then(({ code, map, ast }) => {
+    // ...
+  });
+```
+
 ## parse
 
-> babel.parse(code: string, [options?](#options): Object)
+> babel.parse(code: string, [options?](#options): Object, callback: Function)
+
+Given some code, parse it using Babel's standard behavior. Referenced presets and
+plugins will be loaded such that optional syntax plugins are automatically
+enabled.
+
+> Compat Note:
+>
+> In Babel 7's early betas, this method was synchronous and `parseSync` did not exist. For backward-compatibility,
+> this function will behave synchronously if no callback is given. If you're starting with Babel 7 stable
+> and need synchronous behavior, please use `parseSync` since this backward-compat may be dropped
+> in future major versions of Babel.
+
+
+## parseSync
+
+> babel.parseSync(code: string, [options?](#options): Object)
+
+Returns an AST.
+
+Given some code, parse it using Babel's standard behavior. Referenced presets and
+plugins will be loaded such that optional syntax plugins are automatically
+enabled.
+
+## parseAsync
+
+> babel.parseAsync(code: string, [options?](#options): Object)
+
+Returns a promise for an AST.
 
 Given some code, parse it using Babel's standard behavior. Referenced presets and
 plugins will be loaded such that optional syntax plugins are automatically
@@ -144,6 +230,7 @@ Many systems that wrap Babel like to automatically inject plugins and presets,
 or override options. To accomplish this goal, Babel exposes several functions
 that aid in loading the configuration part-way without transforming.
 
+
 ### loadOptions
 
 > babel.loadOptions([options?](#options): Object)
@@ -152,8 +239,8 @@ Resolve Babel's options fully, resulting in an options object where:
 
 * `opts.plugins` is a full list of `Plugin` instances.
 * `opts.presets` is empty and all presets are flattened into `opts`.
-* It can be safely passed back to Babel. Fields like `babelrc` have been set to
-  false so that later calls to Babel will not make a second attempt to load
+* It can be safely passed back to Babel. Fields like [`"babelrc"`](options.md#babelrc) have been set to
+  `false` so that later calls to Babel will not make a second attempt to load
   config files.
 
 `Plugin` instances aren't meant to be manipulated directly, but often
@@ -171,12 +258,13 @@ resolves the plugins and presets and proceeds no further. The expectation is
 that callers will take the config's `.options`, manipulate it as then see fit
 and pass it back to Babel again.
 
-* `babelrc: string | void` - The path of the `.babelrc` file, if there was one.
+* `babelrc: string | void` - The path of the [file-relative configuration](config-files.md#file-relative-configuration) file, if there was one.
 * `babelignore: string | void` - The path of the `.babelignore` file, if there was one.
+* `config: string | void` - The path of the [project-wide config file](config-files.md#project-wide-configuration) file, if there was one.
 * `options: ValidatedOptions` - The partially resolved options, which can be manipulated and passed back to Babel again.
   * `plugins: Array<ConfigItem>` - See below.
   * `presets: Array<ConfigItem>` - See below.
-  * It can be safely passed back to Babel. Fields like `babelrc` have been set
+  * It can be safely passed back to Babel. Options like [`"babelrc"`](options.md#babelrc) have been set
     to false so that later calls to Babel will not make a second attempt to
     load config files.
 * `hasFilesystemConfig(): boolean` - Check if the resolved config loaded any settings from the filesystem.
@@ -213,54 +301,4 @@ Each `ConfigItem` exposes all of the information Babel knows. The fields are:
 
 ## Options
 
-<blockquote class="babel-callout babel-callout-info">
-  <h4>Babel CLI</h4>
-  <p>
-    You can pass these options from the Babel CLI like so:
-  </p>
-  <p>
-    <code>babel --option-name<span class="o">=</span>value</code>
-  </p>
-</blockquote>
-
-Following is a table of the options you can use:
-
-| Option                   | Default              | Description                     |
-| ------------------------ | -------------------- | ------------------------------- |
-| `ast`                    | `false`              | Include the AST in the returned object |
-| `auxiliaryCommentAfter`  | `null`               | Attach a comment after all non-user injected code |
-| `auxiliaryCommentBefore` | `null`               | Attach a comment before all non-user injected code |
-| `root`                   | `"."`                | Specify the "root" folder that defines the location to search for "babel.config.js", and the default folder to allow `.babelrc` files inside of.|
-| `configFile`             | `undefined`          | The config file to load Babel's config from. Defaults to searching for "babel.config.js" inside the "root" folder. `false` will disable searching for config files.|
-| `babelrc`                | `true`               | Specify whether or not to use .babelrc and .babelignore files. Not available when using the CLI, [use `--no-babelrc` instead](https://babeljs.io/docs/usage/cli/#babel-ignoring-babelrc) |
-| `babelrcRoots`           | `(root)`             | Specify which packages should be search for .babelrc files when they are being compiled. `true` to _always_ search, or a path string or an array of paths to packages to search inside of. Defaults to only searching the "root" package. |
-| `envName`                | env vars             | Defaults to environment variable `BABEL_ENV` if set, or else `NODE_ENV` if set, or else it defaults to `"development"` |
-| `code`                   | `true`               | Enable code generation |
-| `comments`               | `true`               | Output comments in generated output |
-| `compact`                | `"auto"`             | Do not include superfluous whitespace characters and line terminators. When set to `"auto"` compact is set to `true` on input sizes of >500KB |
-| `cwd`                    | `.`                  | The working directory that Babel's programmatic options are loaded relative to. |
-| `env`                    | `{}`                 | This is an object of keys that represent different environments. For example, you may have: `{ env: { production: { /* specific options */ } } }` which will use those options when the `envName` is `production` |
-| `extends`                | `null`               | A path to a `.babelrc` file to extend |
-| `filename`               | `"unknown"`          | Filename for use in errors, babel config lookup, etc |
-| `filenameRelative`       | `(filename)`         | Filename relative to `sourceRoot` |
-| `generatorOpts`          | `{}`                 | An object containing the options to be passed down to the babel code generator, @babel/generator |
-| `getModuleId`            | `null`               | Specify a custom callback to generate a module id with. Called as `getModuleId(moduleName)`. If falsy value is returned then the generated module id is used |
-| `highlightCode`          | `true`               | ANSI highlight syntax error code frames |
-| `ignore`                 | `null`               | Opposite to the `only` option. `ignore` is disregarded if `only` is specified |
-| `inputSourceMap`         | `null`               | A source map object that the output source map will be based on |
-| `minified`               | `false`              | Should the output be minified (not printing last semicolons in blocks, printing literal string values instead of escaped ones, stripping `()` from `new` when safe) |
-| `moduleId`               | `null`               | Specify a custom name for module ids |
-| `moduleIds`              | `false`              | If truthy, insert an explicit id for modules. By default, all modules are anonymous. (Not available for `common` modules) |
-| `moduleRoot`             | `(sourceRoot)`       | Optional prefix for the AMD module formatter that will be prepend to the filename on module definitions |
-| `only`                   | `null`               | A [glob](https://github.com/isaacs/minimatch), regex, or mixed array of both, matching paths to **only** compile. Can also be an array of arrays containing paths to explicitly match. When attempting to compile a non-matching file it's returned verbatim |
-| `parserOpts`             | `{}`                 | An object containing the options to be passed down to the babel parser, @babel/parser |
-| `plugins`                | `[]`                 | List of [plugins](https://babeljs.io/docs/plugins/) to load and use |
-| `presets`                | `[]`                 | List of [presets](https://babeljs.io/docs/plugins/#presets) (a set of plugins) to load and use |
-| `retainLines`            | `false`              | Retain line numbers. This will lead to wacky code but is handy for scenarios where you can't use source maps. (**NOTE:** This will not retain the columns) |
-| `shouldPrintComment`     | `null`               | An optional callback that controls whether a comment should be output or not. Called as `shouldPrintComment(commentContents)`. **NOTE:** This overrides the `comment` option when used |
-| `sourceFileName`         | `(filenameRelative)` | Set `sources[0]` on returned source map |
-| `sourceMaps`             | `false`              | If truthy, adds a `map` property to returned output. If set to `"inline"`, a comment with a sourceMappingURL directive is added to the bottom of the returned code. If set to `"both"` then a `map` property is returned as well as a source map comment appended. **This does not emit sourcemap files by itself!** To have sourcemaps emitted using the CLI, you must pass it the `--source-maps` option |
-| `sourceRoot`             | `(moduleRoot)`       | The root from which all sources are relative |
-| `sourceType`             | `"module"`           | Indicate the mode the code should be parsed in. Can be one of "script", "module", or "unambiguous". `"unambiguous"` will make Babel attempt to _guess_, based on the presence of ES6 `import` or `export` statements. Files with ES6 `import`s and `export`s are considered `"module"` and are otherwise `"script"`. |
-| `wrapPluginVisitorMethod`| `null`               | An optional callback that can be used to wrap visitor methods. **NOTE:** This is useful for things like introspection, and not really needed for implementing anything. Called as `wrapPluginVisitorMethod(pluginAlias, visitorType, callback)`.
-
+See [the full option list here](options.md).
diff --git a/docs/env.md b/docs/env.md
index 0cfa537a49..ffcfe93cc2 100644
--- a/docs/env.md
+++ b/docs/env.md
@@ -18,7 +18,7 @@ You might end up on this page because you saw a message in the terminal like thi
 
 Before you proceed further, ask yourself: are you *using* Babel? Check your `package.json` and look for `babel-preset-es2015` or a similar preset there. If you see a preset like this in your `package.json`, read on!
 
-If you don't use Babel or don't use deprecated yearly presets, you probably saw this message because *another package* you depend on uses them. **In that case there's nothing *you* need to do**. Nevertheless, it might be a good idea to find out which package uses the deprecated presets, and help them migrate by sending a pull request. You can find this out by running `npm ls babel-preset-es2015` which will show the dependency tree. 
+If you don't use Babel or don't use deprecated yearly presets, you probably saw this message because *another package* you depend on uses them. **In that case there's nothing *you* need to do**. Nevertheless, it might be a good idea to find out which package uses the deprecated presets, and help them migrate by sending a pull request. You can find this out by running `npm ls babel-preset-es2015` which will show the dependency tree.
 
 ## Upgrading to `babel-preset-env`
 
@@ -27,7 +27,7 @@ If you don't use Babel or don't use deprecated yearly presets, you probably saw
 ```sh
 npm install babel-preset-env --save-dev
 ```
-#### Basic `.babelrc` change
+#### Basic [options](options.md) change
 
 ```diff
 {
@@ -36,7 +36,7 @@ npm install babel-preset-env --save-dev
 }
 ```
 
-#### `.babelrc` change with options
+#### [options](options.md) change with preset options
 
 ```diff
 {
@@ -58,7 +58,7 @@ npm install babel-preset-env --save-dev
 
 ## By targeting specific browsers, Babel can do less work so you can ship native ES2015+ 😎!
 
-#### `.babelrc` against a specific chrome version
+#### [options](options.md) against a specific chrome version
 
 ```json
 {
@@ -72,7 +72,7 @@ npm install babel-preset-env --save-dev
 }
 ```
 
-#### `.babelrc` against current node version
+#### [options](options.md) against current node version
 
 ```json
 {
diff --git a/docs/faq.md b/docs/faq.md
index 0e0a354561..d683a3cc3a 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -56,7 +56,7 @@ We hear you! Babel 6 requires a tiny bit of configuration in order to get going.
 ## Upgrading from Babel 5.x to Babel 6
 
 At the heart of Babel 6 are [plugins](plugins.md). What plugins you need completely
-depends on your specific configuration but just add the following `.babelrc` file to
+depends on your specific configuration but just add the following [config file](config-files.md) to
 get all the same transforms that were in Babel 5:
 
 ```json
diff --git a/docs/options.md b/docs/options.md
new file mode 100644
index 0000000000..73fb3d4f39
--- /dev/null
+++ b/docs/options.md
@@ -0,0 +1,766 @@
+---
+title: Options
+id: options
+---
+
+- [Primary options](#primary-options)
+- [Config Loading options](#config-loading-options)
+- [Plugin and Preset configuration](#plugin-and-preset-options)
+- [Config Merging options](#config-merging-options)
+- [Source Map options](#source-map-options)
+- [Misc options](#misc-options)
+- [Code Generator options](#code-generator-options)
+- [AMD / UMD / SystemJS options](#amd-umd-systemjs-module-options)
+- [Option concepts](#options-concepts)
+
+Options can be passed be passed to Babel in a variety of ways. When directly to Babel,
+you can just pass the objects object. When Babel is used via a wrapper, it may also be
+necessary, or at least more useful, to pass the options via [configuration files](config-files.md).
+
+## Primary options
+
+These options are only allowed as part of Babel's programmatic options, so
+they are primarily for use by tools that wrap around Babel, or people calling
+`babel.transform` directly. Users of Babel's integrations, like `babel-loader`
+or [`@babel/register`](core.md#options) are unlikely to use these.
+
+
+### `cwd`
+
+Type: `string`<br />
+Default: `process.cwd()`<br />
+
+The working directory that all paths in the programmatic options will be resolved
+relative to.
+
+
+### `caller`
+
+Type: `Object` with a string-typed `"name"` property.<br />
+
+Utilities may pass a `caller` object to identify themselves to Babel and pass
+capability-related flags for use by configs, presets and plugins. For example
+```js
+babel.transformFileSync("example.js", {
+  caller: {
+    name: "my-custom-tool",
+    supportsStaticESM: true
+  },
+})
+```
+would allow plugins and presets to decide that, since ES modules are supported,
+they will skip compilation of ES modules into CommonJS modules.
+
+
+### `filename`
+
+Type: `string`<br />
+
+The filename associated with the code currently being compiled, if there is one.
+The filename is optional, but not all Babel functionality is available when
+the filename is unknown, because a subset of options rely on the filename
+for their functionality.
+
+The three primary cases users could run into are:
+
+* The filename is exposed to plugins. Some plugins may require the presence of the filename.
+* Options like [`"test"`](#test), [`"exclude"`](#exclude), and [`"ignore"`](#ignore) require the filename for string/RegExp matching.
+* `.babelrc` files are loaded relative to the file being compiled. If this option is omited, Babel will behave as if `babelrc: false` has been set.
+
+
+### `filenameRelative`
+
+Type: `string`<br />
+Default: `path.relative(opts.cwd, opts.filename)` (if [`"filename"`](#filename) was passed)<br />
+
+Used as the default value for Babel's `sourceFileName` option, and used
+as part of generation of filenames for the AMD / UMD / SystemJS module transforms.
+
+
+### `code`
+
+Type: `boolean`<br />
+Default: `true`<br />
+
+Babel's default return value includes `code` and `map` properties with the
+resulting generated code. In some contexts where multiple calls to Babel
+are being made, it can be helpful to disable code generation and instead
+use `ast: true` to get the AST directly in order to avoid doing unnecessary work.
+
+
+### `ast`
+
+Type: `boolean`<br />
+Default: `false`<br />
+
+Babel's default is to generate a string and a sourcemap, but in some
+contexts it can be useful to get the AST itself. The primary usecase for this
+would be a chain of multiple transform passes, along the lines of
+
+```js
+const filename = "example.js";
+const code = fs.readFileSync(filename, "utf8");
+
+// Load and compile file normally, but skip code generation.
+const { ast } = babel.transformSync(code, { filename, ast: true, code: false });
+
+// Minify the file in a second pass and generate the output code here.
+const { code, map } = babel.transformFromAstSync(ast, code, {
+  filename,
+  presets: ["minify"],
+  babelrc: false,
+  configFile: false,
+});
+```
+
+Note: This option is not on by default because the majority of user won't need
+it and because we'd like to eventually add a caching layer to Babel. Having
+to cache the AST structure will take significantly more space.
+
+
+## Config Loading options
+
+Loading configuration can get a little complex as environments can have several
+types of configuration files, and those configuration files can have various
+nested configuration objects that apply depending on the configuration.
+
+
+### `root`
+
+Type: `string`<br />
+Default: `opts.cwd`<br />
+Placement: Only allowed in Babel's programmatic options<br />
+
+The path of the conceptual root package for the current Babel project.
+This is used in two primary cases:
+
+* The base directory when checking for the default [`"configFile"`](#configFile) value
+* The default value for [`"babelrcRoots"`](#babelrcRoots).
+
+
+### `envName`
+
+Type: `string`<br />
+Default: `process.env.BABEL_ENV || process.env.NODE_ENV || "development"`<br />
+Placement: Only allowed in Babel's programmatic options<br />
+
+The current active environment used during configuration loading. This value
+is used as the key when resolving [`"env"`](#env) configs, and is also
+available inside configuration functions, plugins, and presets, via the
+[`api.env()`](config-files.md#apienv) function.
+
+
+### `configFile`
+
+Type: `string | boolean`<br />
+Default: `path.resolve(opts.root, "babel.config.js")`, if it exists, `false` otherwise<br />
+Placement: Only allowed in Babel's programmatic options<br />
+
+Defaults to searching for a default `babel.config.js` file, but can be passed
+the path of any JS or JSON5 config file.
+
+NOTE: This option does _not_ affect loading of [`.babelrc`](config-files.md#file-relative-configuration) files, so while
+it may be tempting to do `configFile: "./foo/.babelrc"`, it is not recommended.
+If the given [`.babelrc`](config-files.md#file-relative-configuration) is loaded via the standard
+file-relative logic, you'll end up loading the same config file twice, merging it with itself.
+If you are linking a specific config file, it is recommended to stick with a
+naming scheme that is independent of the "babelrc" name.
+
+
+### `babelrc`
+
+Type: `boolean`<br />
+Default: `true` as long as the `filename` option has been specificed<br />
+Placement: Allowed in Babel's programmatic options, or inside of the loaded [`"configFile"`](#configfile). A programmatic option will override a config file one.<br />
+
+`true` will enable searching for [configuration files](config-files.md#file-relative-configuration) relative
+to the [`"filename"`](#filename) provided to Babel.
+
+A `babelrc` value passed in the programmatic options will override one set
+within a configuration file.
+
+Note: `.babelrc` files are only loaded if the current [`"filename"`](#filename) is inside of
+a package that matches one of the [`"babelrcRoots"`](#babelrcroots) packages.
+
+
+### `babelrcRoots`
+
+Type: `boolean | MatchPattern | Array<MatchPattern>`<br />
+Default: `opts.root`<br />
+Placement: Allowed in Babel's programmatic options, or inside of the loaded `configFile`. A programmatic option will override a config file one.<br />
+
+By default, Babel will only search for `.babelrc` files within the [`"root"`](#root) package
+because otherwise Babel cannot know if a given `.babelrc` is meant to be loaded, or
+if it's [`"plugins"`](#plugins) and [`"presets"`](#presets) have even been installed, since the file being
+compiled could be inside `node_modules`, or have been symlinked into the project.
+
+This option allows users to provide a list of other packages that should be considered
+"root" packages when considering whether to load `.babelrc` files.
+
+For example, a monorepo setup that wishes to allow individual packages to
+have their own configs might with to do
+
+```js
+babelrcRoots: [
+  // Keep the root as a root
+  ".",
+
+  // Also consider monorepo packages "root" and load their .babelrc files.
+  "./packages/*"
+]
+```
+
+## Plugin and Preset options
+
+### `plugins`
+
+Type: `Array<PluginEntry | Plugin>` ([`PluginEntry`](#plugin-preset-entries))<br />
+Default: `[]`<br />
+
+An array of plugins to activate when processing this file. For more information on how
+individual entries interact, especially when used across multiple nested [`"env"`](#env) and
+[`"overrides"`](#overrides) configs, see [merging](#merging).
+
+Note: The option also allows `Plugin` instances from Babel itself, but
+using these directly is not recommended. If you need to create a persistent
+representation of a plugin or preset, you should use [`babel.createConfigItem()`](core.md#createconfigitem).
+
+
+### `presets`
+
+Type: `Array<PresetEntry>` ([`PresetEntry`](#plugin-preset-entries))<br />
+Default: `[]`<br />
+
+An array of presets to activate when processing this file. For more information on how
+individual entries interact, especially when used across multiple nested [`"env"`](#env) and
+[`"overrides"`](#overrides) configs, see [merging](#merging).
+
+Note: The format of presets is identical to plugins, except for the fact that
+name normalization expects "preset-" instead of "plugin-", and presets cannot
+be instances of `Plugin`.
+
+
+### `passPerPreset`
+
+Type: `boolean`<br />
+Default: `false`<br />
+Status: *Deprecated*<br />
+
+Instructs Babel to run each of the presets in the `presets` array as an
+independent pass. This option tends to introduce a lot of confusion around
+the exact ordering of plugins, but can be useful if you absolutely need to run
+a set of operations as independent compilation passes.
+
+Note: This option may be removed in future Babel versions as we add better
+support for defining ordering between plugins.
+
+
+## Config Merging options
+
+### `extends`
+
+Type: `string`<br />
+Placement: Not allowed inside of presets<br />
+
+Configs may "extend" other configuration files. Config fields in the current
+config will be [merged](#merging) on top of the extended file's configuration.
+
+
+### `env`
+
+Type: `{ [envKey: string]: Options }`<br />
+Placement: May not be nested inside of another `env` block.<br />
+
+Allows for entire nested configuration options that will only be enabled
+if the `envKey` matches the `envName` option.
+
+Note: `env[envKey]` options will be [merged](#merging) on top of the options specified in
+the root object.
+
+
+### `overrides`
+
+Type: `Array<Options>`<br />
+Placement: May not be nested inside of another `overrides` object, or within an `env` block.<br />
+
+Allows users to provide an array of options that will be [merged](#merging) into the current
+configuration one at a time. This feature is best used alongside the [`"test"`](#test)/[`"include"`](#include)/[`"exclude"`](#exclude)
+options to provide conditions for which an override should apply. For example:
+```js
+overrides: [{
+  test: "./vendor/large.min.js",
+  compact: true,
+}],
+```
+could be used to enable the `compact` option for one specific file that is known
+to be large and minified, to tell Babel not to bother trying to print the file nicely.
+
+
+### `test`
+
+Type: `MatchPattern | Array<MatchPattern>` ([`MatchPattern`](#matchpattern))<br />
+
+If all of patterns fail to match, the current configuration object is considered
+inactive and is ignored during config processing. This option is most useful
+when used within an `overrides` option object, but it's allowed anywhere.
+
+Note: These toggles do not affect the programmatic and config-loading options
+in earlier sections, since they are taken into account long before the
+configuration that is prepared for merging.
+
+
+### `include`
+
+Type: `MatchPattern | Array<MatchPattern>` ([`MatchPattern`](#matchpattern))<br />
+
+This option is a synonym for [`"test"`](#test).
+
+
+### `exclude`
+
+Type: `MatchPattern | Array<MatchPattern>` ([`MatchPattern`](#matchpattern))<br />
+
+If any of patterns match, the current configuration object is considered
+inactive and is ignored during config processing. This option is most useful
+when used within an `overrides` option object, but it's allowed anywhere.
+
+Note: These toggles do not affect the programmatic and config-loading options
+in earlier sections, since they are taken into account long before the
+configuration that is prepared for merging.
+
+
+### `ignore`
+
+Type: `Array<MatchPattern>` ([`MatchPattern`](#matchpattern))<br />
+Placement: Not allowed inside of presets<br />
+
+If any of the patterns match, Babel will immediately stop all processing of
+the current build. For example, a user may want to do something like
+
+```js
+ignore: [
+  "./lib",
+]
+```
+to explicitly disable Babel compilation of files inside the `lib` directory.
+
+Note: This option disables _all_ Babel processing of a file. While that has
+its uses, it is also worth considering the [`"exclude"`](#exclude) option as a less aggressive
+alternative.
+
+
+### `only`
+
+Type: `Array<MatchPattern>` ([`MatchPattern`](#matchpattern))<br />
+Placement: Not allowed inside of presets<br />
+
+If all of the patterns fail to match, Babel will immediately stop all processing
+of the current build. For example, a user may want to do something like
+
+```js
+only: [
+  "./src",
+]
+```
+to explicitly enable Babel compilation of files inside the `src` directory
+while disabling everything else.
+
+Note: This option disables _all_ Babel processing of a file. While that has
+its uses, it is also worth considering the [`"test"`](#test)/[`"include"`](#include)
+options as a less aggressive alternative.
+
+
+## Source Map options
+
+### `inputSourceMap`
+
+Type: `boolean | SourceMap`<br />
+Default: `true`<br />
+
+`true` will attempt to load an input sourcemap from the file itself, if it
+contains a `//# sourceMappingURL=...` commment. If no map is found, or the
+map fails to load and parse, it will be silently discarded.
+
+If an object is provided, it will be treated as the source map object itself.
+
+
+### `sourceMaps`
+
+Type: `boolean | "inline" | "both"`<br />
+Default: `false`<br />
+
+* `true` to generate a sourcemap for the code and include it in the result object.
+* `"inline"` to generate a sourcemap and append it as a data URL to the end of the code, but not include it in the result object.
+* `"both"` is the same as inline, but will include the map in the result object.
+
+`@babel/cli` overloads some of these to also affect how maps are written to disk:
+
+* `true` will write the map to a `.map` file on disk
+* `"inline"` will write the file directly, so it will have a `data:` containing the map
+* `"both"` will write the file with a `data:` URL and _also_ a `.map`.
+
+Note: These options are bit weird, so it may make the most sense to just use
+`true` and handle the rest in your own code, depending on your usecase.
+
+
+### `sourceMap`
+
+This is an synonym for `sourceMaps`. Using `sourceMaps` is recommended.
+
+
+### `sourceFileName`
+
+Type: `string`<br />
+Default: `opts.filenameRelative` when available, or `"unknown"`<br />
+
+The name to use for the file inside the source map object.
+
+
+### `sourceRoot`
+
+Type: `string`<br />
+
+The `sourceRoot` fields to set in the generated source map, if one is desired.
+
+
+## Misc options
+
+### `sourceType`
+
+Type: `"script" | "module" | "unambiguous"`<br />
+Default: "module"<br />
+
+* "script" - Parse the file using the ECMAScript Script grammar. No `import`/`export` statements allowed, and files are not in strict mode.
+* "module" - Parse the file using the ECMAScript Module grammar. Files are automatically strict, and `import`/`export` statements are allowed.
+* "unambiguous" - Consider the file a "module" if `import`/`export` statements are present, or else consider it a "script".
+
+`unambiguous` can be quite useful in contexts where the type is unknow, but it can lead to
+false matches because it's perfectly valid to have a module file that does not use `import`/`export`
+statements.
+
+Note: This option will not affect parsing of `.mjs` files, as they are currently
+hard-coded to always parse as `"module"` files.
+
+
+### `highlightCode`
+
+Type: `boolean`<br />
+Default: `true`<br />
+
+Highlight tokens in code snippets in Babel's error messages to make them easier to read.
+
+
+### `wrapPluginVisitorMethod`
+
+Type: `(key: string, nodeType: string, fn: Function) => Function`<br />
+
+Allows users to add a wrapper on each visitor in order to inspect the visitor
+process as Babel executes the plugins.
+
+* `key` is a simple opaque string that represents the plugin being executed.
+* `nodeType` is the type of AST node currently being visited.
+* `fn` is the visitor function itself.
+
+Users can return a replacement function that should call the original function
+after performing whatever logging and analysis they wish to do.
+
+
+### `parserOpts`
+
+Type: `{}`<br />
+
+An opaque object containing options to pass though to the parser being used.
+
+
+### `generatorOpts`
+
+Type: `{}`<br />
+
+An opaque object containing options to pass though to the code generator being used.
+
+
+## Code Generator options
+
+### `retainLines`
+
+Type: `boolean`<br />
+Default: `false`<br />
+
+Babel will make an effort to generator code such that items are printed on the
+same line that they were on in the original file. This option exists so that
+users who cannot use source maps can get vaguely useful error line numbers,
+but it is only a best-effort, and is not guaranteed in all cases with all plugins.
+
+
+### `compact`
+
+Type: `boolean | "auto"`<br />
+Default: `"auto"`<br />
+
+"auto" will set the value by evaluating `code.length > 500_000`
+
+All optional newlines and whitespace will be omitted when generating code in
+compact mode.
+
+
+### `minified`
+
+Type: `boolean`<br />
+Default: `false`<br />
+
+Includes `compact: true`, omits block-end semicolons, omits `()` from
+`new Foo()` when possible, and may output shorter versions of literals.
+
+
+### `auxiliaryCommentBefore`
+
+Type: `string`<br />
+
+Allows specifying a prefix comment to insert before pieces of code that were
+not present in the original file.
+
+Note: The definition of what is and isn't present in the original file can
+get a little ugly, so usage of this option is not recommended. If you need to
+annotate code somehow, it is better to do so using a Babel plugin.
+
+
+### `auxiliaryCommentAfter`
+
+Type: `string`<br />
+
+Allows specifying a prefix comment to insert after pieces of code that were
+not present in the original file.
+
+Note: The definition of what is and isn't present in the original file can
+get a little ugly, so usage of this option is not recommended. If you need to
+annotate code somehow, it is better to do so using a Babel plugin.
+
+
+### `comments`
+
+Type: `boolean`<br />
+Default: `true`<br />
+
+Provides a default comment state for `shouldPrintComment` if no function
+is given. See the default value of that option for more info.
+
+
+### `shouldPrintComment`
+
+Type: `(value: string) => boolean`<br />
+Default without `minified`: `(val) => opts.comments || /@license|@preserve/.test(val)`<br />
+Default with `minified`: `() => opts.comments`<br />
+
+A function that can decide whether a given comment should be included in the
+output code from Babel.
+
+
+## AMD / UMD / SystemJS module options
+
+### `moduleIds`
+
+Type: `boolean`<br />
+Default: `!!opts.moduleId`<br />
+
+Enables module ID generation.
+
+
+### `moduleId`
+
+Type: `string`<br />
+
+A hard-coded ID to use for the module. Cannot be used alongside `getModuleId`.
+
+
+### `getModuleId`
+
+Type: `(name: string) => string`<br />
+
+Given the babel-generated module name, return the name to use. Returning
+a falcy value will use the original `name`.
+
+
+### `moduleRoot`
+
+Type: `string`<br />
+
+A root path to include on generated module names.
+
+
+## Options Concepts
+
+### `MatchPattern`
+
+Type: `string | RegExp | (filename: string | void, context: { callee: { name: string } | void, envName: string ) => boolean`
+
+Several Babel options perform tests against filepaths. In general, these
+options support a common patter approach where each pattern can be
+
+* `string` - A file path with simple support for `*` and `**` as full slug matches. Any file or
+  parent folder matching the pattern counts as a match. The path follow's Node's normal path logic,
+  so on POSIX is must be `/`-separated, but on Windows both `/` and `\` are supported.
+* `RegExp` - A regular expression to match against the normalized filename. On POSIX the path
+  RegExp will run against a `/`-separated path, and on Windows it will be on a `\`-separated path.
+
+Importantly, if either of these are used, Babel requires that the `filename` option be present,
+and will consider it an error otherwise.
+
+* `(filename: string | void, context: { callee: { name: string } | void, envName: string }) => boolean` is a general callback that should
+  return a boolean to indicate whether it is a match or not. The function is passed the filename
+  or `undefined` if one was not given to Babel. It is also passed the current `envName` and `callee`
+  options that were specified by the top-level call to Babel.
+
+
+### Merging
+
+Babel's configuration merging is relatively straightforward. Options will overwrite existing options
+when they are present and their value is not `undefined`, with a few special cases:
+
+* `parserOpts` objects are merged, rather than replaced, using the same logic as top-level options.
+* `generatorOpts` objects are merged, rather than replaced, using the same logic as top-level options.
+* `plugins` and `presets` are replaced based on the identity of the plugin/preset object/function itself combined with the name of the entry.
+
+#### Plugin/Preset merging
+
+As an example, consider a config with:
+```js
+plugins: [
+  './other',
+  ['./plug', { thing: true, field1: true }]
+],
+overrides: [{
+  plugins: [
+    ['./plug', { thing: false, field2: true }],
+  ]
+}]
+```
+The `overrides` item will be merged on top of the top-level plugins. Importantly, the `plugins`
+array as a whole doesn't just replace the top-level one. The merging logic will see thay `"./plug"`
+is the same plugin in both cases, and `{ thing: false, field2: true }` will replace the original
+options, resulting in a config as
+
+```js
+plugins: [
+  './other',
+  ['./plug', { thing: false, field2: true }],
+],
+```
+
+Since merging is based on identity + name, it is considered an error to use the same plugin with
+the same name twice in the same `plugins`/`presets` array. For example
+```js
+plugins: [
+  './plug',
+  './plug',
+]
+```
+is considered an error, because it's identical to `plugins: ['./plug']`. Additionally, even
+
+```js
+plugins: [
+  ['./plug', {one: true}],
+  ['./plug', {two: true}]
+]
+```
+is considered an error, because the second one would just always replace the first one.
+
+If you actually _do_ want to instantiate two separate instances of a plugin, you must assign each one
+a name to disambiguate them. For example:
+
+```js
+plugins: [
+  ['./plug', {one: true}, "first-instance-name"],
+  ['./plug', {two: true}, "second-instance-name"]
+]
+```
+because each instance has been given a unique name and this a unique identity.
+
+
+### Plugin/Preset entries
+
+#### `PluginEntry` / `PresetEntry`
+
+Individual plugin/preset items can have several different structures:
+
+* `EntryTarget` - Individual plugin
+* `[EntryTarget, EntryOptions]` - Individual plugin w/ options
+* `[EntryTarget, EntryOptions, string]` - Individual plugin with options and name
+* `ConfigItem` - A plugin configuration item created by `babel.createConfigItem()`.
+
+The same `EntryTarget` may be used multiple times unless each one is given a different
+name, and doing so will result in a duplicate-plugin/preset error.
+
+
+#### `EntryTarget`
+
+Type: `string | {} | Function`<br />
+
+A plugin/preset target can come from a few different sources:
+
+* `string` - A `require`-style path or plugin/preset identifier. Identifiers will be passed through [name normalization](#name-normalization).
+* `{} | Function` - An actual plugin/preset object or function after it has been `require()`ed.
+
+
+#### `EntryOptions`
+
+Type: `undefined | {} | false`
+
+Options are passed through to each plugin/preset when they are executed. `undefined` will be
+normalized to an empty object.
+
+`false` indicates that an entry is entirely disabled. This can be useful in contexts where ordering
+is important, but a separate condition is needed to decide if something is enabled. For instace:
+
+```js
+plugins: [
+  'one',
+  ['two', false],
+  'three',
+],
+overrides: [{
+  test: "./src",
+  plugins: [
+    'two',
+  ]
+}]
+```
+would enable the `two` plugin for files in `src`, but `two` would still execute between `one` and `three`.
+
+
+### Name Normalization
+
+By default, Babel expects plugins to have a `babel-plugin-` or `babel-preset-` prefix in their name.
+To avoid repetition, Babel has a name normalization phase will automatically add these prefixes
+when loading items. This boils down to a few primary rules:
+
+* Absolute paths pass through untouched.
+* Relative paths starting with `./` pass through untouched.
+* References to files _within_ a package are untouched.
+* Any identifier prefixed with `module:` will have the prefix removed but otherwise be untouched.
+* `plugin-`/`preset-` will be injected at the start of any `@babel`-scoped package that doesn't have it as a prefix.
+* `babel-plugin-`/`babel-preset-` will be injected as a prefix any unscoped package that doesn't have it as a prefix.
+* `babel-plugin-`/`babel-preset-` will be injected as a prefix any `@`-scoped package that doesn't have it _anywhere_ in their name.
+* `babel-plugin`/`babel-preset` will be injected as the package name if only the `@`-scope name is given.
+
+Here are some example, when applied in a plugin context:
+
+| Input | Normalized |
+| -------- | --- |
+| `"/dir/plugin.js"` | `"/dir/plugin.js"`
+| `"./dir/plugin.js"` | `"./dir/plugin.js"`
+| `"mod"` | `"babel-plugin-mod"` |
+| `"mod/plugin"` | `"mod/plugin"`
+| `"babel-plugin-mod"` | `"babel-plugin-mod"` |
+| `"@babel/mod"` | `"@babel/plugin-mod"` |
+| `"@babel/plugin-mod"` | `"@babel/plugin-mod"` |
+| `"@babel/mod/plugin"` | `"@babel/mod/plugin"`
+| `"@scope"` | `"@scope/babel-plugin"` |
+| `"@scope/babel-plugin"` | `"@scope/babel-plugin"` |
+| `"@scope/mod"` | `"@scope/babel-plugin-mod"` |
+| `"@scope/babel-plugin-mod"` | `"@scope/babel-plugin-mod"` |
+| `"@scope/prefix-babel-plugin-mod"` | `"@scope/prefix-babel-plugin-mod"` |
+| `"@scope/mod/plugin"` | `"@scope/mod/plugin"`
+| `"module:foo"` | `"foo"` |
+
+
+
diff --git a/docs/parser.md b/docs/parser.md
index 7b040ebcb6..e07be36718 100644
--- a/docs/parser.md
+++ b/docs/parser.md
@@ -200,13 +200,16 @@ We currently aren't willing to commit to supporting the API for plugins or the r
 
 Our current recommendation for those that want to create their own custom syntax is for users to fork the parser.
 
-To consume your custom parser, you can add to your `.babelrc` via its npm package name or require it if using JavaScript,
+To consume your custom parser, you can add a plugin to your [options](options.md#plugins) to call the parser via its npm package name or require it if using JavaScript,
 
-```json
-{
-  "parserOpts": {
-    "parser": "custom-fork-of-babel-parser-on-npm-here"
-  }
+```js
+const parse = require("custom-fork-of-babel-parser-on-npm-here");
+
+module.exports = {
+  plugins: [{
+    parserOverride(code, opts) {
+      return parse(code, opts);
+    },
+  }]
 }
 ```
-
diff --git a/docs/preset-env.md b/docs/preset-env.md
index 617337c91c..2cb7e13806 100644
--- a/docs/preset-env.md
+++ b/docs/preset-env.md
@@ -43,7 +43,7 @@ By default `@babel/preset-env` will use [browserslist config sources](https://gi
 
 For example, to only include polyfills and code transforms needed for users whose browsers have >0.25% market share (ignoring browsers without security updates like IE 10 and BlackBerry):
 
-**.babelrc**
+[Options](options.md#presets)
 
 ```json
 {
@@ -211,7 +211,7 @@ This option is useful if there is a bug in a native implementation, or a combina
 
 For example, Node 4 supports native classes but not spread. If `super` is used with a spread argument, then the `@babel/plugin-transform-classes` transform needs to be `include`d, as it is not possible to transpile a spread with `super` otherwise.
 
-> NOTE: The `include` and `exclude` options _only_ work with the [plugins included with this preset](https://github.com/babel/babel/blob/master/packages/babel-preset-env/data/plugin-features.js); so, for example, including `@babel/plugin-proposal-do-expressions` or excluding `@babel/plugin-proposal-function-bind` will throw errors. To use a plugin _not_ included with this preset, add them to your [config](https://babeljs.io/docs/usage/babelrc/) directly.
+> NOTE: The `include` and `exclude` options _only_ work with the [plugins included with this preset](https://github.com/babel/babel/blob/master/packages/babel-preset-env/data/plugin-features.js); so, for example, including `@babel/plugin-proposal-do-expressions` or excluding `@babel/plugin-proposal-function-bind` will throw errors. To use a plugin _not_ included with this preset, add them to your ["plugins"](options.md#plugins) directly.
 
 ### `exclude`
 
@@ -307,24 +307,26 @@ Don't add polyfills automatically per file, or transform `import "@babel/polyfil
 <p><details>
   <summary><b>Example</b></summary>
 
-With Babel 7's .babelrc.js support, you can force all transforms to be run if env is set to `production`.
+With Babel 7's [Javascipt config file](config-files#javascript) support, you can force all transforms to be run if env is set to `production`.
 
 ```js
-module.exports = {
-  presets: [
-    [
-      "@babel/preset-env",
-      {
-        targets: {
-          chrome: 59,
-          edge: 13,
-          firefox: 50,
+module.exports = function(api) {
+  return {
+    presets: [
+      [
+        "@babel/preset-env",
+        {
+          targets: {
+            chrome: 59,
+            edge: 13,
+            firefox: 50,
+          },
+          // for uglifyjs...
+          forceAllTransforms: api.env("production"),
         },
-        // for uglifyjs...
-        forceAllTransforms: process.env === "production",
-      },
+      ],
     ],
-  ],
+  };
 };
 ```
 
diff --git a/docs/preset-react.md b/docs/preset-react.md
index c6a7ebb74a..8c176b3915 100644
--- a/docs/preset-react.md
+++ b/docs/preset-react.md
@@ -93,7 +93,7 @@ Will use the native built-in instead of trying to polyfill behavior for any plug
 
 Toggles plugins that aid in development, such as [`@babel/plugin-transform-react-jsx-self`](https://babeljs.io/docs/plugins/transform-react-jsx-self/) and [`@babel/plugin-transform-react-jsx-source`](https://babeljs.io/docs/plugins/transform-react-jsx-source/).
 
-This is useful when combined with either a `babelrc.js` or [env option in a .babelrc](https://babeljs.io/docs/usage/babelrc/#env-option) configuration:
+This is useful when combined with the [env option](options.md#env) configuration or [js config files](config-files.md#javascript).
 
 ### `throwIfNamespace`
 
diff --git a/docs/presets.md b/docs/presets.md
index e62a28e09c..6a840c5ac8 100644
--- a/docs/presets.md
+++ b/docs/presets.md
@@ -3,7 +3,7 @@ id: presets
 title: Presets
 ---
 
-Don't want to assemble your own set of plugins? No problem! Presets can act as an array of Babel plugins or even a sharable [`.babelrc`](babelrc.md) config.
+Don't want to assemble your own set of plugins? No problem! Presets can act as an array of Babel plugins or even a sharable [`options`](options.md) config.
 
 ## Official Presets
 
@@ -79,7 +79,7 @@ For more info, check out the [babel handbook](https://github.com/thejameskyle/ba
 If the preset is on npm, you can pass in the name of the preset and babel will check that it's installed in `node_modules`
 
 ```json
-{ 
+{
   "presets": ["babel-preset-myPreset"]
 }
 ```
@@ -161,4 +161,4 @@ To specify an option, pass an object with the keys as the option names.
     }]
   ]
 }
-```
\ No newline at end of file
+```
diff --git a/docs/register.md b/docs/register.md
index 2118be2caa..b2787593fd 100644
--- a/docs/register.md
+++ b/docs/register.md
@@ -74,9 +74,10 @@ require("@babel/register")({
 });
 ```
 
-You can pass in all other [options](https://babeljs.io/docs/usage/api/#options) as well,
-including `plugins` and `presets`. But note that the closest [`.babelrc`](https://babeljs.io/docs/usage/babelrc/)
-to each file still applies, and takes precedence over any options you pass in here.
+You can pass in all other [options](options.md) as well, including `plugins` and `presets`.
+Note that [config files](config-files.md) will also be loaded and the programmatic
+config will be merged over top of the file config options.
+
 
 ## Environment variables
 
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 4234c137ba..8692ebe67f 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -15,7 +15,7 @@ Mentioned these in [babel/notes](https://github.com/babel/notes/blob/master/2017
 ### Remake `compat-table` used in preset-env
 
 > https://github.com/kangax/compat-table could use a remake, ideally work with browser vendors on this
-    
+
 - There is also https://github.com/mdn/browser-compat-data
 - Also use data from test262?
 - Run tests against real browsers
@@ -78,7 +78,7 @@ Mentioned these in [babel/notes](https://github.com/babel/notes/blob/master/2017
 - Use [six-speed](https://github.com/kpdecker/six-speed) repo as a base, needs to apply for ES6 and proposals
 - Need continued maintainence
 
-### Compiled Output Stats 
+### Compiled Output Stats
 
 > [#5340](https://github.com/babel/babel/issues/5340) Can show the code size before and after compiling to give a sense of compiled output. Could create suggestions like using "loose" mode or not compiling, etc.
 
@@ -133,7 +133,7 @@ Better set of tests for stability/spec compliancy.
 - Create/expand on new tools like https://github.com/boopathi/babel-time-travel
 
 ### Speed
-  
+
 > Already working with v8 via https://github.com/v8/web-tooling-benchmark, but can add other representative workloads: jsx/flow/ts/es6+.
 
 Can run these benchmarks for perf PRs, should track some over time.
@@ -157,7 +157,7 @@ Can run these benchmarks for perf PRs, should track some over time.
 - Import any package from npm (can give test examples for 3rd party plugins, debugging issues)
 - Run any plugin from npm
 - Create a plugin from the repl (can we merge it with ASTExplorer/codesandbox?), even publish, run from URL?
-- Import/Export a `.babelrc` file
+- Import/Export a config file
 - Combine ^ with the ability to run the version of Babel in a PR/master.
 - Use plugin's tests in the repo as "examples" for docs.
 
diff --git a/docs/standalone.md b/docs/standalone.md
index ae62ace821..b282f3407c 100644
--- a/docs/standalone.md
+++ b/docs/standalone.md
@@ -57,7 +57,7 @@ Loading external scripts via `src` attribute is supported too:
 <script type="text/babel" src="foo.js"></script>
 ```
 
-Note that `.babelrc` doesn't work in @babel/standalone, as no file system access is available. The presets and/or plugins to use **must** be specified in the options passed to `Babel.transform`.
+Note that [config files](config-files.md) don't work in @babel/standalone, as no file system access is available. The presets and/or plugins to use **must** be specified in the options passed to `Babel.transform`.
 
 Customisation
 =============
diff --git a/docs/v7-migration-api.md b/docs/v7-migration-api.md
index b6f8b53db4..cccd094d4d 100644
--- a/docs/v7-migration-api.md
+++ b/docs/v7-migration-api.md
@@ -73,13 +73,13 @@ Included is a `root` option that defaults to the current working directory for i
 It is also not loaded relatively so it will handle symlinking correctly, whereas before you may have had
 hard-code the paths in webpack before.
 
-Check the `babel.config.js` docs for more info: https://babeljs.io/docs/en/next/babelconfigjs.html
+Check the `babel.config.js` docs for more info: [project-wide configuration](config-files.md#project-wide-configuration)
 
-This file combined with the new [`overrides`](https://babeljs.io/docs/en/next/babelrc.html#overrides) property and `env` lets you have a single config file
+This file combined with the new [`overrides`](options.md#overrides) property and `env` lets you have a single config file
 that can work for all the files in a project vs. multiple config files per folder.
 
 We also exclude `node_modules` by default and only look in the root unless you opt-in to setting
-an array of the `.babelrc` option such as `"babelrc": [".", "node_modules/pkgA"]`
+an array of the `.babelrcRoots` option such as `"babelrcRoots": [".", "node_modules/pkgA"]`
 
 ## Asserting Babel version [#7450](https://github.com/babel/babel/pull/7450)
 
diff --git a/docs/v7-migration.md b/docs/v7-migration.md
index fe59ff38f6..c2323767e6 100644
--- a/docs/v7-migration.md
+++ b/docs/v7-migration.md
@@ -227,7 +227,7 @@ If you were relying on Babel to inject `"use strict"` into all of your CommonJS
 
 `babel-preset-react` has always included the flow plugin automatically from the beginning. This has actually caused a lot of issues with users that accidently use `flow` syntax without intending due to a typo, or adding it in without typechecking with `flow` itself, resulting in errors.
 
-This became further of an issue after we decided to support TypeScript with the help of the TS team. If you wanted to use the react and typescript presets, we would have to figure out a way to turn on/off the syntax automatically via file type or the directive. In the end it seemed easiest to just separate the presets entirely. 
+This became further of an issue after we decided to support TypeScript with the help of the TS team. If you wanted to use the react and typescript presets, we would have to figure out a way to turn on/off the syntax automatically via file type or the directive. In the end it seemed easiest to just separate the presets entirely.
 
 So now the react preset and the flow preset are separated.
 
@@ -329,7 +329,7 @@ npm install @babel/plugin-transform-runtime --save-dev
   "plugins": [
 -   ["@babel/plugin-transform-runtime"],
 +   ["@babel/plugin-transform-runtime", {
-+     "corejs": 2,   
++     "corejs": 2,
 +   }],
   ]
 }
@@ -606,7 +606,7 @@ This change just makes babel-generator output `,` instead of `;`.
 
 > Remove `babel-core/src/api/browser.js` [#5124](https://github.com/babel/babel/pull/5124) ![none](https://img.shields.io/badge/risk%20of%20breakage%3F-none-brightgreen.svg)
 
-`babel-browser` was already removed in 6.0. If you need to use Babel in the browser or a non-Node environment, use [babel-standalone](https://github.com/babel/babel-standalone).
+`babel-browser` was already removed in 6.0. If you need to use Babel in the browser or a non-Node environment, use [@babel/standalone](standalone.md).
 
 Babel will return `filename` as an absolute path [#8044](https://github.com/babel/babel/pull/8044)
 
diff --git a/website/i18n/en.json b/website/i18n/en.json
index ae23e5a5a2..08f8d15a68 100644
--- a/website/i18n/en.json
+++ b/website/i18n/en.json
@@ -4,11 +4,10 @@
     "next": "Next",
     "previous": "Previous",
     "tagline": "The compiler for next generation JavaScript",
-    "babelconfigjs": "babel.config.js",
-    "babelrc": ".babelrc",
     "caveats": "Caveats",
     "babel-cli": "babel-cli",
     "babel-code-frame": "babel-code-frame",
+    "config-files": "Config Files",
     "configuration": "Configure Babel",
     "core-packages": "Babel's core packages",
     "babel-core": "babel-core",
@@ -54,8 +53,9 @@
     "learn": "Learn ES2015",
     "babel-minify": "babel-minify",
     "babel-node": "babel-node",
+    "options": "Options",
     "babel-parser": "babel-parser",
-    "babel-plugin-external-helpers": "babel-plugin-external-helpers",
+    "babel-plugin-external-helpers": "@babel/plugin-external-helpers",
     "external-helpers": "external-helpers",
     "babel-plugin-minify-builtins": "babel-plugin-minify-builtins",
     "minify-builtins": "minify-builtins",
@@ -79,125 +79,125 @@
     "minify-simplify": "minify-simplify",
     "babel-plugin-minify-type-constructors": "babel-plugin-minify-type-constructors",
     "minify-type-constructors": "minify-type-constructors",
-    "babel-plugin-proposal-async-generator-functions": "babel-plugin-proposal-async-generator-functions",
+    "babel-plugin-proposal-async-generator-functions": "@babel/plugin-proposal-async-generator-functions",
     "proposal-async-generator-functions": "proposal-async-generator-functions",
-    "babel-plugin-proposal-class-properties": "babel-plugin-proposal-class-properties",
+    "babel-plugin-proposal-class-properties": "@babel/plugin-proposal-class-properties",
     "proposal-class-properties": "proposal-class-properties",
-    "babel-plugin-proposal-decorators": "babel-plugin-proposal-decorators",
+    "babel-plugin-proposal-decorators": "@babel/plugin-proposal-decorators",
     "proposal-decorators": "proposal-decorators",
-    "babel-plugin-proposal-do-expressions": "babel-plugin-proposal-do-expressions",
+    "babel-plugin-proposal-do-expressions": "@babel/plugin-proposal-do-expressions",
     "proposal-do-expressions": "proposal-do-expressions",
-    "babel-plugin-proposal-export-default-from": "babel-plugin-proposal-export-default-from",
+    "babel-plugin-proposal-export-default-from": "@babel/plugin-proposal-export-default-from",
     "proposal-export-default-from": "proposal-export-default-from",
-    "babel-plugin-proposal-export-namespace-from": "babel-plugin-proposal-export-namespace-from",
+    "babel-plugin-proposal-export-namespace-from": "@babel/plugin-proposal-export-namespace-from",
     "proposal-export-namespace-from": "proposal-export-namespace-from",
-    "babel-plugin-proposal-function-bind": "babel-plugin-proposal-function-bind",
+    "babel-plugin-proposal-function-bind": "@babel/plugin-proposal-function-bind",
     "proposal-function-bind": "proposal-function-bind",
-    "babel-plugin-proposal-function-sent": "babel-plugin-proposal-function-sent",
+    "babel-plugin-proposal-function-sent": "@babel/plugin-proposal-function-sent",
     "proposal-function-sent": "proposal-function-sent",
-    "babel-plugin-proposal-json-strings": "babel-plugin-proposal-json-strings",
+    "babel-plugin-proposal-json-strings": "@babel/plugin-proposal-json-strings",
     "proposal-json-strings": "proposal-json-strings",
-    "babel-plugin-proposal-logical-assignment-operators": "babel-plugin-proposal-logical-assignment-operators",
+    "babel-plugin-proposal-logical-assignment-operators": "@babel/plugin-proposal-logical-assignment-operators",
     "proposal-logical-assignment-operators": "proposal-logical-assignment-operators",
-    "babel-plugin-proposal-nullish-coalescing-operator": "babel-plugin-proposal-nullish-coalescing-operator",
+    "babel-plugin-proposal-nullish-coalescing-operator": "@babel/plugin-proposal-nullish-coalescing-operator",
     "proposal-nullish-coalescing-operator": "proposal-nullish-coalescing-operator",
-    "babel-plugin-proposal-numeric-separator": "babel-plugin-proposal-numeric-separator",
+    "babel-plugin-proposal-numeric-separator": "@babel/plugin-proposal-numeric-separator",
     "proposal-numeric-separator": "proposal-numeric-separator",
-    "babel-plugin-proposal-object-rest-spread": "babel-plugin-proposal-object-rest-spread",
+    "babel-plugin-proposal-object-rest-spread": "@babel/plugin-proposal-object-rest-spread",
     "proposal-object-rest-spread": "proposal-object-rest-spread",
-    "babel-plugin-proposal-optional-catch-binding": "babel-plugin-proposal-optional-catch-binding",
+    "babel-plugin-proposal-optional-catch-binding": "@babel/plugin-proposal-optional-catch-binding",
     "proposal-optional-catch-binding": "proposal-optional-catch-binding",
-    "babel-plugin-proposal-optional-chaining": "babel-plugin-proposal-optional-chaining",
+    "babel-plugin-proposal-optional-chaining": "@babel/plugin-proposal-optional-chaining",
     "proposal-optional-chaining": "proposal-optional-chaining",
-    "babel-plugin-proposal-pipeline-operator": "babel-plugin-proposal-pipeline-operator",
+    "babel-plugin-proposal-pipeline-operator": "@babel/plugin-proposal-pipeline-operator",
     "proposal-pipeline-operator": "proposal-pipeline-operator",
-    "babel-plugin-proposal-throw-expressions": "babel-plugin-proposal-throw-expressions",
+    "babel-plugin-proposal-throw-expressions": "@babel/plugin-proposal-throw-expressions",
     "proposal-throw-expressions": "proposal-throw-expressions",
-    "babel-plugin-proposal-unicode-property-regex": "babel-plugin-proposal-unicode-property-regex",
+    "babel-plugin-proposal-unicode-property-regex": "@babel/plugin-proposal-unicode-property-regex",
     "proposal-unicode-property-regex": "proposal-unicode-property-regex",
-    "babel-plugin-syntax-async-generators": "babel-plugin-syntax-async-generators",
+    "babel-plugin-syntax-async-generators": "@babel/plugin-syntax-async-generators",
     "syntax-async-generators": "syntax-async-generators",
-    "babel-plugin-syntax-bigint": "babel-plugin-syntax-bigint",
+    "babel-plugin-syntax-bigint": "@babel/plugin-syntax-bigint",
     "syntax-bigint": "syntax-bigint",
-    "babel-plugin-syntax-class-properties": "babel-plugin-syntax-class-properties",
+    "babel-plugin-syntax-class-properties": "@babel/plugin-syntax-class-properties",
     "syntax-class-properties": "syntax-class-properties",
-    "babel-plugin-syntax-decorators": "babel-plugin-syntax-decorators",
+    "babel-plugin-syntax-decorators": "@babel/plugin-syntax-decorators",
     "syntax-decorators": "syntax-decorators",
-    "babel-plugin-syntax-do-expressions": "babel-plugin-syntax-do-expressions",
+    "babel-plugin-syntax-do-expressions": "@babel/plugin-syntax-do-expressions",
     "syntax-do-expressions": "syntax-do-expressions",
-    "babel-plugin-syntax-dynamic-import": "babel-plugin-syntax-dynamic-import",
+    "babel-plugin-syntax-dynamic-import": "@babel/plugin-syntax-dynamic-import",
     "syntax-dynamic-import": "syntax-dynamic-import",
-    "babel-plugin-syntax-export-default-from": "babel-plugin-syntax-export-default-from",
+    "babel-plugin-syntax-export-default-from": "@babel/plugin-syntax-export-default-from",
     "syntax-export-default-from": "syntax-export-default-from",
-    "babel-plugin-syntax-export-namespace-from": "babel-plugin-syntax-export-namespace-from",
+    "babel-plugin-syntax-export-namespace-from": "@babel/plugin-syntax-export-namespace-from",
     "syntax-export-namespace-from": "syntax-export-namespace-from",
-    "babel-plugin-syntax-flow": "babel-plugin-syntax-flow",
+    "babel-plugin-syntax-flow": "@babel/plugin-syntax-flow",
     "syntax-flow": "syntax-flow",
-    "babel-plugin-syntax-function-bind": "babel-plugin-syntax-function-bind",
+    "babel-plugin-syntax-function-bind": "@babel/plugin-syntax-function-bind",
     "syntax-function-bind": "syntax-function-bind",
-    "babel-plugin-syntax-function-sent": "babel-plugin-syntax-function-sent",
+    "babel-plugin-syntax-function-sent": "@babel/plugin-syntax-function-sent",
     "syntax-function-sent": "syntax-function-sent",
-    "babel-plugin-syntax-import-meta": "babel-plugin-syntax-import-meta",
+    "babel-plugin-syntax-import-meta": "@babel/plugin-syntax-import-meta",
     "syntax-import-meta": "syntax-import-meta",
-    "babel-plugin-syntax-json-strings": "babel-plugin-syntax-json-strings",
+    "babel-plugin-syntax-json-strings": "@babel/plugin-syntax-json-strings",
     "syntax-json-strings": "syntax-json-strings",
-    "babel-plugin-syntax-jsx": "babel-plugin-syntax-jsx",
+    "babel-plugin-syntax-jsx": "@babel/plugin-syntax-jsx",
     "syntax-jsx": "syntax-jsx",
-    "babel-plugin-syntax-logical-assignment-operators": "babel-plugin-syntax-logical-assignment-operators",
+    "babel-plugin-syntax-logical-assignment-operators": "@babel/plugin-syntax-logical-assignment-operators",
     "syntax-logical-assignment-operators": "syntax-logical-assignment-operators",
-    "babel-plugin-syntax-nullish-coalescing-operator": "babel-plugin-syntax-nullish-coalescing-operator",
+    "babel-plugin-syntax-nullish-coalescing-operator": "@babel/plugin-syntax-nullish-coalescing-operator",
     "syntax-nullish-coalescing-operator": "syntax-nullish-coalescing-operator",
-    "babel-plugin-syntax-numeric-separator": "babel-plugin-syntax-numeric-separator",
+    "babel-plugin-syntax-numeric-separator": "@babel/plugin-syntax-numeric-separator",
     "syntax-numeric-separator": "syntax-numeric-separator",
-    "babel-plugin-syntax-object-rest-spread": "babel-plugin-syntax-object-rest-spread",
+    "babel-plugin-syntax-object-rest-spread": "@babel/plugin-syntax-object-rest-spread",
     "syntax-object-rest-spread": "syntax-object-rest-spread",
-    "babel-plugin-syntax-optional-catch-binding": "babel-plugin-syntax-optional-catch-binding",
+    "babel-plugin-syntax-optional-catch-binding": "@babel/plugin-syntax-optional-catch-binding",
     "syntax-optional-catch-binding": "syntax-optional-catch-binding",
-    "babel-plugin-syntax-optional-chaining": "babel-plugin-syntax-optional-chaining",
+    "babel-plugin-syntax-optional-chaining": "@babel/plugin-syntax-optional-chaining",
     "syntax-optional-chaining": "syntax-optional-chaining",
-    "babel-plugin-syntax-pipeline-operator": "babel-plugin-syntax-pipeline-operator",
+    "babel-plugin-syntax-pipeline-operator": "@babel/plugin-syntax-pipeline-operator",
     "syntax-pipeline-operator": "syntax-pipeline-operator",
-    "babel-plugin-syntax-throw-expressions": "babel-plugin-syntax-throw-expressions",
+    "babel-plugin-syntax-throw-expressions": "@babel/plugin-syntax-throw-expressions",
     "syntax-throw-expressions": "syntax-throw-expressions",
-    "babel-plugin-syntax-typescript": "babel-plugin-syntax-typescript",
+    "babel-plugin-syntax-typescript": "@babel/plugin-syntax-typescript",
     "syntax-typescript": "syntax-typescript",
-    "babel-plugin-transform-arrow-functions": "babel-plugin-transform-arrow-functions",
+    "babel-plugin-transform-arrow-functions": "@babel/plugin-transform-arrow-functions",
     "transform-arrow-functions": "transform-arrow-functions",
-    "babel-plugin-transform-async-to-generator": "babel-plugin-transform-async-to-generator",
+    "babel-plugin-transform-async-to-generator": "@babel/plugin-transform-async-to-generator",
     "transform-async-to-generator": "transform-async-to-generator",
-    "babel-plugin-transform-block-scoped-functions": "babel-plugin-transform-block-scoped-functions",
+    "babel-plugin-transform-block-scoped-functions": "@babel/plugin-transform-block-scoped-functions",
     "transform-block-scoped-functions": "transform-block-scoped-functions",
-    "babel-plugin-transform-block-scoping": "babel-plugin-transform-block-scoping",
+    "babel-plugin-transform-block-scoping": "@babel/plugin-transform-block-scoping",
     "transform-block-scoping": "transform-block-scoping",
-    "babel-plugin-transform-classes": "babel-plugin-transform-classes",
+    "babel-plugin-transform-classes": "@babel/plugin-transform-classes",
     "transform-classes": "transform-classes",
-    "babel-plugin-transform-computed-properties": "babel-plugin-transform-computed-properties",
+    "babel-plugin-transform-computed-properties": "@babel/plugin-transform-computed-properties",
     "transform-computed-properties": "transform-computed-properties",
-    "babel-plugin-transform-destructuring": "babel-plugin-transform-destructuring",
+    "babel-plugin-transform-destructuring": "@babel/plugin-transform-destructuring",
     "transform-destructuring": "transform-destructuring",
-    "babel-plugin-transform-dotall-regex": "babel-plugin-transform-dotall-regex",
+    "babel-plugin-transform-dotall-regex": "@babel/plugin-transform-dotall-regex",
     "transform-dotall-regex": "transform-dotall-regex",
-    "babel-plugin-transform-duplicate-keys": "babel-plugin-transform-duplicate-keys",
+    "babel-plugin-transform-duplicate-keys": "@babel/plugin-transform-duplicate-keys",
     "transform-duplicate-keys": "transform-duplicate-keys",
-    "babel-plugin-transform-exponentiation-operator": "babel-plugin-transform-exponentiation-operator",
+    "babel-plugin-transform-exponentiation-operator": "@babel/plugin-transform-exponentiation-operator",
     "transform-exponentiation-operator": "transform-exponentiation-operator",
-    "babel-plugin-transform-flow-comments": "babel-plugin-transform-flow-comments",
+    "babel-plugin-transform-flow-comments": "@babel/plugin-transform-flow-comments",
     "transform-flow-comments": "transform-flow-comments",
-    "babel-plugin-transform-flow-strip-types": "babel-plugin-transform-flow-strip-types",
+    "babel-plugin-transform-flow-strip-types": "@babel/plugin-transform-flow-strip-types",
     "transform-flow-strip-types": "transform-flow-strip-types",
-    "babel-plugin-transform-for-of": "babel-plugin-transform-for-of",
+    "babel-plugin-transform-for-of": "@babel/plugin-transform-for-of",
     "transform-for-of": "transform-for-of",
-    "babel-plugin-transform-function-name": "babel-plugin-transform-function-name",
+    "babel-plugin-transform-function-name": "@babel/plugin-transform-function-name",
     "transform-function-name": "transform-function-name",
-    "babel-plugin-transform-inline-consecutive-adds": "babel-plugin-transform-inline-consecutive-adds",
+    "babel-plugin-transform-inline-consecutive-adds": "@babel/plugin-transform-inline-consecutive-adds",
     "transform-inline-consecutive-adds": "transform-inline-consecutive-adds",
     "babel-plugin-transform-inline-environment-variables": "babel-plugin-transform-inline-environment-variables",
     "transform-inline-environment-variables": "transform-inline-environment-variables",
-    "babel-plugin-transform-instanceof": "babel-plugin-transform-instanceof",
+    "babel-plugin-transform-instanceof": "@babel/plugin-transform-instanceof",
     "transform-instanceof": "transform-instanceof",
-    "babel-plugin-transform-jscript": "babel-plugin-transform-jscript",
+    "babel-plugin-transform-jscript": "@babel/plugin-transform-jscript",
     "transform-jscript": "transform-jscript",
-    "babel-plugin-transform-literals": "babel-plugin-transform-literals",
+    "babel-plugin-transform-literals": "@babel/plugin-transform-literals",
     "transform-literals": "transform-literals",
     "babel-plugin-transform-member-expression-literals": "babel-plugin-transform-member-expression-literals",
     "transform-member-expression-literals": "transform-member-expression-literals",
@@ -205,47 +205,47 @@
     "transform-merge-sibling-variables": "transform-merge-sibling-variables",
     "babel-plugin-transform-minify-booleans": "babel-plugin-transform-minify-booleans",
     "transform-minify-booleans": "transform-minify-booleans",
-    "babel-plugin-transform-modules-amd": "babel-plugin-transform-modules-amd",
+    "babel-plugin-transform-modules-amd": "@babel/plugin-transform-modules-amd",
     "transform-modules-amd": "transform-modules-amd",
-    "babel-plugin-transform-modules-commonjs": "babel-plugin-transform-modules-commonjs",
+    "babel-plugin-transform-modules-commonjs": "@babel/plugin-transform-modules-commonjs",
     "transform-modules-commonjs": "transform-modules-commonjs",
-    "babel-plugin-transform-modules-systemjs": "babel-plugin-transform-modules-systemjs",
+    "babel-plugin-transform-modules-systemjs": "@babel/plugin-transform-modules-systemjs",
     "transform-modules-systemjs": "transform-modules-systemjs",
-    "babel-plugin-transform-modules-umd": "babel-plugin-transform-modules-umd",
+    "babel-plugin-transform-modules-umd": "@babel/plugin-transform-modules-umd",
     "transform-modules-umd": "transform-modules-umd",
-    "babel-plugin-transform-new-target": "babel-plugin-transform-new-target",
+    "babel-plugin-transform-new-target": "@babel/plugin-transform-new-target",
     "transform-new-target": "transform-new-target",
     "babel-plugin-transform-node-env-inline": "babel-plugin-transform-node-env-inline",
     "transform-node-env-inline": "transform-node-env-inline",
-    "babel-plugin-transform-object-assign": "babel-plugin-transform-object-assign",
+    "babel-plugin-transform-object-assign": "@babel/plugin-transform-object-assign",
     "transform-object-assign": "transform-object-assign",
-    "babel-plugin-transform-object-set-prototype-of-to-assign": "babel-plugin-transform-object-set-prototype-of-to-assign",
+    "babel-plugin-transform-object-set-prototype-of-to-assign": "@babel/plugin-transform-object-set-prototype-of-to-assign",
     "transform-object-set-prototype-of-to-assign": "transform-object-set-prototype-of-to-assign",
-    "babel-plugin-transform-object-super": "babel-plugin-transform-object-super",
+    "babel-plugin-transform-object-super": "@babel/plugin-transform-object-super",
     "transform-object-super": "transform-object-super",
-    "babel-plugin-transform-parameters": "babel-plugin-transform-parameters",
+    "babel-plugin-transform-parameters": "@babel/plugin-transform-parameters",
     "transform-parameters": "transform-parameters",
     "babel-plugin-transform-property-literals": "babel-plugin-transform-property-literals",
     "transform-property-literals": "transform-property-literals",
-    "babel-plugin-transform-property-mutators": "babel-plugin-transform-property-mutators",
+    "babel-plugin-transform-property-mutators": "@babel/plugin-transform-property-mutators",
     "transform-property-mutators": "transform-property-mutators",
-    "babel-plugin-transform-proto-to-assign": "babel-plugin-transform-proto-to-assign",
+    "babel-plugin-transform-proto-to-assign": "@babel/plugin-transform-proto-to-assign",
     "transform-proto-to-assign": "transform-proto-to-assign",
-    "babel-plugin-transform-react-constant-elements": "babel-plugin-transform-react-constant-elements",
+    "babel-plugin-transform-react-constant-elements": "@babel/plugin-transform-react-constant-elements",
     "transform-react-constant-elements": "transform-react-constant-elements",
-    "babel-plugin-transform-react-display-name": "babel-plugin-transform-react-display-name",
+    "babel-plugin-transform-react-display-name": "@babel/plugin-transform-react-display-name",
     "transform-react-display-name": "transform-react-display-name",
-    "babel-plugin-transform-react-inline-elements": "babel-plugin-transform-react-inline-elements",
+    "babel-plugin-transform-react-inline-elements": "@babel/plugin-transform-react-inline-elements",
     "transform-react-inline-elements": "transform-react-inline-elements",
-    "babel-plugin-transform-react-jsx-compat": "babel-plugin-transform-react-jsx-compat",
+    "babel-plugin-transform-react-jsx-compat": "@babel/plugin-transform-react-jsx-compat",
     "transform-react-jsx-compat": "transform-react-jsx-compat",
-    "babel-plugin-transform-react-jsx-self": "babel-plugin-transform-react-jsx-self",
+    "babel-plugin-transform-react-jsx-self": "@babel/plugin-transform-react-jsx-self",
     "transform-react-jsx-self": "transform-react-jsx-self",
-    "babel-plugin-transform-react-jsx-source": "babel-plugin-transform-react-jsx-source",
+    "babel-plugin-transform-react-jsx-source": "@babel/plugin-transform-react-jsx-source",
     "transform-react-jsx-source": "transform-react-jsx-source",
-    "babel-plugin-transform-react-jsx": "babel-plugin-transform-react-jsx",
+    "babel-plugin-transform-react-jsx": "@babel/plugin-transform-react-jsx",
     "transform-react-jsx": "transform-react-jsx",
-    "babel-plugin-transform-regenerator": "babel-plugin-transform-regenerator",
+    "babel-plugin-transform-regenerator": "@babel/plugin-transform-regenerator",
     "transform-regenerator": "transform-regenerator",
     "babel-plugin-transform-regexp-constructors": "babel-plugin-transform-regexp-constructors",
     "transform-regexp-constructors": "transform-regexp-constructors",
@@ -255,56 +255,56 @@
     "transform-remove-debugger": "transform-remove-debugger",
     "babel-plugin-transform-remove-undefined": "babel-plugin-transform-remove-undefined",
     "transform-remove-undefined": "transform-remove-undefined",
-    "babel-plugin-transform-reserved-words": "babel-plugin-transform-reserved-words",
+    "babel-plugin-transform-reserved-words": "@babel/plugin-transform-reserved-words",
     "transform-reserved-words": "transform-reserved-words",
-    "babel-plugin-transform-runtime": "babel-plugin-transform-runtime",
+    "babel-plugin-transform-runtime": "@babel/plugin-transform-runtime",
     "transform-runtime": "transform-runtime",
-    "babel-plugin-transform-shorthand-properties": "babel-plugin-transform-shorthand-properties",
+    "babel-plugin-transform-shorthand-properties": "@babel/plugin-transform-shorthand-properties",
     "transform-shorthand-properties": "transform-shorthand-properties",
     "babel-plugin-transform-simplify-comparison-operators": "babel-plugin-transform-simplify-comparison-operators",
     "transform-simplify-comparison-operators": "transform-simplify-comparison-operators",
-    "babel-plugin-transform-spread": "babel-plugin-transform-spread",
+    "babel-plugin-transform-spread": "@babel/plugin-transform-spread",
     "transform-spread": "transform-spread",
-    "babel-plugin-transform-sticky-regex": "babel-plugin-transform-sticky-regex",
+    "babel-plugin-transform-sticky-regex": "@babel/plugin-transform-sticky-regex",
     "transform-sticky-regex": "transform-sticky-regex",
-    "babel-plugin-transform-strict-mode": "babel-plugin-transform-strict-mode",
+    "babel-plugin-transform-strict-mode": "@babel/plugin-transform-strict-mode",
     "transform-strict-mode": "transform-strict-mode",
-    "babel-plugin-transform-template-literals": "babel-plugin-transform-template-literals",
+    "babel-plugin-transform-template-literals": "@babel/plugin-transform-template-literals",
     "transform-template-literals": "transform-template-literals",
-    "babel-plugin-transform-typeof-symbol": "babel-plugin-transform-typeof-symbol",
+    "babel-plugin-transform-typeof-symbol": "@babel/plugin-transform-typeof-symbol",
     "transform-typeof-symbol": "transform-typeof-symbol",
-    "babel-plugin-transform-typescript": "babel-plugin-transform-typescript",
+    "babel-plugin-transform-typescript": "@babel/plugin-transform-typescript",
     "transform-typescript": "transform-typescript",
     "babel-plugin-transform-undefined-to-void": "babel-plugin-transform-undefined-to-void",
     "transform-undefined-to-void": "transform-undefined-to-void",
-    "babel-plugin-transform-unicode-regex": "babel-plugin-transform-unicode-regex",
+    "babel-plugin-transform-unicode-regex": "@babel/plugin-transform-unicode-regex",
     "transform-unicode-regex": "transform-unicode-regex",
     "plugins": "Plugins",
     "babel-polyfill": "babel-polyfill",
-    "babel-preset-env-standalone": "babel-preset-env-standalone",
+    "babel-preset-env-standalone": "@babel/preset-env-standalone",
     "env-standalone": "env-standalone",
-    "babel-preset-env": "babel-preset-env",
-    "babel-preset-es2015": "babel-preset-es2015",
+    "babel-preset-env": "@babel/preset-env",
+    "babel-preset-es2015": "@babel/preset-es2015",
     "es2015": "es2015",
-    "babel-preset-es2016": "babel-preset-es2016",
+    "babel-preset-es2016": "@babel/preset-es2016",
     "es2016": "es2016",
-    "babel-preset-es2017": "babel-preset-es2017",
+    "babel-preset-es2017": "@babel/preset-es2017",
     "es2017": "es2017",
-    "babel-preset-flow": "babel-preset-flow",
+    "babel-preset-flow": "@babel/preset-flow",
     "flow": "flow",
     "babel-preset-minify": "babel-preset-minify",
     "minify": "minify",
-    "babel-preset-react": "babel-preset-react",
+    "babel-preset-react": "@babel/preset-react",
     "react": "react",
-    "babel-preset-stage-0": "babel-preset-stage-0",
+    "babel-preset-stage-0": "@babel/preset-stage-0",
     "stage-0": "stage-0",
-    "babel-preset-stage-1": "babel-preset-stage-1",
+    "babel-preset-stage-1": "@babel/preset-stage-1",
     "stage-1": "stage-1",
-    "babel-preset-stage-2": "babel-preset-stage-2",
+    "babel-preset-stage-2": "@babel/preset-stage-2",
     "stage-2": "stage-2",
-    "babel-preset-stage-3": "babel-preset-stage-3",
+    "babel-preset-stage-3": "@babel/preset-stage-3",
     "stage-3": "stage-3",
-    "babel-preset-typescript": "babel-preset-typescript",
+    "babel-preset-typescript": "@babel/preset-typescript",
     "typescript": "typescript",
     "presets": "Presets",
     "babel-register": "babel-register",
diff --git a/website/sidebars.json b/website/sidebars.json
index 511230df32..326bb7e4b7 100644
--- a/website/sidebars.json
+++ b/website/sidebars.json
@@ -17,8 +17,8 @@
       "roadmap"
     ],
     "Usage": [
-      "babelconfigjs",
-      "babelrc",
+      "options",
+      "config-files",
       "babel-cli",
       "babel-polyfill",
       "babel-plugin-transform-runtime",