docs: improve documentation for history api fallback

packages/core/src/types/config.ts

@@ -379,9 +379,33 @@ export type HistoryApiFallbackTo =
   | ((context: HistoryApiFallbackContext) => string);
 
 export type HistoryApiFallbackOptions = {
+  /**
+   * Specifies the default HTML file to return when the History API fallback is enabled.
+   * For example, if you set `historyApiFallback.index` to `main.html`, the server will
+   * automatically serve `main.html` as the fallback page when users access any unmatched
+   * routes.
+   * @default 'index.html'
+   */
   index?: string;
+  /**
+   * Override the default `Accepts:` headers that are queried when matching HTML content
+   * requests.
+   * @default ['text/html', '*\/*']
+   */
   htmlAcceptHeaders?: string[];
-  disableDotRule?: true;
+  /**
+   * By default, requests containing a dot (`.`) in the path are treated as direct file
+   * requests and are not redirected. Setting `disableDotRule` to `true` will disable this
+   * behavior and allow such requests to be redirected as well.
+   * @default false
+   */
+  disableDotRule?: boolean;
+  /**
+   * `rewrites` lets you customize how request paths are mapped to HTML files when
+   * a History API fallback occurs. These rules only apply when no static asset matches
+   * the request, meaning it has entered the fallback stage. Each rule is evaluated in
+   * order until a match is found and executed.
+   */
   rewrites?: {
     from: RegExp;
     to: HistoryApiFallbackTo;

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

@@ -39,7 +39,9 @@ Rsbuild will change the requested location to the [index](#index) you specify wh
 - **Type:** `string`
 - **Default:** `'index.html'`
 
-By setting `historyApiFallback.index` to `main.html`, when accessing the root path `/` or other routes that may result in a 404, the page will automatically redirect to `main.html`.
+Specifies the default HTML file to return when the History API fallback is enabled.
+
+For example, if you set `historyApiFallback.index` to `main.html`, the server will automatically serve `main.html` as the fallback page when users access any unmatched routes.
 
 ```ts title="rsbuild.config.ts"
 export default {
@@ -49,7 +51,6 @@ export default {
     },
   },
   server: {
-    htmlFallback: false,
     historyApiFallback: {
       index: '/main.html',
     },
@@ -70,22 +71,31 @@ type Rewrites = Array<{
 
 - **Default:** `[]`
 
-When your application contains multiple entries, you may need to redirect different paths to different pages. In this case, you can configure more flexible redirection rules through the `rewrites` option:
+`rewrites` lets you customize how request paths are mapped to HTML files when a History API fallback occurs.
+
+These rules only apply when no static asset matches the request, meaning it has entered the fallback stage. Each rule is evaluated in order until a match is found and executed.
 
 ```ts title="rsbuild.config.ts"
 export default {
   server: {
     historyApiFallback: {
       rewrites: [
+        // Redirect the root path to the landing page
         { from: /^\/$/, to: '/views/landing.html' },
+        // Return subpage.html for any path starting with /subpage
         { from: /^\/subpage/, to: '/views/subpage.html' },
+        // Return a custom 404 page for all other paths
         { from: /./, to: '/views/404.html' },
       ],
     },
   },
 };
 ```
 
+:::tip
+If you want to modify or forward requests outside of the fallback scenario, use the [server.proxy](/config/server/proxy) option to define proxy rules.
+:::
+
 ### htmlAcceptHeaders
 
 - **Type:** `string[]`

website/docs/en/guide/basic/server.mdx

@@ -70,7 +70,6 @@ export default {
     },
   },
   server: {
-    htmlFallback: false,
     historyApiFallback: {
       index: '/main.html',
     },

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

@@ -39,7 +39,9 @@ export default {
 - **类型：** `string`
 - **默认值：** `'index.html'`
 
-通过将 `historyApiFallback.index` 设置为 `main.html`，当访问根路径 `/` 或其他可能导致 404 的路由时，页面会自动重定向到 `main.html`。
+指定当启用 History API fallback 时返回的默认 HTML 文件。
+
+例如，设置 `historyApiFallback.index` 为 `main.html` 后，当用户访问未命中的路由时，服务器会自动返回 `main.html` 作为回退页面。
 
 ```ts title="rsbuild.config.ts"
 export default {
@@ -49,7 +51,6 @@ export default {
     },
   },
   server: {
-    htmlFallback: false,
     historyApiFallback: {
       index: '/main.html',
     },
@@ -70,22 +71,31 @@ type Rewrites = Array<{
 
 - **默认值：** `[]`
 
-当你的应用包含多个入口（entry）时，你可能需要将不同的访问路径重定向到不同的页面。此时，你可以通过 `rewrites` 选项来配置更灵活的重定向规则：
+`rewrites` 用于在 History API fallback 发生时，自定义请求路径与页面文件之间的映射。
+
+仅当请求未命中任何静态资源（即进入 fallback 阶段）时，这些规则才会被应用。所有规则会按照数组中的顺序依次匹配并执行。
 
 ```ts title="rsbuild.config.ts"
 export default {
   server: {
     historyApiFallback: {
       rewrites: [
+        // 将根路径重定向到 landing 页面
         { from: /^\/$/, to: '/views/landing.html' },
+        // 当访问 /subpage 开头的路径时，返回 subpage.html
         { from: /^\/subpage/, to: '/views/subpage.html' },
+        // 其他所有路径返回自定义的 404 页面
         { from: /./, to: '/views/404.html' },
       ],
     },
   },
 };
 ```
 
+:::tip
+如果你希望在非 fallback 场景下修改或转发请求，可以使用 [server.proxy](/config/server/proxy) 配置代理规则。
+:::
+
 ### htmlAcceptHeaders
 
 - **类型：** `string[]`

website/docs/zh/guide/basic/server.mdx

@@ -70,7 +70,6 @@ export default {
     },
   },
   server: {
-    htmlFallback: false,
     historyApiFallback: {
       index: '/main.html',
     },