docs: Improve documentation authenticity and clarity (#6046)

Copilot · chenjiahan · web-flow · commit b38d946b9423 · 2025-09-03T14:44:48.000+08:00
Co-authored-by: copilot-swe-agent[bot] &lt;198982749+Copilot@users.noreply.github.com&gt;
Co-authored-by: chenjiahan &lt;7237365+chenjiahan@users.noreply.github.com&gt;
Co-authored-by: neverland &lt;chenjiahan.jait@bytedance.com&gt;
diff --git a/website/docs/en/api/javascript-api/instance.mdx b/website/docs/en/api/javascript-api/instance.mdx
@@ -41,7 +41,7 @@ type Version = string;
 
 ### context.rootPath
 
-The root path of current build, corresponding to the `cwd` option of [createRsbuild](/api/javascript-api/core#creatersbuild) method.
+The root path of the current build, corresponding to the `cwd` option of the [createRsbuild](/api/javascript-api/core#creatersbuild) method.
 
 - **Type:**
 
@@ -172,7 +172,7 @@ type bundlerType = 'rspack' | 'webpack';
 
 ## rsbuild.build
 
-Perform a production mode build. This method will generate optimized production bundles and emit them to the output directory.
+Performs a production mode build. This method generates optimized production bundles and emits them to the output directory.
 
 - **Type:**
 
@@ -299,7 +299,7 @@ await rsbuild.build({
 
 ## rsbuild.startDevServer
 
-Start the local dev server. This method will:
+Starts the local dev server. This method will:
 
 1. Start a development server that serves your application.
 2. Watch for file changes and trigger recompilation.
@@ -429,7 +429,7 @@ await server.listen();
 
 ## rsbuild.preview
 
-Start a server to preview the production build locally. This method should be executed after [rsbuild.build](#rsbuildbuild).
+Starts a server to preview the production build locally. This method should be executed after [rsbuild.build](#rsbuildbuild).
 
 - **Type:**
 
@@ -510,7 +510,7 @@ await server.close();
 
 ## rsbuild.createCompiler
 
-Create an Rspack [Compiler](https://rspack.rs/api/javascript-api/compiler) instance. If there are multiple [environments](/config/environments) for this build, the return value is [MultiCompiler](https://rspack.rs/api/javascript-api/compiler#multicompiler).
+Creates an Rspack [Compiler](https://rspack.rs/api/javascript-api/compiler) instance. If there are multiple [environments](/config/environments) for this build, the return value is [MultiCompiler](https://rspack.rs/api/javascript-api/compiler#multicompiler).
 
 - **Type:**
 
@@ -528,7 +528,7 @@ const compiler = await rsbuild.createCompiler();
 
 ## rsbuild.addPlugins
 
-Register one or more Rsbuild plugins, which can be called multiple times.
+Registers one or more Rsbuild plugins, which can be called multiple times.
 
 This method needs to be called before compiling. If it is called after compiling, it will not affect the compilation result.
 
@@ -557,7 +557,7 @@ rsbuild.addPlugins([pluginFoo()], { environment: 'node' });
 
 ## rsbuild.getPlugins
 
-Get all the Rsbuild plugins registered in the current Rsbuild instance.
+Gets all the Rsbuild plugins registered in the current Rsbuild instance.
 
 - **Type:**
 
@@ -687,7 +687,7 @@ console.log(buildConfigs);
 
 ## rsbuild.inspectConfig
 
-Inspect and debug Rsbuild's internal configurations. It provides access to:
+Inspects and debugs Rsbuild's internal configurations. It provides access to:
 
 - The resolved Rsbuild configuration
 - The environment-specific Rsbuild configurations
diff --git a/website/docs/en/config/html/meta.mdx b/website/docs/en/config/html/meta.mdx
@@ -14,7 +14,7 @@ const defaultMeta = {
 };
 ```
 
-Configure the `<meta>` tag of the HTML.
+Configures the `<meta>` tags of the HTML.
 
 :::tip
 If the HTML template used in the current project already contains the charset or viewport meta tags, then the tags in the HTML template take precedence.
@@ -147,7 +147,7 @@ export default {
 
 ## Remove default value
 
-Setting the `value` of the `meta` object to `false` and the meta tag will not be generated.
+Setting the `value` of the `meta` object to `false` means the meta tag will not be generated.
 
 For example to remove the `viewport`:
 
diff --git a/website/docs/en/config/html/mount-id.mdx b/website/docs/en/config/html/mount-id.mdx
@@ -3,7 +3,7 @@
 - **Type:** `string`
 - **Default:** `'root'`
 
-By default, the `root` element is included in the HTML template for component mounting, and the element id can be modified through `mountId`.
+By default, the `root` element is included in the HTML template for component mounting. The element id can be modified through `mountId`.
 
 ```html
 <body>
@@ -46,4 +46,4 @@ ReactDOM.createRoot(domNode).render(<App />);
 
 ### Custom templates
 
-If you customized the HTML template, please make sure that the template contains `<div id="<%= mountId %>"></div>`, otherwise the `mountId` config will not take effect.
+If you've customized the HTML template, please make sure that the template contains `<div id="<%= mountId %>"></div>`, otherwise the `mountId` config will not take effect.
diff --git a/website/docs/en/config/output/emit-assets.mdx b/website/docs/en/config/output/emit-assets.mdx
@@ -3,13 +3,13 @@
 - **Type:** `boolean`
 - **Default:** `true`
 
-Control whether to emit static assets such as images, fonts, audio, video, etc.
+Controls whether to emit static assets such as images, fonts, audio, video, etc.
 
-In scenarios such as SSR, you may not need to emit duplicate static assets. Therefore, you can return `false` in `emitAssets` to avoid emitting assets.
+In scenarios such as SSR, you may not need to emit duplicate static assets. Therefore, you can set `emitAssets` to `false` to avoid emitting assets.
 
 ## Example
 
-For example, the following example will emit static assets when building web bundles, and avoid emitting when building node bundles.
+The following example will emit static assets when building web bundles, and avoid emitting when building node bundles.
 
 ```js
 export default {
diff --git a/website/docs/en/config/output/legal-comments.mdx b/website/docs/en/config/output/legal-comments.mdx
@@ -3,7 +3,7 @@
 - **Type:** `'linked' | 'inline' | 'none'`
 - **Default:** `'linked'`
 
-Configure how to handle legal comments.
+Controls how legal comments are handled in the build output.
 
 ## What are legal comments?
 
@@ -25,11 +25,11 @@ For example, the `LICENSE` comment in React:
 
 ## Optional values
 
-You can configure how to handle legal comments using these options:
+You can control how legal comments are handled using these options:
 
 ### `linked`
 
-Extract all legal comments to `*.LICENSE.txt` files and link to them with a comment.
+Extracts all legal comments to `*.LICENSE.txt` files and links to them with a comment.
 
 ```js title="rsbuild.config.js"
 export default {
@@ -43,7 +43,7 @@ export default {
 
 ### `inline`
 
-Preserve all legal comments in the original position. This may increase the size of the output bundles.
+Preserves all legal comments in their original position. This may increase the size of the output bundles.
 
 ```js title="rsbuild.config.js"
 export default {
@@ -55,7 +55,7 @@ export default {
 
 ### `none`
 
-Remove all legal comments.
+Removes all legal comments.
 
 ```js title="rsbuild.config.js"
 export default {
diff --git a/website/docs/en/config/output/minify.mdx b/website/docs/en/config/output/minify.mdx
@@ -17,7 +17,7 @@ type Minify =
 
 Controls code minification in production mode and configures minimizer options.
 
-By default, JS and CSS code are automatically minified in production mode to improve page performance. To disable minification for all code, set `minify` to `false`. Alternatively, control code minification behavior through detailed configuration of the `minify` option:
+By default, JS and CSS code are automatically minified in production mode to improve page performance. To disable minification entirely, set `minify` to `false`. You can also control specific minification behavior through the detailed `minify` options:
 
 :::tip
 Rsbuild uses [SWC](/guide/configuration/swc) to minify JS code and [Lightning CSS](/guide/styling/css-usage#lightning-css) to minify CSS code by default.
@@ -38,7 +38,7 @@ export default {
 ```
 
 :::tip
-This approach is used for debugging and troubleshooting. We do not recommend to disable code minification in production builds, as it will significantly degrade page performance.
+This is useful for debugging and troubleshooting. We do not recommend disabling code minification in production builds, as it will significantly degrade page performance.
 :::
 
 ## Options
@@ -162,14 +162,14 @@ export default {
 ```
 
 :::tip
-When you configure some options in [tools.lightningcssLoader](/config/tools/lightningcss-loader), `output.minify.cssOptions` will automatically inherit these options, which ensures that the CSS code transformation behavior in the development build is consistent with that in the production build.
+When you configure options in [tools.lightningcssLoader](/config/tools/lightningcss-loader), `output.minify.cssOptions` will automatically inherit these options, ensuring that CSS code transformation behavior in the development build is consistent with the production build.
 :::
 
 ## Switching minifier
 
 ### JS minifier
 
-If the default SWC minifier does not meet your needs, you can switch to other minifiers through the [tools.bundlerChain](/config/tools/bundler-chain) option.
+If the default SWC minifier doesn't meet your needs, you can switch to other minifiers using the [tools.bundlerChain](/config/tools/bundler-chain) option.
 
 For example, use [terser-webpack-plugin](https://github.com/terser/terser-webpack-plugin) to switch to Terser or esbuild.
 
diff --git a/website/docs/en/config/output/source-map.mdx b/website/docs/en/config/output/source-map.mdx
@@ -20,7 +20,7 @@ const defaultSourceMap = {
 };
 ```
 
-Configure whether to generate source map files and which source map format to generate.
+Configures whether to generate source map files and which source map format to generate.
 
 :::tip What is a source map
 Source map is an information file that stores the source code mapping relationship. It records each location of the compiled code and the corresponding pre-compilation location. With source map, you can directly view the source code when debugging compiled code.
diff --git a/website/docs/en/config/source/define.mdx b/website/docs/en/config/source/define.mdx
@@ -5,7 +5,7 @@
 
 Replaces variables in your code with other values or expressions at compile time. This is useful for enabling different behavior between development and production builds.
 
-Each key passed into the configuration is an identifier or multiple identifiers joined with `.`.
+Each key passed to the configuration represents an identifier or multiple identifiers joined with `.`.
 
 - If the value is a string, it will be used as a code fragment.
 - If the value is not a string, it will be stringified (including functions).
diff --git a/website/docs/en/guide/basic/output-files.mdx b/website/docs/en/guide/basic/output-files.mdx
@@ -1,12 +1,12 @@
 # Output files
 
-This section introduces the output file directory structure and how to control the output directory for different file types.
+This section introduces the output file directory structure and explains how to control the output directory for different file types.
 
 If you want to know how to deploy the build outputs of Rsbuild as a static site, please refer to [Deploy Static Site](/guide/basic/static-deploy).
 
 ## Default directory structure
 
-The default output directory structure is shown below. Output files are written to the `dist` directory of the current project.
+The default output directory structure is shown below. Output files are written to the `dist` directory in the current project.
 
 ```bash
 dist
@@ -38,7 +38,7 @@ In the filename, `[name]` represents the entry name for this file, such as `inde
 
 ## Development mode output
 
-In development mode, Rsbuild stores build outputs in memory on the dev server by default, rather than writing them to disk. This reduces filesystem operation overhead. Refer to [View Static Assets](/guide/basic/server#view-static-assets) to view all static assets generated in the current build.
+In development mode, Rsbuild stores build outputs in memory on the dev server by default, rather than writing them to disk. This reduces filesystem operation overhead. Refer to [View Static Assets](/guide/basic/server#view-static-assets) to see all static assets generated in the current build.
 
 To write output files to disk (typically used for inspecting build artifacts or configuring proxy rules for static assets), set the [dev.writeToDisk](/config/dev/write-to-disk) configuration to `true`:
 
@@ -80,7 +80,7 @@ dist
         └── qux.[hash].mp4
 ```
 
-Use the [output.distPath](/config/output/dist-path) config to write these static assets to a single directory, for example, to the `assets` directory:
+Use the [output.distPath](/config/output/dist-path) config to write these static assets to a single directory. For example, to organize them in an `assets` directory:
 
 ```ts
 export default {
@@ -116,7 +116,7 @@ dist
 └── [name].js
 ```
 
-Node.js outputs typically contain only JS files, without HTML or CSS. The JS file names do not include hash values.
+Node.js outputs typically contain only JS files, without HTML or CSS. The JS filenames do not include hash values.
 
 Modify the output path of Node.js files using the [environments](/config/environments) config.
 
@@ -144,7 +144,7 @@ export default {
 
 ## Flatten the directory
 
-For a flatter directory structure in the dist directory, set the directory to an empty string to flatten the generated directory.
+For a flatter directory structure, set any directory to an empty string to flatten the generated output structure.
 
 Here's an example:
 
diff --git a/website/docs/en/guide/framework/react.mdx b/website/docs/en/guide/framework/react.mdx
@@ -48,7 +48,7 @@ To use SVGR, you also need to register the [SVGR plugin](/plugins/list/plugin-sv
 
 Rsbuild uses React's official [Fast Refresh](https://npmjs.com/package/react-refresh) capability to perform component hot updates.
 
-Note that React Refresh requires components to be written according to the standards. Otherwise HMR may not work. You can use [eslint-plugin-react-refresh](https://github.com/ArnaudBarre/eslint-plugin-react-refresh) for validation.
+Note that React Refresh requires components to be written according to the standards, otherwise HMR may not work. You can use [eslint-plugin-react-refresh](https://github.com/ArnaudBarre/eslint-plugin-react-refresh) for validation.
 
 For example, if the hot update of the React component cannot take effect, or the state of the React component is lost after the hot update, it is usually because your React component uses an anonymous function. In the official practice of React Fast Refresh, it is required that the component cannot be an anonymous function, otherwise the state of the React component cannot be preserved after hot update.
 
diff --git a/website/docs/en/plugins/dev/index.mdx b/website/docs/en/plugins/dev/index.mdx
@@ -8,7 +8,7 @@ Rsbuild plugins are functions that can register hooks at different stages, liste
 
 Before developing a Rsbuild plugin, you may have been familiar with the plugin systems of tools such as webpack, Vite, esbuild, etc.
 
-Generally, Rsbuild's plugin API is similar to esbuild, and compared with webpack or Rspack plugins, Rsbuild's plugin API is simpler and easier to get started with.
+Rsbuild's plugin API is similar to esbuild's, and compared with webpack or Rspack plugins, Rsbuild's plugin API is simpler and easier to get started with.
 
 ```ts
 // esbuild plugin
@@ -37,7 +37,7 @@ class RspackExamplePlugin {
 }
 ```
 
-From a functional perspective, Rsbuild's plugin API mainly revolves around Rsbuild's operation process and build configuration and provides some hooks for extension. On the other hand, Rspack's plugin API is more complex and rich, capable of modifying every aspect of the bundling process.
+From a functional perspective, Rsbuild's plugin API mainly revolves around Rsbuild's operation process and build configuration, providing various hooks for extension. On the other hand, Rspack's plugin API is more complex and comprehensive, capable of modifying every aspect of the bundling process.
 
 Rspack plugins can be integrated into Rsbuild plugins. If the hooks provided by Rsbuild do not meet your requirements, you can also implement the functionality using Rspack plugin and register Rspack plugins in the Rsbuild plugin:
 
diff --git a/website/docs/en/plugins/list/plugin-svgr.mdx b/website/docs/en/plugins/list/plugin-svgr.mdx
@@ -4,7 +4,7 @@ import { SourceCode } from '@rspress/core/theme';
 
 <SourceCode href="https://github.com/web-infra-dev/rsbuild/tree/main/packages/plugin-svgr" />
 
-By default, Rsbuild will treat SVG files as static assets. For processing rules, please refer to: [Static assets](/guide/basic/static-assets).
+By default, Rsbuild treats SVG files as static assets. For processing rules, refer to: [Static assets](/guide/basic/static-assets).
 
 With the SVGR plugin, Rsbuild supports transforming SVG to React components via [SVGR](https://react-svgr.com/).
 
@@ -35,15 +35,15 @@ export default {
 
 ### Default usage
 
-After registering the plugin, when you import an SVG in a JavaScript file, if the imported path contains the `?react` suffix, Rsbuild will call SVGR to transform the SVG into a React component.
+After registering the plugin, when you import an SVG in a JavaScript file, if the imported path includes the `?react` suffix, Rsbuild will call SVGR to transform the SVG into a React component.
 
 ```jsx title="App.jsx"
 import Logo from './logo.svg?react';
 
 export const App = () => <Logo />;
 ```
 
-If the imported path does not contain the `?react` suffix, then the SVG will be treated as a normal static asset and you will get a URL string or base64 URL, see [Static assets](/guide/basic/static-assets).
+If the imported path doesn't include the `?react` suffix, then the SVG will be treated as a normal static asset and you will get a URL string or base64 URL, see [Static assets](/guide/basic/static-assets).
 
 ```js
 import logoURL from './static/logo.svg';
@@ -96,7 +96,7 @@ type PluginSvgrOptions = {
 
 ### svgrOptions
 
-Modify the options of SVGR, the passed object will be deep merged with the default value. See [SVGR - Options](https://react-svgr.com/docs/options/) for details.
+Modifies the options of SVGR, the passed object will be deep merged with the default value. See [SVGR - Options](https://react-svgr.com/docs/options/) for details.
 
 - **Type:** `import('@svgr/core').Config`
 - **Default:**
diff --git a/website/docs/zh/config/output/emit-assets.mdx b/website/docs/zh/config/output/emit-assets.mdx
@@ -5,7 +5,7 @@
 
 用于控制是否输出图片、字体、音频、视频等静态资源。
 
-在 SSR 等场景下，你可能不需要输出重复的静态资源，因此你可以在 `emitAssets` 返回 `false` 来避免资源输出。
+在 SSR 等场景下，你可能不需要输出重复的静态资源，因此你可以将 `emitAssets` 设置为 `false` 来避免资源输出。
 
 ## 示例
 
