docs: polish configuration documents (#3654)

website/docs/en/config/html/crossorigin.mdx

@@ -8,7 +8,7 @@ Set the [crossorigin](https://developer.mozilla.org/en-US/docs/Web/HTML/Attribut
 - If `true` is passed, it will automatically be set to `crossorigin="anonymous"`.
 - If `false` is passed, it will not set the `crossorigin` attr.
 
-### Example
+## Example
 
 ```js
 export default {
@@ -45,7 +45,7 @@ The `<style>` tag becomes:
 If the domain of static assets is the same as the current page, Rsbuild will not add the crossorigin="anonymous" attribute, as this attribute is not required for non-cross-domain scenario.
 :::
 
-### Optional Values
+## Optional Values
 
 `crossorigin` can the set to the following values:
 

website/docs/en/config/html/favicon.mdx

@@ -11,7 +11,11 @@ Set the favicon icon path for all pages, can be set as:
 
 After config this option, the favicon will be automatically copied to the dist directory during the compilation, and the corresponding `link` tag will be added to the HTML.
 
-### Example
+:::tip
+Rsbuild also provides [html.appIcon](/config/html/app-icon) to set the icon of the web application.
+:::
+
+## Example
 
 Set as a relative path:
 
@@ -53,7 +57,7 @@ After recompiling, the following tags are automatically generated in the HTML:
 <link rel="icon" href="/favicon.ico" />
 ```
 
-### Function Usage
+## Function Usage
 
 - **Type:**
 

website/docs/en/config/html/output-structure.mdx

@@ -5,7 +5,7 @@
 
 Define the directory structure of the HTML output files.
 
-### Example
+## Example
 
 By default, the structure of HTML files in the `dist` directory is `flat`:
 

website/docs/en/config/output/data-uri-limit.mdx

@@ -37,7 +37,7 @@ Detail:
 - `image`: The threshold of non-SVG images.
 - `media`: The threshold of media assets such as videos.
 
-### Example
+## Example
 
 - Inline all static assets less than 10KiB:
 

website/docs/en/config/output/externals.mdx

@@ -17,7 +17,7 @@ At build time, prevent some `import` dependencies from being packed into bundles
 
 > For more information, please see: [Rspack Externals](https://rspack.dev/config/externals).
 
-### Example
+## Example
 
 Exclude the `react-dom` dependency from the build product. To get this module at runtime, the value of `react-dom` will globally retrieve the `ReactDOM` variable.
 

website/docs/en/config/output/legal-comments.mdx

@@ -13,7 +13,7 @@ This behavior can be configured by using one of the following options:
 - `inline`: Preserve all legal comments in original position.
 - `none`: Remove all legal comments.
 
-### Example
+## Example
 
 Remove all legal comments:
 

website/docs/en/config/performance/preconnect.mdx

@@ -15,7 +15,7 @@ Specifies that the user agent should preemptively connect to the target resource
 
 Configuring this property will establish a connection with the server. If the site is HTTPS, this process includes DNS resolution, TCP connection establishment, and TLS handshake. Combining Preconnect and DnsPrefetch can further reduce the delay of cross-domain requests.
 
-### Example
+## Example
 
 ```js
 export default {
@@ -24,3 +24,9 @@ export default {
   },
 };
 ```
+
+The generated HTML tag is:
+
+```html
+<link ref="preconnect" href="https://example.com" />
+```

website/docs/en/config/performance/profile.mdx

@@ -10,7 +10,7 @@ After enabled:
 - Rsbuild will auto-generate `dist/stats.json` file through [bundle analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer).
 - Rspack will include the build time information when generating stats.json or other statistics files.
 
-### Example
+## Example
 
 ```js
 export default {
@@ -22,6 +22,6 @@ export default {
 
 When enabled, Rspack generates a JSON file with some statistics about the module that includes information about timing information for each module.
 
-### Guide
+## Guide
 
 Please refer to the [Build Profiling](/guide/optimization/build-performance#nodejs-profiling) section for more methods to analyze build performance.

website/docs/en/config/security/nonce.mdx

@@ -10,7 +10,7 @@ type Nonce = string;
 
 Adding a `nonce` attribute to the scripts resources introduced for HTML. This allows the browser to determine whether the script can be executed when it parses inline scripts with matching nonce values.
 
-#### Introduce nonce
+## What is nonce
 
 The nonce mechanism plays a crucial role in Content Security Policy (CSP), enhancing webpage security. It allows developers to define a unique and random string value, i.e., nonce, for inline `<script>` tags and `<style>` tags within CSP.
 
@@ -21,7 +21,7 @@ For more information about nonce, you can refer to:
 - [nonce - MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce)
 - [webpack - Content Security Policies](https://webpack.js.org/guides/csp/)
 
-### Example
+## Example
 
 By default, `nonce` is not enabled by Rsbuild, you can define this value based on your needs:
 
@@ -35,7 +35,7 @@ export default {
 
 Typically, we can define a fixed value in the project, and replace it with a random value on downstream servers such as Nginx, Web Server, gateway, etc.
 
-### Scope of Effect
+## Scope of Effect
 
 The `security.nonce` config adds the nonce attribute to the following tags:
 

website/docs/en/config/security/sri.mdx

@@ -13,7 +13,7 @@ type SriOptions = {
 
 Adding an `integrity` attribute to `<script>` and `<link rel="stylesheet">` tags introduced by HTML allows the browser to verify the integrity of the introduced resource, thus preventing tampering with the downloaded resource.
 
-## SRI
+## What is SRI
 
 Subresource Integrity (SRI) is a security feature that enables browsers to verify that resources they fetch (for example, from a CDN) are delivered without unexpected manipulation. It works by allowing you to provide a cryptographic hash that a fetched resource must match.
 

website/docs/en/config/server/base.mdx

@@ -6,7 +6,7 @@
 
 `server.base` is used to configure the [base path](/guide/basic/server#base-path) of the server.
 
-### Example
+## Example
 
 By default, the base path of the server is `/`, and users can access `index.html` through http://localhost:3000.
 
@@ -20,7 +20,7 @@ export default {
 };
 ```
 
-### The URL prefix of static assets
+## URL prefix of assets
 
 By default, [dev.assetPrefix](/config/dev/asset-prefix) and [output.assetPrefix](/config/output/asset-prefix) will read the value of `server.base` as the default value.
 

website/docs/en/config/server/history-api-fallback.mdx

@@ -5,7 +5,7 @@
 
 When Rsbuild's default [page routing](/guide/basic/server#page-routing) behavior cannot meet your needs, for example, if you want to be able to access `main.html` when accessing `/`, you can set it up using `server.historyApiFallback`.
 
-### Example
+## Example
 
 Set `historyApiFallback.index` to `main.html`, then `main.html` can be accessed when accessing `/` or other routes that would otherwise 404.
 

website/docs/en/config/server/open.mdx

@@ -19,7 +19,7 @@ type Open =
 
 > You can also use the [--open](/guide/basic/cli#opening-page) option of Rsbuild CLI to open the pages. When using `server.open` and `--open` at the same time, `--open` takes precedence.
 
-### Example
+## Example
 
 `server.open` can be set to the following values.
 
@@ -73,7 +73,7 @@ export default {
 };
 ```
 
-### Port placeholder
+## Port placeholder
 
 The port number that Rsbuild server listens on may change. For example, if the port is in use, Rsbuild will automatically increment the port number until it finds an available port.
 
@@ -90,7 +90,7 @@ export default {
 };
 ```
 
-### Open the specified browser
+## Open the specified browser
 
 Rsbuild by default will open the page in the system's default browser.
 
@@ -115,7 +115,7 @@ BROWSER="Google Chrome Canary" npx rsbuild dev --open
 You can set `BROWSER` in the local [.env.local](/guide/advanced/env-vars#env-file) file, which helps avoid impacting other developers.
 :::
 
-### Callback
+## Callback
 
 By using `open.before`, you can trigger a callback function before opening the page.
 

website/docs/en/config/server/port.mdx

@@ -9,7 +9,7 @@ By default, Rsbuild Server listens on port `3000` and automatically increments t
 
 You can use `server.port` or the `--port` CLI param to set the port number (The priority of `--port` option is higher than `server.port`).
 
-### Example
+## Example
 
 Set the port to `3000`:
 

website/docs/en/config/server/strict-port.mdx

@@ -7,7 +7,7 @@ When a port is occupied, Rsbuild will automatically increment the port number un
 
 Set `strictPort` to `true` and Rsbuild will throw an exception when the port is occupied.
 
-### Example
+## Example
 
 ```ts
 export default {

website/docs/en/config/source/define.mdx

@@ -14,7 +14,7 @@ Each key passed into options is an identifier or multiple identifiers joined wit
 
 > For more usage, please refer to [Using define](/guide/advanced/env-vars#using-define) and [Rspack - DefinePlugin](https://rspack.dev/plugins/webpack/define-plugin).
 
-### Example
+## Example
 
 ```js
 export default {
@@ -26,7 +26,7 @@ export default {
       TWO: '1 + 1',
       'typeof window': JSON.stringify('object'),
       'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
-      'import.meta': { test: undefined },
+      'import.meta.test': JSON.stringify('foo'),
     },
   },
 };

website/docs/zh/config/html/crossorigin.mdx

@@ -8,7 +8,7 @@
 - 当传入 `true` 时，它会被自动设置为 `crossorigin="anonymous"`。
 - 当传入 `false` 时，它不会设置 `crossorigin` 属性。
 
-### 示例
+## 示例
 
 ```js
 export default {
@@ -45,7 +45,7 @@ export default {
 如果静态资源的域名和当前页面的域名一致，那么 Rsbuild 将不会添加 crossorigin="anonymous" 属性，因为非跨域情况下不需要此属性。
 :::
 
-### 可选值
+## 可选值
 
 `crossorigin` 可以被设置为以下几个值：
 

website/docs/zh/config/html/favicon.mdx

@@ -11,7 +11,11 @@
 
 配置该选项后，在编译过程中会自动将图标拷贝至 dist 目录下，并在 HTML 中添加相应的 `link` 标签。
 
-### 示例
+:::tip
+Rsbuild 还提供了 [html.appIcon](/config/html/app-icon) 来设置 Web 应用的图标。
+:::
+
+## 示例
 
 设置为相对路径：
 
@@ -53,7 +57,7 @@ export default {
 <link rel="icon" href="/favicon.ico" />
 ```
 
-### 函数用法
+## 函数用法
 
 - **类型：**
 

website/docs/zh/config/html/output-structure.mdx

@@ -5,7 +5,7 @@
 
 用于定义 HTML 产物文件的目录结构。
 
-### 示例
+## 示例
 
 默认情况下，HTML 产物在 `dist` 目录下的结构为 `flat`：
 

website/docs/zh/config/output/data-uri-limit.mdx

@@ -37,7 +37,7 @@ const defaultDatUriLimit = {
 - `image`：表示非 SVG 图片的体积阈值。
 - `media`：表示视频等媒体资源的体积阈值。
 
-### 示例
+## 示例
 
 - 内联小于 10KiB 的所有静态资源：
 

website/docs/zh/config/output/externals.mdx

@@ -17,7 +17,7 @@ type Externals =
 
 > 更多用法供参考：[Rspack Externals](https://rspack.dev/zh/config/externals)。
 
-### 示例
+## 示例
 
 将 `react-dom` 依赖从构建产物中剔除。为了在运行时获取这个模块, `react-dom` 的值将全局检索 `ReactDOM` 变量。
 

website/docs/zh/config/output/legal-comments.mdx

@@ -13,7 +13,7 @@ legal comment 是 JS 或 CSS 文件中的一些特殊注释，这些注释包含
 - `inline`：保留所有 legal comments。
 - `none`：移除所有 legal comments。
 
-### 示例
+## 示例
 
 移除所有 legal comments。
 

website/docs/zh/config/performance/preconnect.mdx

@@ -15,7 +15,7 @@ interface PreconnectOption {
 
 配置该属性会预先建立与服务器的连接，如果站点是 HTTPS 的，则此过程包括 DNS 解析，建立 TCP 连接以及执行 TLS 握手。将 Preconnect 和 DnsPrefetch 结合使用可进一步减少跨域请求的延迟。
 
-### 示例
+## 示例
 
 ```js
 export default {
@@ -24,3 +24,9 @@ export default {
   },
 };
 ```
+
+生成的 HTML 标签如下：
+
+```html
+<link ref="preconnect" href="https://example.com" />
+```

website/docs/zh/config/performance/profile.mdx

@@ -10,7 +10,7 @@
 - Rsbuild 会通过 [bundle analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) 自动生成 `dist/stats.json` 文件。
 - Rspack 在生成 stats.json 等统计文件时，会将构建的耗时信息也包含进去。
 
-### 示例
+## 示例
 
 ```js
 export default {
@@ -20,6 +20,6 @@ export default {
 };
 ```
 
-### 指南
+## 指南
 
 请参考 [构建性能分析](/guide/optimization/build-performance#nodejs-profiling) 章节来了解更多分析构建性能方法。

website/docs/zh/config/security/nonce.mdx

@@ -10,7 +10,7 @@ type Nonce = string;
 
 为 HTML 所引入的脚本资源添加随机属性值 nonce，使浏览器在解析到带有匹配 nonce 值的内联脚本时，能判断该脚本是否能执行。
 
-#### nonce 介绍
+## 什么是 nonce
 
 nonce 机制在 Content Security Policy（CSP，内容安全策略）中起到关键作用，用于提升网页安全性。其允许开发者在 CSP 中为内联 `<script>` 标签和 `<style` 标签定义一个唯一且随机的字符串值，即 `nonce`。
 
@@ -21,7 +21,7 @@ nonce 机制在 Content Security Policy（CSP，内容安全策略）中起到
 - [nonce - MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce)
 - [webpack - Content Security Policies](https://webpack.js.org/guides/csp/)
 
-### 示例
+## 示例
 
 默认情况下，Rsbuild 不会开启 `nonce`，你可以按照需求定义该值：
 
@@ -35,7 +35,7 @@ export default {
 
 通常，我们可以在项目中可以定义一个固定值，并在 Nginx、Web Server、网关等响应下游的服务器上，统一替换成随机值。
 
-### 生效范围
+## 生效范围
 
 `security.nonce` 选项会为以下标签添加 nonce 属性：
 

website/docs/zh/config/security/sri.mdx

@@ -13,7 +13,7 @@ type SriOptions = {
 
 为 HTML 所引入的 `<script>` 和 `<link rel="stylesheet">` 标签添加完整性属性 —— `integrity`，使浏览器能够验证引入资源的完整性，以此防止下载的资源被篡改。
 
-## 介绍
+## 什么是 SRI
 
 子资源完整性 Subresource Integrity（SRI）是专门用来校验资源的一种方案，它读取资源标签中的 integrity 属性，将其中的信息摘要值，和资源实际的信息摘要值进行对比，如果发现无法匹配，那么浏览器就会拒绝执行资源。