docs: add formatting guide

website/docs/en/guide/_meta.json

@@ -24,13 +24,18 @@
   },
   {
     "type": "file",
-    "name": "monorepo",
-    "label": "Monorepo"
+    "name": "testing",
+    "label": "Testing"
   },
   {
     "type": "file",
-    "name": "testing",
-    "label": "Testing"
+    "name": "formatting",
+    "label": "Formatting"
+  },
+  {
+    "type": "file",
+    "name": "monorepo",
+    "label": "Monorepo"
   },
   {
     "type": "dir-section-header",

website/docs/en/guide/cli/fmt.mdx

@@ -1,81 +1,42 @@
 # fmt
 
-The `rs fmt` command is built on [Prettier](https://prettier.io/). It processes files in parallel by default and uses the high-performance [Yuku](https://yuku.fyi/) parser for JavaScript and TypeScript, providing better performance than using Prettier directly.
+The `rs fmt` command formats files or checks whether they are formatted. For detailed usage, see [Formatting](../formatting).
 
 ## Usage
 
 ```bash
 rs fmt [options] [files/globs...]
 ```
 
-Pass files, directories, or glob patterns to select what to format. When no inputs are provided, `rs fmt` formats the current directory. `rs format` is an alias for `rs fmt`.
-
-## Options
-
-| Option                       | Description                                                                         |
-| ---------------------------- | ----------------------------------------------------------------------------------- |
-| `--write`                    | Write formatted files in place. This is the default mode.                           |
-| `--check`                    | Check formatting without writing files. Exits with code 1 when files are different. |
-| `--list-different`           | Print only unformatted paths. Exits with code 1 when files are different.           |
-| `--parallel-workers <count>` | Set the maximum number of formatting workers.                                       |
-| `-h, --help`                 | Display usage and option information.                                               |
-
-`--write`, `--check`, and `--list-different` are mutually exclusive.
+Pass files, directories, or glob patterns to choose what to format. When no paths are provided, `rs fmt` formats the current directory.
 
 Examples:
 
 ```bash
-# Format the current directory in place
+# Format files in the current directory
 rs fmt
 
 # Format specific files and directories
 rs fmt src package.json
 
-# Include and exclude files with quoted globs
-rs fmt "src/**/*.{js,ts}" "!src/generated/**"
-
 # Check formatting in CI
 rs fmt --check
 ```
 
-## File discovery
-
-Directory and glob discovery follows `.gitignore` files, skips binary files, and does not traverse version-control directories or `node_modules`. Files for which Prettier cannot infer a parser are skipped.
-
-Use [`ignorePatterns`](../configuration#define-fmt) for additional project-specific exclusions. Both positive and negative input globs are resolved from the current working directory.
-
-## Configuration
+`rs format` is an alias for `rs fmt`:
 
-Configure formatting through [`define.fmt()`](../configuration#define-fmt) in the [Rstack configuration file](/guide/configuration#configuration-file):
-
-```ts title="rstack.config.ts"
-import { define } from 'rstack';
-
-define.fmt({
-  printWidth: 100,
-  singleQuote: true,
-  sortPackageJson: true,
-  ignorePatterns: ['dist/**'],
-  overrides: [
-    {
-      files: '*.md',
-      options: {
-        proseWrap: 'always',
-      },
-    },
-  ],
-});
+```bash
+rs format
 ```
 
-`define.fmt()` accepts standard [Prettier options](https://prettier.io/docs/options) and the `overrides` field, plus these Rstack options:
-
-- `ignorePatterns`: Gitignore-compatible patterns relative to the directory containing `rstack.config.ts`.
-- `sortPackageJson`: Sort `package.json` fields before formatting. The default value is `false`.
-
-:::warning Configuration sources
-
-`rs fmt` does not load Prettier configuration files, `.prettierignore`, or `.editorconfig`. Move those settings and ignore rules into `define.fmt()`.
+## Options
 
-:::
+| Option                       | Description                                                                         |
+| ---------------------------- | ----------------------------------------------------------------------------------- |
+| `--write`                    | Write formatted files in place. This is the default mode.                           |
+| `--check`                    | Check formatting without writing files. Exits with code 1 when files are different. |
+| `--list-different`           | Print only unformatted paths. Exits with code 1 when files are different.           |
+| `--parallel-workers <count>` | Set the maximum number of formatting workers.                                       |
+| `-h, --help`                 | Display usage and option information.                                               |
 
-When using [Prettier plugins](https://prettier.io/docs/plugins), pass each plugin as a package name, file path, or URL. Imported plugin objects are not supported because formatting runs in workers. Package names and relative paths are resolved from the Rstack configuration directory.
+> `--write`, `--check`, and `--list-different` are mutually exclusive.

website/docs/en/guide/configuration.mdx

@@ -168,32 +168,18 @@ define.lint(async () => {
 
 ### `define.fmt()` \{#define-fmt}
 
-Defines the formatting configuration used by [`rs fmt`](./cli/fmt). Pass the configuration directly, or return it from a synchronous or asynchronous function.
-
-`define.fmt()` accepts standard [Prettier options](https://prettier.io/docs/options) and the `overrides` field. It also supports `ignorePatterns` for Gitignore-compatible exclusions and `sortPackageJson` for sorting `package.json` fields before formatting.
+Defines formatting settings for [`rs fmt`](./cli/fmt). Pass a configuration object directly, or use a synchronous or asynchronous function that returns one.
 
 ```ts title="rstack.config.ts"
 import { define } from 'rstack';
 
 define.fmt({
   printWidth: 100,
   singleQuote: true,
-  sortPackageJson: true,
-  ignorePatterns: ['dist/**'],
-  overrides: [
-    {
-      files: '*.md',
-      options: {
-        proseWrap: 'always',
-      },
-    },
-  ],
 });
 ```
 
-Ignore patterns, override patterns, and relative plugin paths are resolved from the directory containing the Rstack configuration file. Specify Prettier plugins as package names, paths, or URLs rather than imported plugin objects.
-
-`rs fmt` does not load Prettier configuration files, `.prettierignore`, or `.editorconfig`; keep all formatting options and ignore rules in `define.fmt()`.
+For detailed usage, see [Formatting](./formatting).
 
 ### `define.staged()` \{#define-staged}
 

website/docs/en/guide/formatting.mdx

@@ -0,0 +1,168 @@
+# Formatting
+
+import { PackageManagerTabs } from '@rspress/core/theme';
+
+Rstack CLI includes a formatter built on [Prettier](https://prettier.io/). Compared with running Prettier directly, `rs fmt` offers better performance in two ways:
+
+- **Parallel formatting**: `rs fmt` formats files concurrently in a worker pool.
+- **Yuku parser**: `rs fmt` uses the high-performance [Yuku](https://yuku.fyi/) parser by default for JavaScript, JSX, and TypeScript files.
+
+`rs fmt` supports Prettier options and plugins and adds built-in capabilities such as [sorting package.json fields](#sort-package-json).
+
+## Basic usage
+
+Run `rs fmt` without file arguments to format files in the current directory and save the changes:
+
+```bash
+rs fmt
+```
+
+Use `--check` to verify formatting without changing files:
+
+```bash
+rs fmt --check
+```
+
+See the [`rs fmt` CLI reference](./cli/fmt) for more command-line options.
+
+## Configuration
+
+Use [`define.fmt()`](./configuration#define-fmt) in `rstack.config.ts` to set formatting rules. It supports all [Prettier options](https://prettier.io/docs/options):
+
+```ts title="rstack.config.ts"
+import { define } from 'rstack';
+
+define.fmt({
+  printWidth: 100,
+  singleQuote: true,
+});
+```
+
+In addition to Prettier options and `overrides`, Rstack provides two options:
+
+- [`ignorePatterns`](#ignore-files): exclude files with Gitignore-compatible patterns.
+- [`sortPackageJson`](#sort-package-json): sort fields in `package.json` files. The default value is `false`.
+
+:::warning Prettier configuration files
+
+`rs fmt` does not read Prettier configuration files, `.prettierignore`, or `.editorconfig`. Keep formatting options and additional ignore rules in `define.fmt()`.
+
+:::
+
+## Formatting scope
+
+`rs fmt` determines the formatting scope from the paths passed on the command line. You can combine the following inputs:
+
+- **Files**: format only the specified files.
+- **Directories**: scan directories recursively and format supported files.
+- **Glob patterns**: match multiple paths, and prefix a pattern with `!` to exclude matches.
+
+When no paths are provided, `rs fmt` formats the current directory. All glob patterns are resolved from the current working directory. Quote them so that `rs fmt`, rather than the shell, expands them:
+
+```bash
+# Format a directory and a file
+rs fmt src package.json
+
+# Format JavaScript and TypeScript files, excluding generated files
+rs fmt "src/**/*.{js,ts}" "!src/generated/**"
+```
+
+When scanning directories or globs, `rs fmt` follows `.gitignore` rules, skips binary files, and does not traverse version-control directories or `node_modules`. It also skips files for which Prettier cannot infer a parser.
+
+`.gitignore` applies only when scanning directories and globs. It does not exclude files passed explicitly on the command line. To always exclude a file, use [`ignorePatterns`](#ignore-files).
+
+## Ignore files
+
+Use `ignorePatterns` to exclude files from formatting:
+
+```ts title="rstack.config.ts"
+import { define } from 'rstack';
+
+define.fmt({
+  ignorePatterns: ['dist/**', 'coverage/**', '**/generated/**'],
+});
+```
+
+Patterns follow Gitignore syntax and are resolved relative to the directory containing the Rstack configuration file. Because they are applied after the files are selected, they also exclude files passed explicitly on the command line.
+
+## Sort package.json fields \{#sort-package-json}
+
+Enable `sortPackageJson` to sort fields in each selected `package.json` with [`sort-package-json`](https://github.com/keithamus/sort-package-json):
+
+```ts title="rstack.config.ts"
+import { define } from 'rstack';
+
+define.fmt({
+  sortPackageJson: true,
+});
+```
+
+## Overrides
+
+Use the `overrides` field to set options for specific files. Each override supports these fields:
+
+- `files`: files or glob patterns to match.
+- `options`: formatting options applied to matching files.
+- `excludeFiles`: optional files or glob patterns to exclude.
+
+```ts title="rstack.config.ts"
+import { define } from 'rstack';
+
+define.fmt({
+  overrides: [
+    {
+      files: 'docs/**/*.md',
+      excludeFiles: 'docs/generated/**',
+      options: {
+        proseWrap: 'always',
+      },
+    },
+  ],
+});
+```
+
+### Pattern matching
+
+The `files` and `excludeFiles` patterns are resolved relative to the directory containing `rstack.config.ts`.
+
+In `files`, a pattern without `/` matches file names at any depth, while a pattern containing `/` matches relative paths. In this example, `*.md` matches Markdown files in any directory, while `scripts/**/*.js` matches paths relative to the configuration directory:
+
+```ts
+define.fmt({
+  overrides: [
+    { files: '*.md', options: { proseWrap: 'always' } },
+    { files: 'scripts/**/*.js', options: { singleQuote: true } },
+  ],
+});
+```
+
+### Merge order
+
+When multiple overrides match, they are applied in declaration order, so later values take precedence. Here, `README.md` matches both overrides, so the final `printWidth` is `80`:
+
+```ts
+define.fmt({
+  overrides: [
+    { files: '*.md', options: { printWidth: 100 } },
+    { files: 'README.md', options: { printWidth: 80 } },
+  ],
+});
+```
+
+## Prettier plugins
+
+To add formatting capabilities that are not built into Rstack, install the corresponding [Prettier plugin](https://prettier.io/docs/plugins) and add it to `plugins`. Plugins can be referenced by package name, file path, or URL. Package names and relative paths are resolved from the directory containing the Rstack configuration file.
+
+Because `rs fmt` loads plugins in workers, plugin objects cannot be passed directly. Reference each plugin by package name, path, or URL instead. For example, install and enable [`prettier-plugin-tailwindcss`](https://github.com/tailwindlabs/prettier-plugin-tailwindcss):
+
+<PackageManagerTabs command="install -D prettier-plugin-tailwindcss" />
+
+```ts title="rstack.config.ts"
+import { define } from 'rstack';
+
+define.fmt({
+  plugins: ['prettier-plugin-tailwindcss'],
+});
+```
+
+To enable a plugin only for specific files, add `plugins` to the `options` of an [`overrides`](#overrides) entry.

website/docs/zh/guide/_meta.json

@@ -24,13 +24,18 @@
   },
   {
     "type": "file",
-    "name": "monorepo",
-    "label": "Monorepo"
+    "name": "testing",
+    "label": "测试"
   },
   {
     "type": "file",
-    "name": "testing",
-    "label": "测试"
+    "name": "formatting",
+    "label": "格式化"
+  },
+  {
+    "type": "file",
+    "name": "monorepo",
+    "label": "Monorepo"
   },
   {
     "type": "dir-section-header",