@modern-js/main-doc 2.60.0 → 2.60.1-alpha.0

package/docs/zh/configure/app/html/app-icon.mdx

@@ -1,9 +1,55 @@
 ---
 title: appIcon
+configName: html.appIcon
 ---
 
 # html.appIcon
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/appIcon.md';
+- **类型：**
 
-<Main />
+```ts
+type AppIconItem = {
+  src: string;
+  size: number;
+  target?: 'apple-touch-icon' | 'web-app-manifest';
+};
+
+type AppIcon = string | {
+  name?: string;
+  icons: AppIconItem[];
+  filename?: string;
+};
+```
+
+- **默认值：** `undefined`
+
+设置 Web 应用的图标，用于在添加到移动设备的主屏幕时显示：
+
+- 生成 web app manifest 文件和其中的 `icons` 字段。
+- 生成 HTML 文件中的 `apple-touch-icon` 标签和 `manifest` 标签。
+
+### 字符串形式
+
+`string` 类型的 `appIcon` 配置是对象类型的一个语法糖。
+
+```js
+export default {
+  html: {
+    appIcon: './src/assets/icon.png',
+  },
+};
+```
+
+以上配置相当于下面配置的语法糖：
+
+```js
+export default {
+  html: {
+    appIcon: { icons: [{ src: './src/assets/icon.png', size: 180 }] }
+  },
+};
+```
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/html/crossorigin.mdx

@@ -1,9 +1,16 @@
 ---
 title: crossorigin
+configName: html.crossorigin
 ---
 
 # html.crossorigin
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/crossorigin.md';
+- **类型：** `boolean | 'anonymous' | 'use-credentials'`
+- **默认值：** `false`
 
-<Main />
+用于设置 `<script>` 和 `<style>` 标签的 [crossorigin](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) 属性。
+
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/html/disable-html-folder.mdx

@@ -4,6 +4,38 @@ title: disableHtmlFolder
 
 # html.disableHtmlFolder
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/disableHtmlFolder.md';
+- **类型：** `boolean`
+- **默认值：** `false`
 
-<Main />
+移除 HTML 产物对应的文件夹。开启该选项后，生成的 HTML 文件目录会从 `[name]/index.html` 变为 `[name].html`。
+
+### 示例
+
+默认情况下，HTML 产物在 `dist` 目录下的结构为：
+
+```bash
+/dist
+└── html
+    └── main
+        └── index.html
+```
+
+开启 `html.disableHtmlFolder` 配置:
+
+```js
+export default {
+  html: {
+    disableHtmlFolder: true,
+  },
+};
+```
+
+重新编译后，HTML 产物在 dist 中的目录结构如下：
+
+```bash
+/dist
+└── html
+    └── main.html
+```
+
+> 如果需要设置 HTML 文件在 dist 目录中的路径，请使用 `output.distPath.html` 配置。

package/docs/zh/configure/app/html/favicon-by-entries.mdx

@@ -4,6 +4,34 @@ title: faviconByEntries
 
 # html.faviconByEntries
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/faviconByEntries.md';
+- **类型：** `Record<string, string>`
+- **默认值：** `undefined`
+
+用于在多页面的场景下，为不同的页面设置不同的 favicon。
+
+整体用法与 `favicon` 一致，并且可以使用「入口名称」作为 key ，对各个页面进行单独设置。
+
+`faviconByEntries` 的优先级高于 `favicon`，因此会覆盖 `favicon` 中设置的值。
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 `html.favicon` 的函数用法代替。
+:::
+
+### 示例
+
+```js
+export default {
+  html: {
+    favicon: './src/assets/default.png',
+    faviconByEntries: {
+      foo: './src/assets/foo.png',
+    },
+  },
+};
+```
+
+重新编译后，可以看到:
+
+- 页面 `foo` 的 favicon 为 `./src/assets/foo.png`。
+- 其他页面的 favicon 为 `./src/assets/default.png`。
 
-<Main />

package/docs/zh/configure/app/html/favicon.mdx

@@ -1,9 +1,22 @@
 ---
 title: favicon
+configName: html.favicon
 ---
 
 # html.favicon
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/favicon.md';
+- **类型：** `string ｜ Function`
+- **默认值：** `undefined`
 
-<Main />
+设置页面的 favicon 图标，可以设置为：
+
+- URL 地址。
+- 文件的绝对路径。
+- 相对于项目根目录的相对路径。
+
+配置该选项后，在编译过程中会自动将图标拷贝至 dist 目录下，并在 HTML 中添加相应的 `link` 标签。
+
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/html/inject-by-entries.mdx

@@ -4,6 +4,34 @@ title: injectByEntries
 
 # html.injectByEntries
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/injectByEntries.md';
+- **类型：** `Record<string, boolean | string>`
+- **默认值：** `undefined`
+
+用于在多页面的场景下，为不同的页面设置不同的 script 标签插入位置。
+
+整体用法与 `inject` 一致，并且可以使用「入口名称」作为 key ，对各个页面进行单独设置。
+
+`injectByEntries` 的优先级高于 `inject`，因此会覆盖 `inject` 中设置的值。
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 `html.inject` 的函数用法代替。
+:::
+
+### 示例
+
+```js
+export default {
+  html: {
+    inject: 'head',
+    injectByEntries: {
+      foo: 'body',
+    },
+  },
+};
+```
+
+重新编译后，可以看到:
+
+- 页面 `foo` 的 script 标签会插入到 `body` 标签内。
+- 其他页面的 script 标签会插入到 `head` 标签内。
 
-<Main />

package/docs/zh/configure/app/html/inject.mdx

@@ -1,9 +1,15 @@
 ---
 title: inject
+configName: html.inject
 ---
 
 # html.inject
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/inject.md';
+- **类型：** `'head' | 'body' | boolean | Function`
+- **默认值：** `'head'`
 
-<Main />
+修改构建产物中 `<script>` 标签在 HTML 中的插入位置。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/html/meta-by-entries.mdx

@@ -4,6 +4,45 @@ title: metaByEntries
 
 # html.metaByEntries
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/metaByEntries.md';
+- **类型：** `Record<string, Meta>`
+- **默认值：** `undefined`
+
+用于在多页面的场景下，为不同的页面设置不同的 meta 标签。
+
+整体用法与 `meta` 一致，并且可以使用「入口名称」作为 key ，对各个页面进行单独设置。
+
+`metaByEntries` 的优先级高于 `meta`，因此会覆盖 `meta` 中设置的值。
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 `html.meta` 的函数用法代替。
+:::
+
+### 示例
+
+```js
+export default {
+  html: {
+    meta: {
+      description: 'ByteDance',
+    },
+    metaByEntries: {
+      foo: {
+        description: 'TikTok',
+      },
+    },
+  },
+};
+```
+
+编译后，可以看到页面 `foo` 的 meta 为：
+
+```html
+<meta name="description" content="TikTok" />
+```
+
+其他页面的 meta 为：
+
+```html
+<meta name="description" content="ByteDance" />
+```
 
-<Main />

package/docs/zh/configure/app/html/meta.mdx

@@ -1,9 +1,29 @@
 ---
 title: meta
+configName: html.meta
 ---
 
 # html.meta
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/meta.md';
+- **类型：** `Object | Function`
+- **默认值：**
 
-<Main />
+```js
+const defaultMeta = {
+  charset: { charset: 'utf-8' },
+  viewport:
+    'width=device-width, initial-scale=1.0, shrink-to-fit=no, viewport-fit=cover, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no',
+  'http-equiv': { 'http-equiv': 'x-ua-compatible', content: 'ie=edge' },
+  renderer: 'webkit',
+  layoutmode: 'standard',
+  imagemode: 'force',
+  'wap-font-scale': 'no',
+  'format-detection': 'telephone=no',
+};
+```
+
+配置 HTML 页面的 `<meta>` 标签。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/html/mount-id.mdx

@@ -1,9 +1,15 @@
 ---
 title: mountId
+configName: html.mountId
 ---
 
 # html.mountId
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/mountId.md';
+- **类型：** `string`
+- **默认值：** `'root'`
 
-<Main />
+默认情况下，HTML 模板中包含了 `root` 节点用于组件挂载，通过 `mountId` 可以修改该节点的 id。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/html/script-loading.mdx

@@ -1,9 +1,15 @@
 ---
 title: scriptLoading
+configName: html.scriptLoading
 ---
 
 # html.scriptLoading
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/scriptLoading.md';
+- **类型：** `'defer' | 'blocking' | 'module'`
+- **默认值：** `'defer'`
 
-<Main />
+用于设置 `<script>` 标签的加载方式。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/html/tags-by-entries.mdx

@@ -4,6 +4,41 @@ title: tagsByEntries
 
 # html.tagsByEntries
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/tagsByEntries.md';
+- **类型：** `Record<string, ArrayOrNot<HtmlInjectTag | HtmlInjectTagHandler>>`
+- **默认值：** `undefined`
+
+用于在多页面的场景下，为不同的页面注入不同的标签。
+
+整体用法与 `tags` 一致，并且可以使用「入口名称」作为 key ，对各个页面进行单独设置。
+
+`tagsByEntries` 的优先级高于 `tags`，因此会覆盖 `tags` 中设置的值。
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 `html.tags` 的函数用法代替。
+:::
+
+### 示例
+
+```js
+export default {
+  html: {
+    tags: [{ tag: 'script', attrs: { src: 'a.js' } }],
+    tagsByEntries: {
+      foo: [{ tag: 'script', attrs: { src: 'b.js' } }],
+    },
+  },
+};
+```
+
+编译后，可以看到页面 `foo` 注入标签：
+
+```html
+<script src="b.js"></script>
+```
+
+其他页面则注入了：
+
+```html
+<script src="a.js"></script>
+```
 
-<Main />

package/docs/zh/configure/app/html/tags.mdx

@@ -1,9 +1,20 @@
 ---
 title: tags
+configName: html.tags
 ---
 
 # html.tags
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/tags.md';
+- **类型：**
 
-<Main />
+```ts
+type TagsConfig = HtmlTag | HtmlTagHandler | Array<HtmlTag | HtmlTagHandler>;
+```
+
+- **默认值：** `undefined`
+
+添加和修改最终注入到 HTML 页面的标签。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/html/template-by-entries.mdx

@@ -4,6 +4,30 @@ title: templateByEntries
 
 # html.templateByEntries
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/templateByEntries.md';
+- **类型：** `Object`
+- **默认值：** `undefined`
+
+用于在多页面的场景下，为不同的页面设置不同的 HTML 模板。
+
+整体用法与 `template` 一致，并且可以使用「入口名称」作为 key ，对各个页面进行单独设置。
+
+`templateByEntries` 的优先级高于 `template`，因此会覆盖 `template` 设置的值。
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 `html.template` 的函数用法代替。
+:::
+
+### 示例
+
+```js
+export default {
+  html: {
+    template: './static/index.html',
+    templateByEntries: {
+      foo: './src/pages/foo/index.html',
+      bar: './src/pages/bar/index.html',
+    },
+  },
+};
+```
 
-<Main />

package/docs/zh/configure/app/html/template-parameters-by-entries.mdx

@@ -4,6 +4,33 @@ title: templateParametersByEntries
 
 # html.templateParametersByEntries
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/templateParametersByEntries.md';
+- **类型：** `Object`
+- **默认值：** `undefined`
+
+用于在多页面的场景下，为不同的页面设置不同的模板参数。
+
+整体用法与 `templateParameters` 一致，并且可以使用「入口名称」作为 key ，对各个页面进行单独设置。
+
+`templateParametersByEntries` 的优先级高于 `templateParameters`，因此会覆盖 `templateParameters` 中设置的值。
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 `html.templateParameters` 的函数用法代替。
+:::
+
+### 示例
+
+```js
+export default {
+  html: {
+    templateParametersByEntries: {
+      foo: {
+        type: 'a',
+      },
+      bar: {
+        type: 'b',
+      },
+    },
+  },
+};
+```
 
-<Main />

package/docs/zh/configure/app/html/template-parameters.mdx

@@ -1,9 +1,38 @@
 ---
 title: templateParameters
+configName: html.templateParameters
 ---
 
 # html.templateParameters
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/templateParameters.md';
+- **类型：** `Record<string, unknown> | Function`
+- **默认值：**
 
-<Main />
+```ts
+type DefaultParameters = {
+  mountId: string; // 对应 html.mountId 配置
+  entryName: string; // 入口名称
+  assetPrefix: string; // 对应 dev.assetPrefix 和 output.assetPrefix 配置
+  compilation: Compilation; // Rspack 的 compilation 对象
+  rspackConfig: Rspack.Configuration; // Rspack 的配置对象
+  // html-rspack-plugin 生成的参数
+  htmlPlugin: {
+    tags: {
+      headTags: HtmlTagObject[];
+      bodyTags: HtmlTagObject[];
+    };
+    files: {
+      publicPath: string;
+      js: Array<string>;
+      css: Array<string>;
+      favicon?: string;
+    };
+  };
+};
+```
+
+定义 HTML 模板中的参数，对应 [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin) 的 `templateParameters` 配置项。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/html/template.mdx

@@ -1,9 +1,15 @@
 ---
 title: template
+configName: html.template
 ---
 
 # html.template
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/template.md';
+- **类型：** `string | Function`
+- **默认值：**
 
-<Main />
+定义 HTML 模板的文件路径，可以是相对路径或绝对路径。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/html/title-by-entries.mdx

@@ -4,6 +4,34 @@ title: titleByEntries
 
 # html.titleByEntries
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/titleByEntries.md';
+- **类型：** `Record<string, string>`
+- **默认值：** `undefined`
+
+用于在多页面的场景下，为不同的页面设置不同的 `title`。
+
+整体用法与 `title` 一致，并且可以使用「入口名称」作为 key ，对各个页面进行单独设置。
+
+`titleByEntries` 的优先级高于 `title`，因此会覆盖 `title` 中设置的值。
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 `html.title` 的函数用法代替。
+:::
+
+### 示例
+
+```js
+export default {
+  html: {
+    title: 'ByteDance',
+    titleByEntries: {
+      foo: 'TikTok',
+    },
+  },
+};
+```
+
+重新编译后，可以看到:
+
+- 页面 `foo` 的 title 为 `TikTok`。
+- 其他页面的 title 为 `ByteDance`。
 
-<Main />

package/docs/zh/configure/app/html/title.mdx

@@ -1,9 +1,23 @@
 ---
 title: title
+configName: html.title
 ---
 
 # html.title
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/title.md';
+- **类型：** `string | Function`
+- **默认值：** `''`
 
-<Main />
+配置 HTML 页面的 title 标签，例如：
+
+```js
+export default {
+  html: {
+    title: 'example',
+  },
+};
+```
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/output/asset-prefix.mdx

@@ -1,9 +1,19 @@
 ---
 title: assetPrefix
+configName: output.assetPrefix
 ---
 
 # output.assetPrefix
 
-import Main from '@modern-js/builder-doc/docs/zh/config/output/assetPrefix.md';
+- **类型：** `string`
+- **默认值：** `'/'`
 
-<Main />
+在生产环境使用 CDN 部署时，可使用该选项设置静态资源的 URL 前缀。
+
+import OutputAssetPrefixExtend from '@site-docs/components/output-asset-prefix-extend';
+
+<OutputAssetPrefixExtend />
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />