docs: more about extensions

Author: joelgallant

docs/guide/intro/extensions.md

@@ -46,34 +46,46 @@ api:
 
 This will safely resolve to an object `{ url: string, timeout: number }` by merging sibling keys.
 
+Note that `$env` is aware of environment name aliases as well. See [meta file](./settings.md#parse-and-loading-configuration)
+for how to change the environmentSourceNames or environmentAliases.
+
 ## The `$extends` Directive
 
 Merges (deeply) values from another file. The current file has precedent when merging.
 
 ```yaml
+# Use it with a file path
 $extends: './other-file.yml'
 
+# Or use it with options
 nested:
   propertyA:
     $extends:
       path: ./other-file.yml
       optional: true
       select: 'foo.bar'
+
+# An array also works
+$extends:
+  - ./file1.yml
+  - ./file2.yml
 ```
 
-This option can be given a string (filepath), an object with options, or an array of objects.
+This option can be given a filepath, an object with options, or an array of objects.
 
-`select` allows extending a sub-object and `optional` allows missing files. These are optional.
+`select` allows extending a property from the other file, and `optional` allows missing files.
 
 ## The `$override` Directive
 
 The override directive is exactly the same as `$extends`, except that the other file takes precedent when merging.
 This is useful for the pattern:
 
 ```yaml
+# if present, the values in this file will override the ones here
 $override:
   path: /etc/my-app/config.yml
   optional: true
+
 # ... default values
 ```