docs: Explain how to combine configs (#17947)

* docs: Explain how to combine configs

fixes #17844

* Update docs/src/use/configure/combine-configs.md

Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com>

* Update docs/src/use/configure/combine-configs.md

Co-authored-by: Nitin Kumar <snitin315@gmail.com>

---------

Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com>
Co-authored-by: Nitin Kumar <snitin315@gmail.com>

docs/src/use/configure/combine-configs.md

@@ -0,0 +1,95 @@
+---
+title: Combine Configs
+eleventyNavigation:
+    key: combine configs
+    parent: configure
+    title: Combine Configs
+    order: 6
+---
+
+In many cases, you won't write an ESLint config file from scratch, but rather, you'll use a combination of predefined and shareable configs along with your own overrides to create the config for your project. This page explains some of the patterns you can use to combine configs in your configuration file.
+
+## Apply a Config Object
+
+If you are importing an object from another module, in most cases, you can just insert the object directly into your config file's exported array. For example, you can use the recommended rule configurations for JavaScript by importing the `recommended` config and using it in your array:
+
+```js
+// eslint.config.js
+import js from "@eslint/js";
+
+export default [
+    js.configs.recommended,
+    {
+        rules: {
+            "no-unused-vars": "warn"
+        }
+    }
+];
+```
+
+Here, the `js.configs.recommended` predefined configuration is applied first and then another configuration object adds the desired configuration for `no-unused-vars`.
+
+### Apply a Config Object to a Subset of Files
+
+You can apply a config object to just a subset of files by creating a new object with a `files` key and using the object spread operator to merge in the rest of the properties from the config object. For example:
+
+```js
+// eslint.config.js
+import js from "@eslint/js";
+
+export default [
+    {
+        ...js.configs.recommended,
+        files: ["**/src/safe/*.js"]
+    }
+];
+```
+
+Here, the `js.configs.recommended` config object is applied only to files that match the pattern "`**/src/safe/*.js"`.
+
+## Apply a Config Array
+
+If you are importing an array from another module, you can use the array spread operator to insert the items from that array into your exported array. Here's an example:
+
+```js
+// eslint.config.js
+import exampleConfigs from "eslint-config-example";
+
+export default [
+    ...exampleConfigs,
+
+    // your modifications
+    {
+        rules: {
+            "no-unused-vars": "warn"
+        }
+    }
+];
+```
+
+Here, the `exampleConfigs` shareable configuration is applied first and then another configuration object adds the desired configuration for `no-unused-vars`.
+
+### Apply a Config Array to a Subset of Files
+
+You can apply a config array to just a subset of files by using the `map()` method to add a `files` key to each config object. For example:
+
+```js
+// eslint.config.js
+import exampleConfigs from "eslint-config-example";
+
+export default [
+    ...exampleConfigs.map(config => ({
+        ...config,
+        files: ["**/src/safe/*.js"]
+    })),
+
+    // your modifications
+    {
+        rules: {
+            "no-unused-vars": "warn"
+        }
+    }
+];
+```
+
+Here, each config object in `exampleConfigs` is applied only to files that match the pattern "`**/src/safe/*.js"`.

docs/src/use/configure/configuration-files.md

@@ -316,19 +316,7 @@ export default [
 
 Here, the `js.configs.recommended` predefined configuration is applied first and then another configuration object adds the desired configuration for `no-unused-vars`.
 
-You can apply these predefined configs to just a subset of files by specifying a config object with a `files` key, like this:
-
-```js
-// eslint.config.js
-import js from "@eslint/js";
-
-export default [
-    {
-        files: ["**/src/safe/*.js"],
-        ...js.configs.recommended
-    }
-];
-```
+For more information on how to combine predefined configs with your preferences, please see [Combine Configs](combine-configs).
 
 ## Using a Shareable Configuration Package
 
@@ -372,6 +360,8 @@ export default [
 
 Please refer to the documentation for the shareable configuration package you're using to determine whether it is exporting an object or an array.
 
+For more information on how to combine shareable configs with your preferences, please see [Combine Configs](combine-configs).
+
 ## Configuration File Resolution
 
 When ESLint is run on the command line, it first checks the current working directory for `eslint.config.js`. If that file is found, then the search stops, otherwise it checks for `eslint.config.mjs`. If that file is found, then the search stops, otherwise it checks for `eslint.config.cjs`. If none of the files are not found, it checks the parent directory for each file. This search continues until either a config file is found or the root directory is reached.

docs/src/use/configure/ignore.md

@@ -4,7 +4,7 @@ eleventyNavigation:
     key: ignore files
     parent: configure
     title: Ignore Files
-    order: 6
+    order: 7
 
 ---
 

docs/src/use/configure/migration-guide.md

@@ -4,7 +4,7 @@ eleventyNavigation:
     key: migration guide
     parent: configure
     title: Configuration Migration Guide
-    order: 7
+    order: 8
 ---
 
 This guide provides an overview of how you can migrate your ESLint configuration file from the eslintrc format (typically configured in `.eslintrc.js` or `.eslintrc.json` files) to the new flat config format (typically configured in an `eslint.config.js` file).