docs(oxfmt): Updates for v0.21

.vitepress/config/en.ts

@@ -114,6 +114,10 @@ export const enConfig = defineLocaleConfig("root", {
               text: "Configuration",
               link: "/docs/guide/usage/formatter/config",
             },
+            {
+              text: "Ignoring",
+              link: "/docs/guide/usage/formatter/ignoring",
+            },
             {
               text: "Integration",
               link: "/docs/guide/usage/formatter/integration",

src/docs/guide/usage/formatter/config.md

@@ -39,43 +39,3 @@ For those properties, glob path overrides also work.
 By default, `oxfmt` automatically tries to find the nearest `.editorconfig` file from the current working directory.
 
 Unlike Prettier, Oxfmt does not respect `root = true` and does not merge nested `.editorconfig` files.
-
-## Ignore files
-
-By default, `oxfmt` automatically finds the `.gitignore` and `.prettierignore` files from the current working directory.
-
-Also you can specify your ignore file by `--ignore-path your.ignore` flag.
-In addition, `.oxfmtrc.json(c)` supports an `ignorePatterns` field.
-
-Defined paths are resolved based on where the file is located, not the current working directory.
-
-Global and nested ignores are not respected.
-
-VCS directories like `.git` and `.svn` are always ignored, also popular lock files are also ignored.
-
-### Ignore comments
-
-For JS/TS files, you can use a `prettier-ignore` comment.
-
-This takes effect on the next statement/expression.
-
-```js
-// prettier-ignore
-const a=42;
-
-/* prettier-ignore */
-const x=()=>{return      2;}
-
-<>
-  {/* prettier-ignore */}
-  <span     ugly  format=''   />
-</>;
-```
-
-(Not documented, but) Prettier supports trailing ignore comment too, but we don't support it to avoid a performance hit.
-Please update your code in that case.
-
-For non-JS files, the same convention as Prettier works.
-Please see Prettier's [documentation](https://prettier.io/docs/ignore#html).
-
-For TOML files, ignore comments are not supported.

src/docs/guide/usage/formatter/ignoring.md

@@ -0,0 +1,71 @@
+# Ignoring
+
+## Ignore files
+
+Oxfmt provides several ways to ignore files.
+
+### `.gitignore`
+
+Respects `.gitignore` in the current working directory and subdirectories.
+
+Does not respect global, exclude, or `.gitignore` in parent directories.
+Does not require `.git` directory to exist.
+
+Files listed here can still be formatted if explicitly specified.
+This is safe for use cases like `husky`, as ignored files are never staged.
+
+### `.prettierignore` / `oxfmtrc.ignorePatterns`
+
+These are formatter-specific ignore settings, separate from Git, and each operates within its own scope.
+
+`.prettierignore` is only read from the current working directory. For `.oxfmtrc.json(c)`, see [Configuration](./config).
+
+The syntax is the same as `.gitignore`, and paths are resolved relative to the directory containing the ignore file.
+
+Files ignored here cannot be formatted even if explicitly specified. This behavior is intended for use cases like `husky`.
+
+You can also specify custom ignore paths with `--ignore-path`, or use `!`-prefixed positional paths to exclude files.
+
+### VCS directories and `node_modules`
+
+Directories like `.git`, `.svn` and `.jj` are ignored by default.
+
+The `node_modules` directory is also ignored unless `--with-node_modules` flag is specified.
+
+If the current working directory is inside these directories, formatting is still possible.
+
+### Lock files
+
+Files like `package-lock.json` and `pnpm-lock.yaml` are ignored by default.
+
+These cannot be formatted even if explicitly specified.
+
+## Ignore comments
+
+For JS/TS files, you can use a `prettier-ignore` comment.
+
+This takes effect on the next statement/expression.
+
+```js
+// prettier-ignore
+const a=42;
+
+/* prettier-ignore */
+const x=()=>{return      2;}
+
+<>
+  {/* prettier-ignore */}
+  <span     ugly  format=''   />
+</>;
+```
+
+::: warning
+(Not documented, but) Prettier supports trailing ignore comment too.
+However, we don't support it to avoid a performance hit.
+Please update your code in that case.
+:::
+
+For non-JS files, the same convention as Prettier works.
+Please see Prettier's [documentation](https://prettier.io/docs/ignore#html).
+
+For TOML files, ignore comments are not supported.