docs: clarify tag injection position (#5162)

chenjiahan · web-flow · commit ec2d14a48cf1 · 2025-05-05T16:03:58.000+08:00
diff --git a/packages/core/src/rspack/RsbuildHtmlPlugin.ts b/packages/core/src/rspack/RsbuildHtmlPlugin.ts
@@ -29,7 +29,9 @@ export type TagConfig = {
   publicPath?: HtmlTag['publicPath'];
 };
 
-/** @see {@link https://developer.mozilla.org/en-US/docs/Glossary/Void_element} */
+/**
+ * @see https://developer.mozilla.org/en-US/docs/Glossary/Void_element}
+ */
 const VOID_TAGS = [
   'area',
   'base',
@@ -48,7 +50,9 @@ const VOID_TAGS = [
   'wbr',
 ];
 
-/** @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head#see_also} */
+/**
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head#see_also
+ */
 const HEAD_TAGS = [
   'title',
   'base',
diff --git a/packages/core/src/types/config.ts b/packages/core/src/types/config.ts
@@ -1248,9 +1248,22 @@ export type HtmlBasicTag = {
 };
 
 export type HtmlTag = HtmlBasicTag & {
+  /** @default false */
   hash?: boolean | string | ((url: string, hash: string) => string);
+  /** @default true */
   publicPath?: boolean | string | ((url: string, publicPath: string) => string);
+  /**
+   * Defines the injection position of the current tag relative to existing tags
+   * - When set to `true`, the tag will be inserted after existing tags
+   * - When set to `false`, the tag will be inserted before existing tags
+   * @default true
+   */
   append?: boolean;
+  /**
+   * Specifies whether to add the current tag to the HTML `<head>` element
+   * @default defaults to `true` for element types allowed in the `<head>`, otherwise `false`
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head#see_also
+   */
   head?: boolean;
 };
 
diff --git a/website/docs/en/config/html/tags.mdx b/website/docs/en/config/html/tags.mdx
@@ -10,6 +10,8 @@ type TagsConfig = HtmlTag | HtmlTagHandler | Array<HtmlTag | HtmlTagHandler>;
 
 Modifies the tags that are injected into the HTML page.
 
+> In Rsbuild plugins, you can modify tags by using [api.modifyHTMLTags](/plugins/dev/hooks#modifyhtmltags) hook.
+
 ## Tag object
 
 ```ts
@@ -22,23 +24,24 @@ type HtmlTag = {
   /** @default true */
   publicPath?: boolean | string | ((url: string, publicPath: string) => string);
   /**
-   * Sets the insertion position of the current tag relative to the original tags.
-   * If set to `true` it will be inserted after the original tags, if set to `false` it will be inserted before the original tags.
+   * Defines the injection position of the current tag relative to existing tags
+   * - When set to `true`, the tag will be inserted after existing tags
+   * - When set to `false`, the tag will be inserted before existing tags
    * @default true
    */
   append?: boolean;
   /**
-   * Whether to add tags to head
-   * Enable by default only for elements that are allowed to be included in the `head` tag.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head#see_also}
+   * Specifies whether to add the current tag to the HTML `<head>` element
+   * @default defaults to `true` for element types allowed in the `<head>`, otherwise `false`
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head#see_also
    */
   head?: boolean;
 };
 ```
 
 A tag object can be used to describe the tag to be injected and the location of the injection can be controlled by the parameters.
 
-```js
+```ts title="rsbuild.config.ts"
 export default {
   output: {
     assetPrefix: 'https://example.com/',
@@ -78,25 +81,25 @@ Enabling `publicPath` will splice the [output.assetPrefix](/config/output/asset-
 
 You can also pass functions to those fields to control the path joining.
 
-### Set tag insertion position
+### Injection position
 
-The final insertion position of the tag is determined by the `head` and `append` options, and two elements with the same configuration will be inserted into the same area and hold their relative positions to each other.
+The final injection position of the tag is determined by the `head` and `append` options, and two elements with the same configuration will be inserted into the same area and hold their relative positions to each other.
 
-- `append`: used to describe whether the tag is added to the end or beginning of the original tags
-- `head`: used to describe whether to add this tag to the HTML `<head>`
+- `append`: Defines the injection position of the current tag relative to existing tags, defaults to `true`
+- `head`: Specifies whether to add the current tag to the HTML `<head>` element, defaults to `true` for element types allowed in the `<head>`, otherwise `false`
 
-The final insertion position on the page is as follows:
+The final injection position in HTML is as follows:
 
 ```html
 <html>
   <head>
     <!-- tags with `{ head: true, append: false }` here. -->
-    <!-- some other headTags... -->
+    <!-- existing headTags... -->
     <!-- tags with `{ head: true, append: true }` here. -->
   </head>
   <body>
     <!-- tags with `{ head: false, append: false }` here. -->
-    <!-- some other bodyTags... -->
+    <!-- existing bodyTags... -->
     <!-- tags with `{ head: false, append: true }` here. -->
   </body>
 </html>
diff --git a/website/docs/en/plugins/dev/hooks.mdx b/website/docs/en/plugins/dev/hooks.mdx
@@ -583,16 +583,32 @@ function ModifyHTMLTags(
 - **Example:**
 
 ```ts
-const myPlugin = () => ({
+const tagsPlugin = () => ({
+  name: 'tags-plugin',
   setup(api) {
     api.modifyHTMLTags(({ headTags, bodyTags }) => {
-      headTags.push({
+      // Inject a tag into <head>, before other tags
+      headTags.unshift({
         tag: 'script',
         attrs: { src: 'https://example.com/foo.js' },
       });
-      bodyTags.push({
+
+      // Inject a tag into <head>, after other tags
+      headTags.push({
         tag: 'script',
-        children: 'console.log("hello world!");',
+        attrs: { src: 'https://example.com/bar.js' },
+      });
+
+      // Inject a tag into <body>, before other tags
+      bodyTags.unshift({
+        tag: 'div',
+        children: 'before other body tags',
+      });
+
+      // Inject a tag into <body>, after other tags
+      bodyTags.push({
+        tag: 'div',
+        children: 'after other body tags',
       });
 
       return { headTags, bodyTags };
diff --git a/website/docs/zh/config/html/tags.mdx b/website/docs/zh/config/html/tags.mdx
@@ -10,6 +10,8 @@ type TagsConfig = HtmlTag | HtmlTagHandler | Array<HtmlTag | HtmlTagHandler>;
 
 添加和修改最终注入到 HTML 页面的标签。
 
+> 在 Rsbuild 插件中，可以通过 [api.modifyHTMLTags](/plugins/dev/hooks#modifyhtmltags) hook 来修改标签。
+
 ## 对象形式
 
 ```ts
@@ -22,22 +24,24 @@ type HtmlTag = {
   /** @default true */
   publicPath?: boolean | string | ((url: string, publicPath: string) => string);
   /**
-   * 定义当前标签相对于原有标签的插入位置。
-   * 设为 `true` 时，将被插入原有标签之后；设为 `false` 时，将被插入原有标签之前。
+   * 定义当前标签相对于已有标签的插入位置
+   * - 当设置为 `true` 时，标签将被插入到已有标签之后
+   * - 当设置为 `false` 时，标签将被插入到已有标签之前
    * @default true
    */
   append?: boolean;
   /**
-   * 是否将标签添加到 head 中 (仅对于允许包含在 head 中的元素会默认启用)
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head#see_also}
+   * 指定是否将当前标签添加到 HTML 的 `<head>` 元素中
+   * @default 对于允许在 `<head>` 中包含的元素类型，默认为 `true`，否则为 `false`
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head#see_also
    */
   head?: boolean;
 };
 ```
 
 对象形式的配置项可以用于描述需要注入的标签，并可以通过参数控制注入的位置：
 
-```js
+```ts title="rsbuild.config.ts"
 export default {
   output: {
     assetPrefix: 'https://example.com/',
@@ -77,26 +81,26 @@ export default {
 
 用户也可以向这两个配置传入函数，以自行控制路径拼接的逻辑。
 
-### 设置标签插入位置
+### 插入位置
 
-标签最终的插入位置由 `head` 和 `append` 选项决定，当两个元素的 `head` 和 `append` 配置相同时，将被插入到相同区域，并且维持彼此之间的相对位置。
+标签插入位置由 `head` 和 `append` 选项决定，当两个元素的 `head` 和 `append` 配置相同时，将被插入到相同区域，并且维持彼此之间的相对位置。
 
-- `append` 用于描述是将该标签添加到原有标签的末尾还是开头
-- `head` 用于描述是否将该标签添加到页面 `<head>` 中
+- `append` 定义当前标签相对于已有标签的插入位置，默认值为 `true`
+- `head` 指定是否将当前标签添加到 HTML 的 `<head>` 元素中，对于允许在 `<head>` 中包含的元素类型，默认为 `true`，否则为 `false`
 
-最终在页面中的插入位置如下：
+最终在 HTML 中的插入位置如下：
 
 ```html
 <html>
   <head>
-    <!-- tags with `{ head: true, append: false }` here. -->
-    <!-- some other headTags... -->
-    <!-- tags with `{ head: true, append: true }` here. -->
+    <!-- 设置了 `{ head: true, append: false }` 的标签。 -->
+    <!-- 已有的 headTags... -->
+    <!-- 设置了 `{ head: true, append: true }` 的标签。 -->
   </head>
   <body>
-    <!-- tags with `{ head: false, append: false }` here. -->
-    <!-- some other bodyTags... -->
-    <!-- tags with `{ head: false, append: true }` here. -->
+    <!-- 设置了 `{ head: false, append: false }` 的标签。 -->
+    <!-- 已有的 bodyTags... -->
+    <!-- 设置了 `{ head: false, append: true }` 的标签。 -->
   </body>
 </html>
 ```
diff --git a/website/docs/zh/plugins/dev/hooks.mdx b/website/docs/zh/plugins/dev/hooks.mdx
@@ -579,16 +579,32 @@ function ModifyHTMLTags(
 - **示例：**
 
 ```ts
-const myPlugin = () => ({
+const tagsPlugin = () => ({
+  name: 'tags-plugin',
   setup(api) {
     api.modifyHTMLTags(({ headTags, bodyTags }) => {
-      headTags.push({
+      // 在 <head> 中插入一个标签，位于其他标签之前
+      headTags.unshift({
         tag: 'script',
         attrs: { src: 'https://example.com/foo.js' },
       });
-      bodyTags.push({
+
+      // 在 <head> 中插入一个标签，位于其他标签之后
+      headTags.push({
         tag: 'script',
-        children: 'console.log("hello world!");',
+        attrs: { src: 'https://example.com/bar.js' },
+      });
+
+      // 在 <body> 中插入一个标签，位于其他标签之前
+      bodyTags.unshift({
+        tag: 'div',
+        children: 'before other body tags',
+      });
+
+      // 在 <body> 中插入一个标签，位于其他标签之后
+      bodyTags.push({
+        tag: 'div',
+        children: 'after other body tags',
       });
 
       return { headTags, bodyTags };
