docs(en): merge webpack.js.org/master into webpack.js.org/cn @ c9cfd74a

package.json

@@ -73,7 +73,7 @@
     ]
   },
   "devDependencies": {
-    "@babel/core": "^7.17.0",
+    "@babel/core": "^7.17.5",
     "@babel/eslint-parser": "^7.17.0",
     "@babel/plugin-proposal-class-properties": "^7.16.7",
     "@babel/preset-env": "^7.16.11",
@@ -88,29 +88,29 @@
     "copy-webpack-plugin": "^10.2.4",
     "css-loader": "^6.6.0",
     "css-minimizer-webpack-plugin": "^3.4.1",
-    "cypress": "^9.4.1",
-    "directory-tree": "^3.1.0",
+    "cypress": "^9.5.0",
+    "directory-tree": "^3.2.1",
     "directory-tree-webpack-plugin": "^1.0.3",
     "duplexer": "^0.1.1",
-    "eslint": "^8.8.0",
+    "eslint": "^8.9.0",
     "eslint-config-prettier": "^8.3.0",
     "eslint-plugin-cypress": "^2.12.1",
     "eslint-plugin-mdx": "^1.16.0",
     "eslint-plugin-react": "^7.28.0",
     "eslint-plugin-react-hooks": "^4.3.0",
     "front-matter": "^4.0.2",
-    "github-slugger": "^1.3.0",
+    "github-slugger": "^1.4.0",
     "html-loader": "^2.1.2",
     "html-webpack-plugin": "^5.5.0",
     "http-server": "^14.1.0",
     "husky": "^7.0.4",
     "hyperlink": "^5.0.4",
-    "jest": "^27.5.0",
-    "lint-staged": "^12.3.3",
+    "jest": "^27.5.1",
+    "lint-staged": "^12.3.4",
     "lodash": "^4.17.21",
     "markdownlint": "^0.25.1",
-    "markdownlint-cli": "^0.31.0",
-    "mdast-util-to-string": "^1.1.0",
+    "markdownlint-cli": "^0.31.1",
+    "mdast-util-to-string": "^3.1.0",
     "mini-css-extract-plugin": "^2.5.3",
     "mkdirp": "^1.0.4",
     "modularscale-sass": "^3.0.3",
@@ -129,21 +129,20 @@
     "remark-gfm": "^1.0.0",
     "remark-html": "^15.0.1",
     "remark-refractor": "montogeek/remark-refractor",
-    "remark-slug": "^7.0.1",
     "rimraf": "^3.0.2",
-    "sass": "^1.49.7",
-    "sass-loader": "^12.4.0",
+    "sass": "^1.49.8",
+    "sass-loader": "^12.6.0",
     "sirv-cli": "^2.0.2",
     "sitemap-static": "^0.4.2",
     "start-server-and-test": "^1.14.0",
     "static-site-generator-webpack-plugin": "^3.4.1",
     "style-loader": "^3.3.1",
-    "tailwindcss": "^3.0.18",
+    "tailwindcss": "^3.0.23",
     "tap-spot": "^1.1.1",
     "textlint": "^11.8.2",
     "textlint-rule-heading": "^1.0.10",
     "unist-util-visit": "^4.1.0",
-    "webpack": "^5.68.0",
+    "webpack": "^5.69.1",
     "webpack-bundle-analyzer": "^4.5.0",
     "webpack-cli": "^4.9.2",
     "webpack-dev-server": "^4.7.4",
@@ -156,9 +155,9 @@
     "prop-types": "^15.8.1",
     "react": "^17.0.2",
     "react-dom": "^17.0.2",
-    "react-helmet-async": "^1.2.2",
+    "react-helmet-async": "^1.2.3",
     "react-router-dom": "^6.2.1",
-    "react-spring": "^9.4.2",
+    "react-spring": "^9.4.3",
     "react-tiny-popover": "5",
     "react-use": "^17.3.2",
     "react-visibility-sensor": "^5.0.2",

src/components/Markdown/Markdown.scss

@@ -1,4 +1,4 @@
-@use "sass:color";
+@use 'sass:color';
 @import 'vars';
 @import 'functions';
 @import 'prism-theme';
@@ -41,15 +41,16 @@ $topHeightMobileWithBanner: $bannerHeight + $topHeightMobile;
   h4,
   h5,
   h6 {
-    &:before {
-      content: '';
+    > span[id] {
+      position: absolute;
+      width: 0;
       display: block;
       visibility: hidden;
       pointer-events: none;
-      height: $topHeightMobile;
+      padding-top: $topHeightMobile;
       margin-top: -#{$topHeightMobile};
       @include break {
-        height: $topHeightDesktop;
+        padding-top: $topHeightDesktop;
         margin-top: -#{$topHeightDesktop};
       }
     }

src/content/api/cli.mdx

@@ -583,7 +583,7 @@ T> 请查阅 [environment 变量指南](/guides/environment-variables/)了解更
 
 | 变量名          | 描述                                          |
 | --------------- | --------------------------------------------- |
-| `WEBPACK_SERVE` | 如果使用了 `serve\|s`，则为 `true`。          |
+| `WEBPACK_SERVE` | 如果使用了 `serve\|server\|s`，则为 `true`。          |
 | `WEBPACK_BUILD` | 如果使用了 `build\|bundle\|b`，则为 `true`。  |
 | `WEBPACK_WATCH` | 如果使用了 `--watch\|watch\|w`，则为 `true`。 |
 

src/content/configuration/output.mdx

@@ -42,6 +42,8 @@ translators:
 
 与 [`output.filename`](#outputfilename) 相同，不过应用于 [Asset Modules](/guides/asset-modules/)。
 
+`[name]`、`[file]`、`[query]`、`[fragment]`、`[base]` 与 `[path]` 设置为空字符串，用于从数据 URI 替换构建的静态资源。
+
 ## output.asyncChunks $#outputasyncchunks$
 
 `boolean = true`

src/content/guides/code-splitting.mdx

@@ -34,6 +34,7 @@ contributors:
   - Adarah
   - atesgoral
   - snitin315
+  - artem-malko
 translators:
   - QC-L
   - jacob-lcs
@@ -429,6 +430,30 @@ import(/* webpackPreload: true */ 'ChartingLibrary');
 
 T> 不正确地使用 `webpackPreload` 会有损性能，请谨慎使用。
 
+有时你需要自己控制预加载。例如，动态引入的预加载可以通过异步脚本（async script）完成。这对于流式服务端渲染比较有用。
+
+```js
+const lazyComp = () =>
+  import('DynamicComponent').catch((error) => {
+    // 错误处理。
+    // 例如，我们可以在网络错误的情况下重发请求。
+  });
+```
+
+如果在 webpack 自己开始加载该脚本之前脚本加载将失败（如果该脚本不在页面上，webpack 只是创建一个 script 标签来加载其代码），则该 catch 处理程序将不会启动，直到 [chunkLoadTimeout](/configuration/output/#outputchunkloadtimeout) 未通过。此行为可能是意料之外的。但这是可以解释的——webpack 不能抛出任何错误，因为 webpack 不知道那个脚本失败了。Webpack 将在错误发生后立即将 onerror 处理程序添加到 script 中。
+
+为了防止这样的问题，你可以加载自己的 onerror 处理程序，在出现任何错误的情况下删除脚本。
+
+```html
+<script
+  src="https://example.com/dist/dynamicComponent.js"
+  async
+  onerror="this.remove()"
+></script>
+```
+
+在这种情况下，错误的脚本将被删除。Webpack 将创建自己的脚本，并且任何错误都将被处理而没有任何延时。
+
 ## bundle 分析(bundle analysis) $#bundle-analysis$
 
 一旦开始分离代码，一件很有帮助的事情是，分析输出结果来检查模块在何处结束。 [官方分析工具](https://github.com/webpack/analyse) 是一个不错的开始。还有一些其他社区支持的可选项：

src/remark-plugins/docschina-remark-slugger/index.mjs

@@ -1,6 +1,6 @@
 'use strict';
 
-import toString from 'mdast-util-to-string';
+import { toString } from 'mdast-util-to-string';
 import { visit } from 'unist-util-visit';
 import slugs from 'github-slugger';
 
@@ -30,6 +30,26 @@ function transformer(ast) {
     }
     data.id = id;
     props.id = id;
+
+    // insert <span id="..." /> for headings
+    node.children = [
+      {
+        type: 'paragraph',
+        data: {
+          hName: 'span',
+          hProperties: {
+            id,
+          },
+        },
+        children: [
+          {
+            type: 'text',
+            value: '',
+          },
+        ],
+      },
+      ...node.children,
+    ];
   }
 }
 

src/remark-plugins/remark-remove-heading-id/__snapshots__/index.test.mjs.snap

@@ -0,0 +1,7 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`customize blockquote should add id 1`] = `
+"<h2><span id=\\"user-content-hello-world\\"></span>hello world</h2>
+<p>this is me.</p>
+"
+`;

src/remark-plugins/remark-remove-heading-id/index.mjs

@@ -0,0 +1,14 @@
+import { visit } from 'unist-util-visit';
+export default function () {
+  return function transformer(ast) {
+    visit(ast, 'heading', visitor);
+  };
+  function visitor(node) {
+    if (node.data && node.data.id) {
+      delete node.data.id;
+    }
+    if (node.data && node.data.hProperties && node.data.hProperties.id) {
+      delete node.data.hProperties.id;
+    }
+  }
+}

src/remark-plugins/remark-remove-heading-id/index.test.mjs

@@ -0,0 +1,23 @@
+import { remark } from 'remark';
+import remarkHtml from 'remark-html';
+import Plugin from './index.mjs';
+import remarkSlug from '../remark-slug/index.mjs';
+describe('customize blockquote', () => {
+  it('should add id', () => {
+    remark()
+      .use(remarkSlug)
+      .use(Plugin)
+      .use(remarkHtml)
+      .process(
+        `
+## hello world
+
+this is me.
+`,
+        function (err, { value: contents }) {
+          expect(err).toBeNull();
+          expect(contents).toMatchSnapshot();
+        }
+      );
+  });
+});

src/remark-plugins/remark-slug/__snapshots__/index.test.mjs.snap

@@ -0,0 +1,7 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`remark slug should add id 1`] = `
+"<h2 id=\\"user-content-hello-world\\"><span id=\\"user-content-hello-world\\"></span>hello world</h2>
+<p>this is me.</p>
+"
+`;

src/remark-plugins/remark-slug/index.mjs

@@ -0,0 +1,56 @@
+// based on https://github.com/remarkjs/remark-slug/blob/8e6394c3dd6232cc9f0fb0b05e7eaf33063effa5/index.js
+// to fix https://github.com/webpack/webpack.js.org/pull/5947
+/**
+ * @typedef {import('mdast').Root} Root
+ * @typedef {import('hast').Properties} Properties
+ */
+
+import { toString } from 'mdast-util-to-string';
+import { visit } from 'unist-util-visit';
+import BananaSlug from 'github-slugger';
+
+const slugs = new BananaSlug();
+
+/**
+ * Plugin to add anchors headings using GitHub’s algorithm.
+ *
+ * @type {import('unified').Plugin<void[], Root>}
+ */
+export default function remarkSlug() {
+  return (tree) => {
+    slugs.reset();
+
+    visit(tree, 'heading', (node) => {
+      const data = node.data || (node.data = {});
+      const props = /** @type {Properties} */ (
+        data.hProperties || (data.hProperties = {})
+      );
+      let id = props.id;
+
+      id = id ? slugs.slug(String(id), true) : slugs.slug(toString(node));
+
+      data.id = id;
+      props.id = id;
+
+      // insert <span id="..." /> for headings
+      node.children = [
+        {
+          type: 'paragraph',
+          data: {
+            hName: 'span',
+            hProperties: {
+              id,
+            },
+          },
+          children: [
+            {
+              type: 'text',
+              value: '',
+            },
+          ],
+        },
+        ...node.children,
+      ];
+    });
+  };
+}

src/remark-plugins/remark-slug/index.test.mjs

@@ -0,0 +1,20 @@
+import { remark } from 'remark';
+import remarkHtml from 'remark-html';
+import Plugin from './index.mjs';
+describe('remark slug', () => {
+  it('should add id', () => {
+    remark()
+      .use(Plugin)
+      .use(remarkHtml)
+      .process(
+        `## hello world
+
+this is me.
+`,
+        function (err, { value: contents }) {
+          expect(err).toBeNull();
+          expect(contents).toMatchSnapshot();
+        }
+      );
+  });
+});

src/remark-plugins/remark-slug/license

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2015 Titus Wormer <[email protected]>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

src/utilities/content-tree-enhancers.mjs

@@ -2,12 +2,13 @@ import fs from 'fs';
 import path from 'path';
 import frontMatter from 'front-matter';
 import {remark} from 'remark';
-import slug from 'remark-slug';
+import slug from '../../src/remark-plugins/remark-slug/index.mjs';
 import extractAnchors from 'remark-extract-anchors';
 import remarkHtml from 'remark-html';
 import frontmatter from 'remark-frontmatter';
 import gfm from 'remark-gfm';
 import emoji from 'remark-emoji';
+import remarkRemoveHeadingId from '../remark-plugins/remark-remove-heading-id/index.mjs';
 
 export const enhance = (tree, options) => {
   // delete `./` root directory on node
@@ -46,6 +47,7 @@ export const enhance = (tree, options) => {
       .use(gfm)
       .use(emoji)
       .use(extractAnchors, { anchors, levels: 3 })
+      .use(remarkRemoveHeadingId)
       .use(remarkHtml)
       .process(content, (err) => {
         if (err) {