docs: add guide for filename template string (#3138)

e2e/cases/html/filename-hash/index.test.ts

@@ -2,7 +2,27 @@ import { join } from 'node:path';
 import { build, globContentJSON } from '@e2e/helper';
 import { expect, test } from '@playwright/test';
 
-test('should allow to generate HTML with filename hash', async () => {
+test('should allow to generate HTML with filename hash using filename.html', async () => {
+  await build({
+    cwd: __dirname,
+    rsbuildConfig: {
+      output: {
+        filename: {
+          html: '[name].[contenthash:8].html',
+        },
+      },
+    },
+  });
+
+  const outputs = await globContentJSON(join(__dirname, 'dist'));
+  const htmlFilename = Object.keys(outputs).find((item) =>
+    item.endsWith('.html'),
+  );
+
+  expect(/index.\w+.html/.test(htmlFilename!)).toBeTruthy();
+});
+
+test('should allow to generate HTML with filename hash using tools.htmlPlugin', async () => {
   await build({
     cwd: __dirname,
     rsbuildConfig: {

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

@@ -48,7 +48,7 @@ After the production build, Rsbuild will add a hash in the middle of the filenam
 
 The following are the details of each filename:
 
-- `html`: The name of the HTML file, only supports the `[name]` placeholder.
+- `html`: The name of the HTML file.
 - `js`: The name of the JavaScript files.
 - `css`: The name of the CSS files.
 - `svg`: The name of the SVG images.
@@ -81,6 +81,26 @@ Usually, Rsbuild only set the filename hash in the production mode (i.e., when `
 If you set the filename hash in the development mode, it may cause HMR to fail (especially for CSS files). This is because every time the file content changes, the hash value changes, preventing bundler from reading the latest file content.
 :::
 
+## Template Strings
+
+In the value of `output.filename`, you can use template strings to dynamically generate file names.
+
+Common template strings include:
+
+- `[name]` - entry name, which is the key of [source.entry](/config/source/entry).
+- `[contenthash]` - hash value generated based on file content.
+- `[contenthash:<length>]` - hash value generated based on file content, with specified hash length.
+- `[ext]` - file extension, including the dot.
+
+> For more template strings, refer to [Rspack - Template String](https://rspack.dev/config/output#template-string).
+
+:::tip
+
+- `filename.html` can only use certain template strings like `[name]` and `[contenthash:<length>]`.
+- `filename.js` and `filename.css` do not support `[ext]`.
+
+:::
+
 ## Filename of Async Modules
 
 When you import a module via dynamic import, the module will be bundled into a single file, and its default naming rules are as follows:

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

@@ -48,7 +48,7 @@ const prodDefaultFilename = {
 
 下面是各个文件类型的说明：
 
-- `html`：表示 HTML 文件的名称，仅支持 `[name]` 占位符。
+- `html`：表示 HTML 文件的名称。
 - `js`：表示 JavaScript 文件的名称。
 - `css`：表示 CSS 样式文件的名称。
 - `svg`：表示 SVG 图片的名称。
@@ -81,6 +81,26 @@ export default {
 如果你在开发模式下设置了文件名的 hash，那么可能会导致热更新不生效（尤其是 CSS 文件）。这是因为每次文件内容变化时，都会引起 hash 变化，导致打包工具无法读取到最新的文件内容。
 :::
 
+## 模板字符串
+
+在 `output.filename` 的值中，你可以使用模板字符串来动态生成文件名。
+
+常用的模板字符串有：
+
+- `[name]` - entry 名称，即 [source.entry](/config/source/entry) 的 key。
+- `[contenthash]` - 基于文件内容生成的 hash 值。
+- `[contenthash:<length>]` - 基于文件内容生成的 hash 值，并指定 hash 长度。
+- `[ext]` - 文件后缀名，包含点号。
+
+> 更多模板字符串可以参考 [Rspack - Template String](https://rspack.dev/config/output#template-string)。
+
+:::tip
+
+- `filename.html` 只能使用部分模板字符串，如 `[name]`、`[contenthash:<length>]`。
+- `filename.js` 和 `filename.css` 不支持 `[ext]`。
+
+:::
+
 ## 异步模块文件名
 
 当你在代码中通过 dynamic import 的方式引入模块时，该模块会被单独打包成一个文件，它默认的命名规则如下：