docs: manual tags injection guide (#4049)

web-infra-dev · Nov 24, 2024 · e3aaced · e3aaced
1 parent 6364b5e
commit e3aaced
Show file tree

Hide file tree

Showing 4 changed files with 54 additions and 0 deletions.
diff --git a/website/docs/en/config/html/inject.mdx b/website/docs/en/config/html/inject.mdx
@@ -82,3 +82,25 @@ export default {
   },
 };
 ```
+
+## Manual Injection
+
+When `html.inject` is set to `false`, Rsbuild will not inject tags into the HTML, and the tags defined in [html.tags](/config/html/tags) will not take effect.
+
+At this time, you can access all the tags to be injected through the `htmlPlugin.tags` template parameter, and manually inject them into the specified position.
+
+For example, insert the `<script>` tag generated by Rsbuild between `a.js` and `b.js`:
+
+```html title="index.html"
+<html>
+  <head>
+    <script src="https://example.com/a.js"></script>
+    <%= htmlPlugin.tags.headTags %>
+    <script src="https://example.com/b.js"></script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <%= htmlPlugin.tags.bodyTags %>
+  </body>
+</html>
+```
diff --git a/website/docs/en/guide/basic/html-template.mdx b/website/docs/en/guide/basic/html-template.mdx
@@ -224,6 +224,7 @@ In the HTML template, the `htmlPlugin.tags` variable gives you access to all the
     <%= htmlPlugin.tags.headTags %>
   </head>
   <body>
+    <div id="root"></div>
     <%= htmlPlugin.tags.bodyTags %>
   </body>
 </html>
@@ -257,6 +258,10 @@ export default {
 
 > For more usage, please refer to: [html.tags](/config/html/tags).
 
+:::tip
+Typically, you do not need to manually use the `htmlPlugin.tags.headTags` and `htmlPlugin.tags.bodyTags` template parameters, because Rsbuild will automatically inject these tags. See [html.inject](/config/html/inject) for more details on adjusting the injection location.
+:::
+
 ## HTML Plugin
 
 Rsbuild internally implements HTML-related features based on [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin). It is a fork of [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin), with the same features and options.

diff --git a/website/docs/zh/config/html/inject.mdx b/website/docs/zh/config/html/inject.mdx
@@ -82,3 +82,25 @@ export default {
   },
 };
 ```
+
+## 手动注入
+
+当 `html.inject` 设置为 `false` 时，Rsbuild 不会在 HTML 中自动插入标签，[html.tags](/config/html/tags) 中定义的标签也不会生效。
+
+此时，你可以通过 `htmlPlugin.tags` 模板参数来访问所有待注入的标签，并手动插入到指定的位置。
+
+例如，在 `a.js` 和 `b.js` 两个脚本之间插入 Rsbuild 生成的 `<script>` 标签：
+
+```html title="index.html"
+<html>
+  <head>
+    <script src="https://example.com/a.js"></script>
+    <%= htmlPlugin.tags.headTags %>
+    <script src="https://example.com/b.js"></script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <%= htmlPlugin.tags.bodyTags %>
+  </body>
+</html>
+```
diff --git a/website/docs/zh/guide/basic/html-template.mdx b/website/docs/zh/guide/basic/html-template.mdx
@@ -224,6 +224,7 @@ Rsbuild 通过插件来支持 [Pug](https://pugjs.org/) 模板引擎，详见 [@
     <%= htmlPlugin.tags.headTags %>
   </head>
   <body>
+    <div id="root"></div>
     <%= htmlPlugin.tags.bodyTags %>
   </body>
 </html>
@@ -257,6 +258,10 @@ export default {
 
 > 更多用法请参考：[html.tags](/config/html/tags)。
 
+:::tip
+通常你不需要手动使用 `htmlPlugin.tags.headTags` 和 `htmlPlugin.tags.bodyTags` 模板参数，因为 Rsbuild 会自动注入这些标签。参考 [html.inject](/config/html/inject) 了解调整标签注入位置。
+:::
+
 ## HTML 插件
 
 Rsbuild 内部基于 [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin) 实现 HTML 相关的能力。它是 [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin) 的一个 fork 版本，具备完全一致的功能和选项。