docs: semi-big rewrite

tresorama · web-flow · commit c6efc5197988 · 2025-01-02T17:24:04.000+01:00
diff --git a/docs/src/use/configure/configuration-files.md b/docs/src/use/configure/configuration-files.md
@@ -208,26 +208,48 @@ Filenames starting with a dot, such as `.gitignore`, are considered to have only
 
 #### Globally ignoring files with `ignores`
 
-If you want to globally ignores some directory/files, and apply this directive to all configuration objects of the array,  `global ignores` is exactly made for this scenario.
-If `ignores` is used without any other keys in the configuration object, then the patterns act as global ignores. Here's an example:
+Depending on how the `ignores` property is used, it can behave as non-global `ignores` or as global `ignores`.
+
+* If `ignores` is used without any other keys in the configuration object, then the patterns act as global ignores. This way it gets apply to every configuration object (not only to the configration object in which is defined). Global `ignores` allows you not to have to copy and keep the `ignores` property synchronized in more than one configuration object.
+* If `ignores` is used in conjunction with other properties in the same configuration object, then the patterns act as non-global ignores. This way `ignores` applies only that configuration object
+
+Global and non-global `ignores` have some usage differences:
+
+* patterns in non-global `ignores` only match the files (`dir/filename.js`) or files within directories (`dir/**`)
+* patterns in global `ignores` can also match directories (`dir/`), other than files like "non-global".
+
+In any case (non-global or global):
+
+* the glob patterns you define are added after the default patterns, which are `["**/node_modules/", ".git/"]`
+* glob patterns always match files and directories that begin with a dot, such as `.foo.js` or `.fixtures`, unless those files are explicitly ignored. The only dot directory ignored by default is `.git`
 
 ```js
 // eslint.config.js
+
+// Example of global ignores
 export default [
     {
-        ignores: [".config/*"]
-    }
+      ignores: [".config/", "dist/", "tsconfig.json"] // acts as global ignores, due to the absence of other properties
+    },
+    { ... }, // ... other configuration object, inherit global ignores
+    { ... }, // ... other configuration object inherit global ignores
 ];
-```
 
-This configuration specifies that all of the files in the `.config` directory should be ignored. This pattern is added after the default patterns, which are `["**/node_modules/", ".git/"]`.
+// Example of non-global ignores
+export default [
+    {
+      ignores: [".config/**", "dir1/script1.js"],
+      rules: { ... } // the presence of this property dictates non-global ignores
+    },
+    {
+      ignores: ["other-dir/**", "dist/script2.js"],
+      rules: { ... } // the presence of this property dictates non-global ignores
+    },
+];
+```
 
 For more information and examples on configuring rules regarding `ignores`, see [Ignore Files](ignore).
 
-::: important
-Glob patterns always match files and directories that begin with a dot, such as `.foo.js` or `.fixtures`, unless those files are explicitly ignored. The only dot directory ignored by default is `.git`.
-:::
-
 #### Cascading Configuration Objects
 
 When more than one configuration object matches a given filename, the configuration objects are merged with later objects overriding previous objects when there is a conflict. For example:
