feat: add bulk suppression docs

.vitepress/config/en.ts

@@ -83,6 +83,10 @@ export const enConfig = defineLocaleConfig("root", {
                   text: "Inline ignore comments",
                   link: "/docs/guide/usage/linter/ignore-comments",
                 },
+                {
+                  text: "Bulk suppressions",
+                  link: "/docs/guide/usage/linter/bulk-suppressions",
+                },
                 {
                   text: "Multi-file analysis",
                   link: "/docs/guide/usage/linter/multi-file-analysis",

src/docs/guide/usage/linter.md

@@ -136,6 +136,7 @@ See the [compatibility matrix](/compatibility) for detailed framework support.
 - [Automatic fixes](/docs/guide/usage/linter/automatic-fixes) to apply safe changes quickly.
 - [Ignore files](/docs/guide/usage/linter/ignore-files) to control which paths are linted.
 - [Inline ignore comments](/docs/guide/usage/linter/ignore-comments) for ignoring rules within a file.
+- [Bulk suppressions](/docs/guide/usage/linter/bulk-suppressions) for managing incremental adoption of new lint rules within existing codebaes.
 - [Multi-file analysis](/docs/guide/usage/linter/multi-file-analysis) for rules that require project-wide context such as import analysis like [no-cycle](/docs/guide/usage/linter/rules/import/no-cycle.html).
 - [Type-aware linting](/docs/guide/usage/linter/type-aware) for rules that require TypeScript type information.
 - [JS plugins](/docs/guide/usage/linter/js-plugins) (**alpha**) for compatibility with existing ESLint plugins.

src/docs/guide/usage/linter/bulk-suppressions.md

@@ -0,0 +1,60 @@
+---
+title: Bulk suppressions
+description: Suppress existing lint errors in bulk and fix them over time.
+---
+
+# Bulk suppressions
+
+Enabling a new lint rule in an existing codebase can often introduce many lint errors, which can be challenging to try and fix all at once if no fix is provided automatically. Bulk suppressions allow you to enable a new rule but ignore all existing violations initially so that you can gradually fix them over time. Errors in new code will still be reported, but existing violations will be suppressed until you are ready to address them.
+
+With bulk suppressions, you can incrementally improve the code quality over time of a codebase by enabling more lint rules, but without needing to fix all existing issues immediately.
+
+> [!WARNING]
+> Only lint errors will be suppressed. Rules configured to `warning` severity will NOT be suppressed. If you want warnings to be suppressed, consider setting their severity to `error` instead and then suppressing again.
+>
+> Since the intent of bulk suppressions is to allow linting to succeed even with existing errors, this means we only suppress issues that would cause the linting to report a failure exit code.
+
+## Suppressing errors
+
+To suppress all existing lint rule violations, you can use the `--suppress-all` option. We also recommend using the `--fix` option as well so that any automatic fixes are applied first.
+
+```sh
+oxlint --suppress-all
+```
+
+This will update (or create) the `oxlint-suppressions.json` in the current working directory and suppress all of the existing violations of lint rules in the codebase. The `oxlint-suppressions.json` file should be committed to source so that the linting behavior is consistent everywhere.
+
+## Resolving suppressed errors
+
+When a suppressed error is resolved, the linter will exit with failure and indicate:
+
+```
+  x There are suppressions that do not occur anymore.
+```
+
+This is because you now have fewer errors than you did previously. Congratulations! To resolve this error, run the linter again and use the `--prune-suppressions` option. This will remove all errors that no longer occur while linting.
+
+```sh
+oxlint --prune-suppressions
+```
+
+## Multiple suppression files / multiple projects
+
+Bulk suppressions in `oxlint` are designed to create and use a single `oxlint-suppressions.json` file. If you have a project that contains multiple packages (e.g., a "monorepo" setup) and want to have suppressions on a per-package basis, then we recommend running the linter once per package instead. That is, instead of running:
+
+```sh
+oxlint packages/
+```
+
+You would run:
+
+```sh
+oxlint . # in packages/package-a
+oxlint . # in packages/package-b
+```
+
+A task runner like [Vite+'s `vp run` command](https://viteplus.dev/guide/run) can do this automatically for you with the recursive flag (`-r`):
+
+```sh
+vp run -r lint # Run the `lint` script in each package
+```

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

@@ -560,6 +560,7 @@ export default defineConfig({
 
 - [Ignore files](/docs/guide/usage/linter/ignore-files): Ignore files and patterns, `.gitignore` and `.eslintignore` workflows, and symlink behavior.
 - [Inline ignore comments](/docs/guide/usage/linter/ignore-comments): Inline suppressions and scoped exceptions.
+- [Bulk suppressions](/docs/guide/usage/linter/bulk-suppressions): Suppress rules that have existing errors so you can incrementally fix them later.
 - [Nested configs](/docs/guide/usage/linter/nested-config): Monorepos and per-package configuration.
 - [Config file reference](/docs/guide/usage/linter/config-file-reference.html): Full schema and field documentation.
 - [CLI reference](/docs/guide/usage/linter/cli.html): Complete list of flags and output formats.