docs: Rework a few more oxlint docs pages

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

@@ -1,11 +1,17 @@
 ---
-title: Setup CI
-description: Run Oxlint in CI.
+title: Setup CI and other integrations
+description: Run Oxlint in CI or as a git hook.
 ---
 
-# Setup CI
+# Setup CI and other integrations
 
-## GitHub Actions
+You can - and should - setup your CI pipeline to run Oxlint and fail the build on lint errors.
+
+This page also covers other integrations you may want to include, like git pre-commit hooks.
+
+## CI
+
+### GitHub Actions
 
 Create `.github/workflows/oxlint.yml`:
 
@@ -34,8 +40,24 @@ jobs:
       - run: pnpm run lint --deny-warnings # given package.json scripts "lint": "oxlint"
 ```
 
+## Git hooks
+
+### lint-staged
+
+For JS/TS projects using [lint-staged](https://github.com/lint-staged/lint-staged), you can set up oxlint to run pre-commit as follows:
+
+```json
+{
+  "lint-staged": {
+    "*.{js,jsx,ts,tsx,mjs,cjs}": "pnpm run lint"
+  }
+}
+```
+
 ### pre-commit
 
+If you use [pre-commit](https://pre-commit.com/) to manage git hooks, you can set up Oxlint as follows:
+
 ```yaml [.pre-commit-hooks.yaml]
 repos:
   - repo: https://github.com/oxc-project/mirrors-oxlint
@@ -45,10 +67,12 @@ repos:
         verbose: true
 ```
 
+## Other integrations
+
 ### Unplugin
 
-https://www.npmjs.com/package/unplugin-oxlint
+Unplugin is supported via a [third-party package](https://www.npmjs.com/package/unplugin-oxlint)
 
 ### Vite plugin
 
-https://www.npmjs.com/package/vite-plugin-oxlint
+A Vite plugin is supported via a [third-party package](https://www.npmjs.com/package/vite-plugin-oxlint)

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

@@ -17,7 +17,7 @@ To generate a starter config in the current directory:
 oxlint --init
 ```
 
-Oxlint automatically looks for a `.oxlintrc.json` in the current working directory. You can also pass a config explicitly:
+Oxlint automatically looks for a `.oxlintrc.json` in the current working directory. You can also pass a config explicitly (note that this will disable nested config lookup):
 
 ```sh
 oxlint -c ./oxlintrc.json
@@ -27,8 +27,8 @@ oxlint --config ./oxlintrc.json
 
 Notes:
 
-- Only `.json` config files are supported, and configuration files support comments (JSONC).
-- The configuration format aims to be compatible with ESLint v8 (`eslintrc.json`).
+- Only `.json` config files are supported, but oxlint configuration files support comments (like jsonc).
+- The configuration format aims to be compatible with ESLint v8's format (`eslintrc.json`).
 
 A minimal configuration looks like this:
 
@@ -102,7 +102,7 @@ To configure rule options, use an array:
 }
 ```
 
-All available rules are listed in the [Rules reference](/docs/guide/usage/linter/rules).
+All available rules, and their configuration options, are listed in the [Rules reference](/docs/guide/usage/linter/rules).
 
 ### Override severity from the CLI
 
@@ -176,18 +176,21 @@ For plugin details and CLI flags such as `--import-plugin`, see [Native Plugins]
 
 ## Configure JS plugins (experimental)
 
-Oxlint also supports JavaScript plugins via `jsPlugins`. This is intended for compatibility and advanced integrations.
+Oxlint also supports JavaScript plugins via `jsPlugins`. This is intended for compatibility with existing ESLint plugins and advanced integrations.
 
 Notes:
 
 - JS plugins are experimental and not subject to semver.
 - JS plugins are not supported in the language server at present.
 
-JS plugins can be declared as strings or as objects with an alias:
+JS plugins can be declared as strings, or as objects with an alias:
 
 ```jsonc
 {
-  "jsPlugins": [{ "name": "my-eslint-react", "specifier": "eslint-plugin-react" }],
+  "jsPlugins": [
+    "eslint-plugin-playwright",
+    { "name": "my-eslint-react", "specifier": "eslint-plugin-react" },
+  ],
 }
 ```
 
@@ -212,6 +215,7 @@ Example:
 
 ```jsonc
 {
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
   "rules": {
     "no-console": "error",
   },

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

@@ -39,7 +39,7 @@ Create `.vscode/extensions.json`:
 }
 ```
 
-2. Enable fix on save (optional).
+2. Enable fix-on-save (optional).
 
 Add to `.vscode/settings.json`:
 
@@ -51,6 +51,18 @@ Add to `.vscode/settings.json`:
 }
 ```
 
+3. Enable type-aware linting (optional).
+
+If you'd like to use type-aware rules and show type-related lint violations, ensure that `typeAware` is set to `true` in your VS Code settings (`.vscode/settings.json`):
+
+```jsonc
+{
+  "oxc.typeAware": true,
+}
+```
+
+You also need to ensure `oxlint-tsgolint` is installed in your project. See [the type-aware linting docs](/docs/guide/usage/linter/type-aware) for more details.
+
 ### Usage and configuration reference
 
 - [https://github.com/oxc-project/oxc/tree/main/editors/vscode](https://github.com/oxc-project/oxc/tree/main/editors/vscode)

src/docs/guide/usage/linter/ignore-comments.md

@@ -11,17 +11,17 @@ Oxlint supports line comments (`//`) and block comments (`/* */`). Comments must
 
 ## oxlint-disable
 
-Disable one or more rules until the end of the file, or until they are re enabled.
+Disable one or more rules until the end of the file, or until they are re-enabled.
 
 ```js
-// Disable Oxlint for the rest of the file
+// Disable all Oxlint rules for the rest of the file
 /* oxlint-disable */
 
 // Disable a single rule in this file
 /* oxlint-disable no-console */
 
 // Disable multiple rules in this file
-/* oxlint-disable no-console, no-alert */
+/* oxlint-disable no-console, typescript/no-floating-promises */
 ```
 
 ## oxlint-enable
@@ -44,17 +44,9 @@ console.log("Hello, world!"); // oxlint-disable-line no-console
 console.log(x++); // oxlint-disable-line no-console, no-plusplus
 ```
 
-## oxlint-enable-line
-
-Enable one or more rules on the current line.
-
-```js
-// oxlint-enable-line no-console
-```
-
 ## oxlint-disable-next-line
 
-Disable one or more rules on the line following the comment, then re enable them automatically.
+Disable one or more rules on the line following the comment, then re-enables them for subsequent lines.
 
 ```js
 // oxlint-disable-next-line no-console
@@ -65,14 +57,6 @@ console.log(x++); // not allowed because the previous comment only applied to th
 console.log("Hello, world!"); // allowed
 ```
 
-## oxlint-enable-next-line
-
-Enable one or more rules on the line following the comment, then re enable automatically.
-
-```js
-// oxlint-enable-next-line no-console
-```
-
 ## ESLint compatibility
 
 For compatibility with existing ESLint codebases, the same keywords are supported with `oxlint` replaced by `eslint`, such as `/* eslint-disable */` and `// eslint-disable-next-line`.

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

@@ -42,7 +42,9 @@ Configuration files are not automatically merged. A config in a child directory
 
 Command line options override configuration files, regardless of whether they come from a parent or child directory.
 
-Passing `--config` disables nested config lookup and applies a single configuration file.
+Passing an explicit config file location using `-c` or `--config` disables nested config lookup, and Oxlint will only use that single configuration file.
+
+You can also disable nested configs with the `--disable-nested-configs` flag.
 
 ## Monorepo pattern: share a base config with extends
 

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

@@ -5,21 +5,35 @@ description: Enable built in plugin rule sets and extend Oxlint with ESLint comp
 
 # Built-in Plugins
 
-Oxlint includes built in implementations of many popular ESLint plugin rule sets. Most rules in the `recommended` configs are already implemented, so you can get useful results without extra setup.
+Oxlint includes built-in implementations of many popular ESLint plugin rule sets. Most rules in the `recommended` configs are already implemented, so you can get useful results without extra setup.
 
-Oxlint also supports plugins written in JavaScript with an ESLint compatible API. See [JS Plugins](./js-plugins.md).
+Oxlint also supports plugins written in JavaScript with an ESLint-compatible API. See [JS Plugins](./js-plugins.md).
 
 ## What a plugin means in Oxlint
 
 A plugin is a named group of rules. Enabling a plugin makes its rules available, and category flags control which rules are enabled and at what severity.
 
-If you are migrating from ESLint, plugins map to the ecosystems you already know, such as import, react, jsx a11y, jest, unicorn, and more.
+If you are migrating from ESLint, plugins map to the ecosystems you already know, such as import, react, jsx-a11y, jest, unicorn, and more.
 
 ## Enable a plugin
 
+It is **strongly recommended** to use a config file to enable plugins, as it makes it considerably easier to manage and share with other developers on a project.
+
+### Enable in a config file
+
+You can also enable plugins in `.oxlintrc.json` using the `plugins` field:
+
+```json
+{
+  "plugins": ["import"]
+}
+```
+
+Setting `plugins` **overwrites the default plugin set**. The list should include every plugin you want enabled.
+
 ### Enable with the CLI
 
-Enable a plugin using a `--<plugin-name>-plugin` flag.
+You can also enable a plugin using a `--<plugin-name>-plugin` CLI flag.
 
 Example, enable the import plugin:
 
@@ -39,19 +53,21 @@ Correctness rules are enabled by default.
 
 Tip: run `oxlint --help` to see the full list of plugin flags.
 
-### Enable in a config file
+## Disable default plugins
 
-You can also enable plugins in `.oxlintrc.json` using the `plugins` field:
+### Disable default plugins in a config file
+
+To disable all default plugins in a config file, set `plugins` to an empty array:
 
 ```json
 {
-  "plugins": ["import"]
+  "plugins": []
 }
 ```
 
-Setting `plugins` overwrites the default plugin set. The list should include every plugin you want enabled.
+This disables all default plugins and uses only the base rule set.
 
-## Disable default plugins
+### Disable default plugins with the CLI
 
 Several plugins are enabled by default. You can disable a default plugin with `--disable-<plugin-name>-plugin`.
 
@@ -61,46 +77,34 @@ Example, disable unicorn:
 oxlint --disable-unicorn-plugin
 ```
 
-Only default plugins support being disabled. Non default plugins can simply be omitted.
-
-### Disable default plugins in a config file
-
-To disable all default plugins in a config file, set `plugins` to an empty array:
-
-```json
-{
-  "plugins": []
-}
-```
-
-This disables all default plugins and uses only the base rule set.
+Only default plugins support being disabled. Non-default plugins can simply be omitted.
 
 ## Supported plugins
 
-This table lists the built in plugins and where they come from.
-
-| Plugin name  | Default | Source                                                                                                                   |
-| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `eslint`     | Yes     | ESLint core rules                                                                                                        |
-| `typescript` | Yes     | TypeScript rules from the typescript eslint ecosystem. Type aware rules are available in alpha using the type aware mode |
-| `unicorn`    | Yes     | eslint plugin unicorn                                                                                                    |
-| `react`      | No      | eslint plugin react and eslint plugin react hooks                                                                        |
-| `react-perf` | No      | eslint plugin react perf                                                                                                 |
-| `nextjs`     | No      | eslint plugin next                                                                                                       |
-| `oxc`        | Yes     | Oxc specific rules and selected rules ported from deepscan                                                               |
-| `import`     | No      | eslint plugin import                                                                                                     |
-| `jsdoc`      | No      | eslint plugin jsdoc                                                                                                      |
-| `jsx-a11y`   | No      | eslint plugin jsx a11y                                                                                                   |
-| `node`       | No      | eslint plugin n                                                                                                          |
-| `promise`    | No      | eslint plugin promise                                                                                                    |
-| `jest`       | No      | eslint plugin jest                                                                                                       |
-| `vitest`     | No      | eslint plugin vitest                                                                                                     |
-| `vue`        | No      | eslint plugin vue rules that work with script tags                                                                       |
+This table lists the built-in plugins and where they come from.
+
+| Plugin name  | Default | Source                                                                                                                                                           |
+| ------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `eslint`     | Yes     | ESLint core rules                                                                                                                                                |
+| `typescript` | Yes     | TypeScript rules from typescript-eslint (aka `@typescript-eslint/plugin`). Type-aware rules are available in alpha using [the type-aware mode](./type-aware.md). |
+| `unicorn`    | Yes     | eslint-plugin-unicorn                                                                                                                                            |
+| `react`      | No      | eslint-plugin-react and eslint-plugin-react-hooks                                                                                                                |
+| `react-perf` | No      | eslint-plugin-react-perf                                                                                                                                         |
+| `nextjs`     | No      | @next/eslint-plugin-next                                                                                                                                         |
+| `oxc`        | Yes     | Oxc-specific rules and selected rules ported from deepscan                                                                                                       |
+| `import`     | No      | eslint-plugin-import (also equivalent to eslint-plugin-import-x)                                                                                                 |
+| `jsdoc`      | No      | eslint-plugin-jsdoc                                                                                                                                              |
+| `jsx-a11y`   | No      | eslint-plugin-jsx-a11y                                                                                                                                           |
+| `node`       | No      | eslint-plugin-n                                                                                                                                                  |
+| `promise`    | No      | eslint-plugin-promise                                                                                                                                            |
+| `jest`       | No      | eslint-plugin-jest                                                                                                                                               |
+| `vitest`     | No      | @vitest/eslint-plugin aka eslint-plugin-vitest                                                                                                                   |
+| `vue`        | No      | eslint-plugin-vue rules that work with script tags                                                                                                               |
 
 For the current status of rule coverage, see the linter [product plan issue](https://github.com/oxc-project/oxc/issues/481).
 
 ## Adding new plugins
 
-Oxlint focuses on supporting the ecosystem through built in plugins and ESLint compatible JavaScript plugins. Contributions that add rules to existing built in plugins are encouraged.
+Oxlint focuses on supporting the ecosystem through built-in plugins and ESLint-compatible JavaScript plugins. [Contributions that add rules](/docs/contribute/linter/adding-rules) to existing built-in plugins are encouraged.
 
-If you think a rule set should be implemented as a built in plugin, open a discussion first.
+If you think a rule set should be implemented as a built-in plugin, please [open a GitHub discussion](https://github.com/oxc-project/oxc/discussions/new?category=feature-request) first.