docs: add api.modifyHTMLTags to document (#2101)

chenjiahan · web-flow · commit 00b38123d321 · 2024-04-15T19:30:57.000+08:00
diff --git a/packages/document/docs/en/plugins/dev/hooks.mdx b/packages/document/docs/en/plugins/dev/hooks.mdx
@@ -9,6 +9,7 @@ This chapter introduces the plugin hooks available for Rsbuild plugins.
 - [modifyRsbuildConfig](#modifyrsbuildconfig): Modify the configuration object passed to Rsbuild.
 - [modifyRspackConfig](#modifyrspackconfig): Modify the configuration object passed to Rspack.
 - [modifyBundlerChain](#modifybundlerchain): Modify the configuration object of Rspack through the chain API.
+- [modifyHTMLTags](#modifyhtmltags): Modify the tags that are injected into the HTML.
 - [onBeforeCreateCompiler](#onbeforecreatecompiler): Called before creating a compiler instance.
 - [onAfterCreateCompiler](#onaftercreatecompiler): Called after creating a compiler instance and before building.
 - [onExit](#onexit): Called when the process is about to exit.
@@ -51,6 +52,7 @@ When the `rsbuild dev` command or `rsbuild.startDevServer()` method is executed,
 - [onBeforeCreateCompiler](#onbeforecreatecompiler)
 - [onAfterCreateCompiler](#onaftercreatecompiler)
 - [onAfterStartDevServer](#onafterstartdevserver)
+- [modifyHTMLTags](#modifyhtmltags)
 - [onDevCompileDone](#ondevcompiledone)
 - [onCloseDevServer](#onclosedevserver)
 - [onExit](#onexit)
@@ -65,6 +67,7 @@ When the `rsbuild build` command or `rsbuild.build()` method is executed, Rsbuil
 - [onBeforeCreateCompiler](#onbeforecreatecompiler)
 - [onAfterCreateCompiler](#onaftercreatecompiler)
 - [onBeforeBuild](#onbeforebuild)
+- [modifyHTMLTags](#modifyhtmltags)
 - [onAfterBuild](#onafterbuild)
 - [onExit](#onexit)
 
@@ -290,6 +293,55 @@ const myPlugin = () => ({
 });
 ```
 
+### modifyHTMLTags
+
+Modify the tags that are injected into the HTML.
+
+- **Type:**
+
+```ts
+type HtmlBasicTag = {
+  // Tag name
+  tag: string;
+  // Attributes of the tag
+  attrs?: Record<string, string | boolean | null | undefined>;
+  // innerHTML of the tag
+  children?: string;
+};
+
+type HTMLTags = {
+  // Tags group inserted into <head>
+  headTags: HtmlBasicTag[];
+  // Tags group inserted into <body>
+  bodyTags: HtmlBasicTag[];
+};
+
+function ModifyHTMLTags(
+  callback: (tags: HTMLTags) => MaybePromise<HTMLTags>,
+): void;
+```
+
+- **Example:**
+
+```ts
+const myPlugin = () => ({
+  setup: (api) => {
+    api.modifyHTMLTags(({ headTags, bodyTags }) => {
+      headTags.push({
+        tag: 'script',
+        attrs: { src: 'https://example.com/foo.js' },
+      });
+      bodyTags.push({
+        tag: 'script',
+        children: 'console.log("hello world!");',
+      });
+
+      return { headTags, bodyTags };
+    });
+  },
+});
+```
+
 ### onBeforeCreateCompiler
 
 import OnBeforeCreateCompiler from '@en/shared/onBeforeCreateCompiler.md';
diff --git a/packages/document/docs/zh/plugins/dev/hooks.mdx b/packages/document/docs/zh/plugins/dev/hooks.mdx
@@ -9,6 +9,7 @@
 - [modifyRsbuildConfig](#modifyrsbuildconfig)：修改传递给 Rsbuild 的配置对象。
 - [modifyRspackConfig](#modifyrspackconfig)：修改传递给 Rspack 的配置对象。
 - [modifyBundlerChain](#modifybundlerchain)：通过 chain API 修改 Rspack 的配置对象。
+- [modifyHTMLTags](#modifyhtmltags)：修改注入到 HTML 中的标签。
 - [onBeforeCreateCompiler](#onbeforecreatecompiler)：在创建 compiler 实例前调用。
 - [onAfterCreateCompiler](#onaftercreatecompiler)：在创建 compiler 实例后、执行构建前调用。
 - [onExit](#onexit)：在进程即将退出时调用。
@@ -51,6 +52,7 @@
 - [onBeforeCreateCompiler](#onbeforecreatecompiler)
 - [onAfterCreateCompiler](#onaftercreatecompiler)
 - [onAfterStartDevServer](#onafterstartdevserver)
+- [modifyHTMLTags](#modifyhtmltags)
 - [onDevCompileDone](#ondevcompiledone)
 - [onCloseDevServer](#onclosedevserver)
 - [onExit](#onexit)
@@ -65,6 +67,7 @@
 - [onBeforeCreateCompiler](#onbeforecreatecompiler)
 - [onAfterCreateCompiler](#onaftercreatecompiler)
 - [onBeforeBuild](#onbeforebuild)
+- [modifyHTMLTags](#modifyhtmltags)
 - [onAfterBuild](#onafterbuild)
 - [onExit](#onexit)
 
@@ -292,6 +295,55 @@ const myPlugin = () => ({
 });
 ```
 
+### modifyHTMLTags
+
+修改注入到 HTML 中的标签。
+
+- **类型：**
+
+```ts
+type HtmlBasicTag = {
+  // 标签名
+  tag: string;
+  // 标签的属性
+  attrs?: Record<string, string | boolean | null | undefined>;
+  // 标签的 innerHTML
+  children?: string;
+};
+
+type HTMLTags = {
+  // 插入到 <head> 的标签组
+  headTags: HtmlBasicTag[];
+  // 插入到 <body> 的标签组
+  bodyTags: HtmlBasicTag[];
+};
+
+function ModifyHTMLTags(
+  callback: (tags: HTMLTags) => MaybePromise<HTMLTags>,
+): void;
+```
+
+- **示例：**
+
+```ts
+const myPlugin = () => ({
+  setup: (api) => {
+    api.modifyHTMLTags(({ headTags, bodyTags }) => {
+      headTags.push({
+        tag: 'script',
+        attrs: { src: 'https://example.com/foo.js' },
+      });
+      bodyTags.push({
+        tag: 'script',
+        children: 'console.log("hello world!");',
+      });
+
+      return { headTags, bodyTags };
+    });
+  },
+});
+```
+
 ### onBeforeCreateCompiler
 
 import OnBeforeCreateCompiler from '@zh/shared/onBeforeCreateCompiler.md';
