[babel 8] Remove core-js 2 from preset-env docs (#2839)

* [babel 8] Remove core-js 2 from preset-env docs

* Update docs/preset-env.md

Co-authored-by: Huáng Jùnliàng <[email protected]>

---------

Co-authored-by: Huáng Jùnliàng <[email protected]>

docs/preset-env.md

@@ -98,9 +98,9 @@ Added in: `v7.9.0`
 
 :::babel7
 
-:::note
-This option will be enabled by default in Babel 8
-:::
+::::note
+This option will be enabled by default in Babel 8.
+::::
 
 :::
 
@@ -162,14 +162,27 @@ An array of plugins to always include.
 
 Valid options include any:
 
+:::babel7
+
 - [Babel plugins](https://github.com/babel/babel/blob/main/packages/babel-compat-data/scripts/data/plugin-features.js) - both full and shorthand names are supported, for example the following are functionally equivalent:
   * `@babel/plugin-transform-spread`
   * `@babel/transform-spread`
   * `babel-transform-spread`
   * `transform-spread`
-
 - Built-ins (both for [core-js@2](https://github.com/babel/babel/blob/master/packages/babel-preset-env/src/polyfills/corejs2/built-in-definitions.js) and [core-js@3](https://github.com/babel/babel/blob/master/packages/babel-preset-env/src/polyfills/corejs3/built-in-definitions.js), such as `es.map`, `es.set`, or `es.object.assign`.
 
+:::
+
+:::babel8
+
+- [Babel plugins](https://github.com/babel/babel/blob/main/packages/babel-compat-data/scripts/data/plugin-features.js) - both full and shorthand names are supported, for example the following are functionally equivalent:
+  * `@babel/plugin-transform-optional-chaining`
+  * `@babel/transform-optional-chaining`
+  * `transform-optional-chaining`
+- [core-js@3](https://github.com/babel/babel/blob/master/packages/babel-preset-env/src/polyfills/corejs3/built-in-definitions.js) polyfills, such as `es.map`, `es.set`, or `es.object.assign`.
+
+:::
+
 Plugin names can be fully or partially specified (or using `RegExp`).
 
 Acceptable inputs:
@@ -196,7 +209,7 @@ An array of plugins to always exclude/remove.
 
 The possible options are the same as the `include` option.
 
-This option is useful for excluding a transform like `@babel/plugin-transform-regenerator` if you don't use generators and don't want to include `regeneratorRuntime` (when using `useBuiltIns`) or for using another plugin like [fast-async](https://github.com/MatAtBread/fast-async) instead of [Babel's async-to-gen](plugin-transform-async-generator-functions.md).
+This option is useful for excluding a transform like `@babel/plugin-transform-regenerator`, for example if you are using another plugin like [fast-async](https://github.com/MatAtBread/fast-async) instead of [Babel's async-to-gen](plugin-transform-async-generator-functions.md).
 
 ### `useBuiltIns`
 
@@ -206,6 +219,8 @@ This option configures how `@babel/preset-env` handles polyfills.
 
 When either the `usage` or `entry` options are used, `@babel/preset-env` will add direct references to `core-js` modules as bare imports (or requires). This means `core-js` will be resolved relative to the file itself and needs to be accessible.
 
+:::babel7
+
 Since `@babel/polyfill` was deprecated in 7.4.0, we recommend directly adding `core-js` and setting the version via the [`corejs`](#corejs) option.
 
 ```shell npm2yarn
@@ -216,6 +231,18 @@ npm install core-js@3 --save
 npm install core-js@2 --save
 ```
 
+:::
+
+:::babel8
+
+When auto-injecting polyfills using `@babel/preset-env`, you must add `core-js` to your dependencies:
+
+```shell npm2yarn
+npm install core-js
+```
+
+:::
+
 #### `useBuiltIns: 'entry'`
 
 <details>
@@ -227,12 +254,18 @@ npm install core-js@2 --save
 | `v7.0.0` | It replaces `"@babel/polyfill"` entry imports |
 </details>
 
-:::tip
+::::tip
 Only use `import "core-js";` once in your whole app.
+
+:::babel7
+
 If you are using `@babel/polyfill`, it already includes `core-js`: importing it twice will throw an error.
+
+:::
+
 Multiple imports or requires of those packages might cause global collisions and other issues that are hard to trace.
 We recommend creating a single entry file that only contains the `import` statements.
-:::
+::::
 
 This option enables a new plugin that replaces the `import "core-js/stable";` and `require("core-js");` statements with individual imports to different `core-js` entry points based on environment.
 
@@ -274,9 +307,13 @@ import "core-js/modules/esnext.math.scale";
 
 You can read [core-js](https://github.com/zloirock/core-js)'s documentation for more information about the different entry points.
 
-:::note
+:::babel7
+
+::::note
 When using `core-js@2` (either explicitly using the [`corejs: "2"`](#corejs) option or implicitly), `@babel/preset-env` will also transform imports and requires of `@babel/polyfill`.
 This behavior is deprecated because it isn't possible to use `@babel/polyfill` with different `core-js` versions.
+::::
+
 :::
 
 #### `useBuiltIns: 'usage'`
@@ -323,8 +360,17 @@ Don't add polyfills automatically per file, and don't transform `import "core-js
 
 Added in: `v7.4.0`
 
-`string` or `{ version: string, proposals: boolean }`, defaults to `"2.0"`. The `version` string can be any
-supported `core-js` versions. For example, `"3.8"` or `"2.0"`.
+:::babel7
+
+`string` or `{ version: string, proposals: boolean }`, defaults to `"2.0"`. The `version` string can be any supported `core-js` versions. For example, `"3.8"` or `"2.0"`.
+
+:::
+
+:::babel8
+
+`string` or `{ version: string, proposals: boolean }`, defaults to `"3.0"`. The `version` string can be any supported `core-js` versions. For example, `"3.8"`.
+
+:::
 
 This option only has an effect when used alongside `useBuiltIns: usage` or `useBuiltIns: entry`, and ensures `@babel/preset-env` injects the polyfills supported by your `core-js` version. It is recommended to specify the minor
 version otherwise `"3"` will be interpreted as `"3.0"` which may not include polyfills for the latest features.

website/docusaurus.config.js

@@ -96,12 +96,16 @@ toolsMD.forEach(tool => {
  * @returns md-ast transformer
  */
 function remarkDirectiveBabel8Plugin({ renderBabel8 }) {
-  return async function transformer(root) {
+  return function transformer(root) {
     const children = root.children;
     const deleteBatches = [];
     for (let index = 0; index < children.length; index++) {
       const node = children[index];
-      if (node.type !== "paragraph") continue;
+      if (node.type === "admonitionHTML") { // for support inside ::tip, etc
+        transformer(node);
+      } else if (node.type !== "paragraph") {
+        continue;
+      }
       const directiveLabel = node.children?.[0].value;
       if (directiveLabel === ":::babel8" || directiveLabel === ":::babel7") {
         let containerEnd = index + 1,