Skip to content

Commit

Permalink
docs: remove duplicated html tags example (#3308)
Browse files Browse the repository at this point in the history
  • Loading branch information
@chenjiahan
chenjiahan committed Aug 29, 2024
1 parent 7cb4e70 commit 5f53de5
Show file tree
Hide file tree
Showing 2 changed files with 16 additions and 130 deletions.
73 changes: 8 additions & 65 deletions website/docs/en/guide/basic/html-template.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -214,15 +214,11 @@ Rsbuild supports the [Pug](https://pugjs.org/) template engine via a plugin. See

## Injecting Tags

The `html.tags` option can be configured to insert any tags into the final generated HTML product.
You can insert any tags into the HTML files generated by Rsbuild by configuring [html.tags](/config/html/tags).

:::warning Usage Cases
The artifacts of the web application will eventually be referenced directly or indirectly by HTML entries, but most of the time injecting tags directly into HTML is not preferred.
:::

All tags that need to be injected into HTML can be accessed in the template file via the variable `htmlPlugin.tags`.
In the HTML template, the `htmlPlugin.tags` variable gives you access to all the tags inserted into the HTML:

```html
```html title="index.html"
<html>
<head>
<%= htmlPlugin.tags.headTags %>
Expand All @@ -233,86 +229,33 @@ All tags that need to be injected into HTML can be accessed in the template file
</html>
```

The purpose of `html.tags` is to adjust these template variables and thus modify the HTML, as defined in [API References](/config/html/tags).

### Tag Object
The purpose of the `html.tags` is to update these tag variables to modify the tags in the HTML. Here is a basic example:

```ts
export default {
output: {
assetPrefix: 'https://example.com/'
},
html: {
tags: [
{ tag: 'script', attrs: { src: 'a.js' } },
{ tag: 'script', attrs: { src: 'b.js' }, append: false },
{ tag: 'link', attrs: { href: 'style.css', rel: 'stylesheet' }, append: true },
{ tag: 'link', attrs: { href: 'page.css', rel: 'stylesheet' }, publicPath: false },
{ tag: 'script', attrs: { src: 'c.js' }, head: false },
{ tag: 'meta', attrs: { name: 'referrer', content: 'origin' } },
{ tag: 'script', attrs: { src: 'https://cdn.example.com/my-script.js' } },
],
},
};
```

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 `publicPath` configuration is enabled by default for tags, the value of [output.assetPrefix](/config/output/asset-prefix) will be stitched to the `src` property of the `script` tag that represents the path.

So the HTML output built with the above configuration will look like this.
- The generated HTML file looks like this:

```html
<html>
<head>
<script src="https://example.com/b.js"></script>
<link href="https://example.com/style.css" rel="stylesheet" />
<link href="page.css" rel="stylesheet" />
<script src="https://cdn.example.com/my-script.js"></script>
<!-- some other headTags... -->
<script src="https://example.com/a.js"></script>
<meta name="referrer" content="origin" />
</head>
<body>
<!-- some other bodyTags... -->
<script src="https://example.com/c.js"></script>
</body>
</html>
```

### Tags Handler

`html.tags` also accepts a callback function, which is often used to modify the list of tags or to ensure their relative position while inserting them.

```ts
export default {
html: {
tags: [
(tags) => {
tags.splice(0, 1);
},
{ tag: 'script', attrs: { src: 'a.js' }, head: false },
{ tag: 'script', attrs: { src: 'b.js' }, append: false },
{ tag: 'script', attrs: { src: 'c.js' } },
(tags) => [...tags, { tag: 'script', attrs: { src: 'd.js' } }],
],
},
};
```

And you will get:

```html
<html>
<head>
<!-- some other headTags... -->
<script src="https://example.com/c.js"></script>
<script src="https://example.com/d.js"></script>
</head>
<body>
<!-- some other bodyTags... -->
<script src="https://example.com/a.js"></script>
</body>
</html>
```
> For more usage, please refer to: [html.tags](/config/html/tags).
## HTML Plugin

Expand Down
73 changes: 8 additions & 65 deletions website/docs/zh/guide/basic/html-template.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -214,15 +214,11 @@ Rsbuild 通过插件来支持 [Pug](https://pugjs.org/) 模板引擎，详见 [@

## 注入标签

通过配置 `html.tags` 选项可以在最终生成的 HTML 产物中插入任意标签。
通过配置 [html.tags](/config/html/tags) 选项，可以在 Rsbuild 生成的 HTML 文件中插入任意标签。

:::warning 使用场景
前端应用的产物最终都会直接或间接地被 HTML 入口引用，但大多数时候直接向 HTML 注入标签都并非首选。
:::

模版文件中可以通过 `htmlPlugin.tags` 变量来访问需要最终注入到 HTML 的所有标签：
在 HTML 的模版中，可以通过 `htmlPlugin.tags` 变量来访问被注入到 HTML 的所有标签：

```html
```html title="index.html"
<html>
<head>
<%= htmlPlugin.tags.headTags %>
Expand All @@ -233,86 +229,33 @@ Rsbuild 通过插件来支持 [Pug](https://pugjs.org/) 模板引擎，详见 [@
</html>
```

`html.tags` 的作用就是调整这些模板变量进而修改 HTML，配置的具体定义参考 [API References](/config/html/tags)。

### 对象形式
`html.tags` 的作用就是调整这些 tags 变量，从而修改 HTML 里的标签，下面是一个基本的例子：

```ts
export default {
output: {
assetPrefix: 'https://example.com/'
},
html: {
tags: [
{ tag: 'script', attrs: { src: 'a.js' } },
{ tag: 'script', attrs: { src: 'b.js' }, append: false },
{ tag: 'link', attrs: { href: 'style.css', rel: 'stylesheet' }, append: true }
{ tag: 'link', attrs: { href: 'page.css', rel: 'stylesheet' }, publicPath: false }
{ tag: 'script', attrs: { src: 'c.js' }, head: false },
{ tag: 'meta', attrs: { name: 'referrer', content: 'origin' } },
{ tag: 'script', attrs: { src: 'https://cdn.example.com/my-script.js' } },
],
},
};
```

标签最终的插入位置由 `head` 和 `append` 选项决定，两个配置相同的元素将被插入到相同区域，并且维持彼此之间的相对位置。

标签默认会启用 `publicPath` 配置，即会将 [output.assetPrefix](/config/output/asset-prefix) 的值拼接到 `script` 标签的 `src` 等表示路径的属性上。

所以以上配置构建出的 HTML 产物将会类似：
- 生成的 HTML 文件如下：

```html
<html>
<head>
<script src="https://example.com/b.js"></script>
<link href="https://example.com/style.css" rel="stylesheet" />
<link href="page.css" rel="stylesheet" />
<script src="https://cdn.example.com/my-script.js"></script>
<!-- some other headTags... -->
<script src="https://example.com/a.js"></script>
<meta name="referrer" content="origin" />
</head>
<body>
<!-- some other bodyTags... -->
<script src="https://example.com/c.js"></script>
</body>
</html>
```

### 函数形式

`html.tags` 也支持传入回调函数，常用于修改标签列表或是在插入标签的同时确保其相对位置：

```ts
export default {
html: {
tags: [
(tags) => {
tags.splice(0, 1);
},
{ tag: 'script', attrs: { src: 'a.js' }, head: false },
{ tag: 'script', attrs: { src: 'b.js' }, append: false },
{ tag: 'script', attrs: { src: 'c.js' } },
(tags) => [...tags, { tag: 'script', attrs: { src: 'd.js' } }],
],
},
};
```

最终产物将会类似：

```html
<html>
<head>
<!-- some other headTags... -->
<script src="https://example.com/c.js"></script>
<script src="https://example.com/d.js"></script>
</head>
<body>
<!-- some other bodyTags... -->
<script src="https://example.com/a.js"></script>
</body>
</html>
```
> 更多用法请参考：[html.tags](/config/html/tags)。
## HTML 插件

Expand Down

0 comments on commit 5f53de5

Please sign in to comment.