diff --git a/CHANGELOG.md b/CHANGELOG.md
index 92431a156..9022dc887 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -30,6 +30,7 @@ This change log adheres to standards from [Keep a CHANGELOG](https://keepachange
 - [Refactor] `exportMapBuilder`: avoid hoisting ([#2989], thanks [@soryy708])
 - [Refactor] `ExportMap`: extract "builder" logic to separate files ([#2991], thanks [@soryy708])
 - [Docs] [`order`]: update the description of the `pathGroupsExcludedImportTypes` option ([#3036], thanks [@liby])
+- [readme] Clarify how to install the plugin ([#2993], thanks [@jwbth])
 
 ## [2.29.1] - 2023-12-14
 
@@ -1133,6 +1134,7 @@ for info on changes for earlier releases.
 [#3011]: https://github.com/import-js/eslint-plugin-import/pull/3011
 [#3004]: https://github.com/import-js/eslint-plugin-import/pull/3004
 [#2998]: https://github.com/import-js/eslint-plugin-import/pull/2998
+[#2993]: https://github.com/import-js/eslint-plugin-import/pull/2993
 [#2991]: https://github.com/import-js/eslint-plugin-import/pull/2991
 [#2989]: https://github.com/import-js/eslint-plugin-import/pull/2989
 [#2987]: https://github.com/import-js/eslint-plugin-import/pull/2987
@@ -1835,6 +1837,7 @@ for info on changes for earlier releases.
 [@jseminck]: https://github.com/jseminck
 [@julien1619]: https://github.com/julien1619
 [@justinanastos]: https://github.com/justinanastos
+[@jwbth]: https://github.com/jwbth
 [@k15a]: https://github.com/k15a
 [@kentcdodds]: https://github.com/kentcdodds
 [@kevin940726]: https://github.com/kevin940726
diff --git a/README.md b/README.md
index bf563f4d7..8cc723423 100644
--- a/README.md
+++ b/README.md
@@ -108,35 +108,37 @@ npm install eslint-plugin-import --save-dev
 
 ### Config - Legacy (`.eslintrc`)
 
-All rules are off by default. However, you may configure them manually
-in your `.eslintrc.(yml|json|js)`, or extend one of the canned configs:
+All rules are off by default. However, you may extend one of the preset configs, or configure them manually in your `.eslintrc.(yml|json|js)`.
 
-```yaml
----
-extends:
-  - eslint:recommended
-  - plugin:import/recommended
-  # alternatively, 'recommended' is the combination of these two rule sets:
-  - plugin:import/errors
-  - plugin:import/warnings
-
-# or configure manually:
-plugins:
-  - import
-
-rules:
-  import/no-unresolved: [2, { commonjs: true, amd: true }]
-  import/named: 2
-  import/namespace: 2
-  import/default: 2
-  import/export: 2
-  # etc...
+ - Extending a preset config:
+
+```jsonc
+{
+  "extends": [
+     "eslint:recommended",
+     "plugin:import/recommended",
+  ],
+}
+```
+
+ - Configuring manually:
+
+```jsonc
+{
+  "rules": {
+    "import/no-unresolved": ["error", { "commonjs": true, "amd": true }]
+    "import/named": "error",
+    "import/namespace": "error",
+    "import/default": "error",
+    "import/export": "error",
+    // etc...
+  },
+},
 ```
 
 ### Config - Flat (`eslint.config.js`)
 
-All rules are off by default. However, you may configure them manually
-in your `eslint.config.(js|cjs|mjs)`, or extend one of the canned configs:
+All rules are off by default. However, you may configure them manually in your `eslint.config.(js|cjs|mjs)`, or extend one of the preset configs:
 
 ```js
 import importPlugin from 'eslint-plugin-import';
@@ -166,18 +168,23 @@ You may use the following snippet or assemble your own config using the granular
 
 Make sure you have installed [`@typescript-eslint/parser`] and [`eslint-import-resolver-typescript`] which are used in the following configuration.
 
-```yaml
-extends:
-  - eslint:recommended
-  - plugin:import/recommended
-# the following lines do the trick
-  - plugin:import/typescript
-settings:
-  import/resolver:
-    # You will also need to install and configure the TypeScript resolver
-    # See also https://github.com/import-js/eslint-import-resolver-typescript#configuration
-    typescript: true
-    node: true
+```jsonc
+{
+  "extends": [
+    "eslint:recommended",
+    "plugin:import/recommended",
+// the following lines do the trick
+    "plugin:import/typescript",
+  ],
+  "settings": {
+    "import/resolver": {
+      // You will also need to install and configure the TypeScript resolver
+      // See also https://github.com/import-js/eslint-import-resolver-typescript#configuration
+      "typescript": true,
+      "node": true,
+    },
+  },
+}
 ```
 
 [`@typescript-eslint/parser`]: https://github.com/typescript-eslint/typescript-eslint/tree/HEAD/packages/parser
@@ -206,6 +213,16 @@ You can reference resolvers in several ways (in order of precedence):
 
  - as a conventional `eslint-import-resolver` name, like `eslint-import-resolver-foo`:
 
+ ```jsonc
+// .eslintrc
+{
+  "settings": {
+    // uses 'eslint-import-resolver-foo':
+    "import/resolver": "foo",
+  },
+}
+```
+
 ```yaml
 # .eslintrc.yml
 settings:
@@ -226,6 +243,15 @@ module.exports = {
 
  - with a full npm module name, like `my-awesome-npm-module`:
 
+```jsonc
+// .eslintrc
+{
+  "settings": {
+    "import/resolver": "my-awesome-npm-module",
+  },
+}
+```
+
 ```yaml
 # .eslintrc.yml
 settings:
@@ -321,11 +347,15 @@ In practice, this means rules other than [`no-unresolved`](./docs/rules/no-unres
 
 `no-unresolved` has its own [`ignore`](./docs/rules/no-unresolved.md#ignore) setting.
 
-```yaml
-settings:
-  import/ignore:
-    - \.coffee$          # fraught with parse errors
-    - \.(scss|less|css)$ # can't parse unprocessed CSS modules, either
+```jsonc
+{
+  "settings": {
+    "import/ignore": [
+      "\.coffee$", // fraught with parse errors
+      "\.(scss|less|css)$", // can't parse unprocessed CSS modules, either
+    ],
+  },
+}
 ```
 
 ### `import/core-modules`
@@ -344,10 +374,13 @@ import 'electron'  // without extra config, will be flagged as unresolved!
 that would otherwise be unresolved. To avoid this, you may provide `electron` as a
 core module:
 
-```yaml
-# .eslintrc.yml
-settings:
-  import/core-modules: [ electron ]
+```jsonc
+// .eslintrc
+{
+  "settings": {
+    "import/core-modules": ["electron"],
+  },
+}
 ```
 
 In Electron's specific case, there is a shared config named `electron`
@@ -380,11 +413,15 @@ dependency parser will require and use the map key as the parser instead of the
 configured ESLint parser. This is useful if you're inter-op-ing with TypeScript
 directly using webpack, for example:
 
-```yaml
-# .eslintrc.yml
-settings:
-  import/parsers:
-    "@typescript-eslint/parser": [ .ts, .tsx ]
+```jsonc
+// .eslintrc
+{
+  "settings": {
+    "import/parsers": {
+      "@typescript-eslint/parser": [".ts", ".tsx"],
+    },
+  },
+}
 ```
 
 In this case, [`@typescript-eslint/parser`](https://www.npmjs.com/package/@typescript-eslint/parser)
@@ -414,20 +451,28 @@ For long-lasting processes, like [`eslint_d`] or [`eslint-loader`], however, it'
 
 If you never use [`eslint_d`] or [`eslint-loader`], you may set the cache lifetime to `Infinity` and everything should be fine:
 
-```yaml
-# .eslintrc.yml
-settings:
-  import/cache:
-    lifetime: ∞  # or Infinity
+```jsonc
+// .eslintrc
+{
+  "settings": {
+    "import/cache": {
+      "lifetime": "∞", // or Infinity, in a JS config
+    },
+  },
+}
 ```
 
 Otherwise, set some integer, and cache entries will be evicted after that many seconds have elapsed:
 
-```yaml
-# .eslintrc.yml
-settings:
-  import/cache:
-    lifetime: 5  # 30 is the default
+```jsonc
+// .eslintrc
+{
+  "settings": {
+    "import/cache": {
+      "lifetime": 5, // 30 is the default
+    },
+  },
+}
 ```
 
 [`eslint_d`]: https://www.npmjs.com/package/eslint_d
@@ -441,10 +486,13 @@ By default, any package referenced from [`import/external-module-folders`](#impo
 
 For example, if your packages in a monorepo are all in `@scope`, you can configure `import/internal-regex` like this
 
-```yaml
-# .eslintrc.yml
-settings:
-  import/internal-regex: ^@scope/
+```jsonc
+// .eslintrc
+{
+  "settings": {
+    "import/internal-regex": "^@scope/",
+  },
+}
 ```
 
 ## SublimeLinter-eslint