sort_by works on maps

pkg/yqlib/doc/operators/headers/sort-keys.md

@@ -12,5 +12,5 @@ diff file1.yml file2.yml
 
 Note that `yq` does not yet consider anchors when sorting by keys - this may result in invalid yaml documents if you are using merge anchors.
 
-For more advanced sorting, using `to_entries` to convert the map to an array, then sort/process the array as you like (e.g. using `sort_by`) and convert back to a map using `from_entries`.
-See [here](https://mikefarah.gitbook.io/yq/operators/entries#custom-sort-map-keys) for an example. 
+For more advanced sorting, you can use the [sort_by](https://mikefarah.gitbook.io/yq/operators/sort) function on a map, and give it a custom function like `sort_by(key | downcase)`.
+

pkg/yqlib/doc/operators/sort-keys.md

@@ -12,8 +12,8 @@ diff file1.yml file2.yml
 
 Note that `yq` does not yet consider anchors when sorting by keys - this may result in invalid yaml documents if you are using merge anchors.
 
-For more advanced sorting, using `to_entries` to convert the map to an array, then sort/process the array as you like (e.g. using `sort_by`) and convert back to a map using `from_entries`.
-See [here](https://mikefarah.gitbook.io/yq/operators/entries#custom-sort-map-keys) for an example. 
+For more advanced sorting, you can use the [sort_by](https://mikefarah.gitbook.io/yq/operators/sort) function on a map, and give it a custom function like `sort_by(key | downcase)`.
+
 
 ## Sort keys of map
 Given a sample.yml file of:

pkg/yqlib/doc/operators/sort.md

@@ -109,6 +109,46 @@ cool:
   - c: banana
 ```
 
+## Sort a map
+Sorting a map, by default, will sort by the values
+
+Given a sample.yml file of:
+```yaml
+y: b
+z: a
+x: c
+```
+then
+```bash
+yq 'sort' sample.yml
+```
+will output
+```yaml
+z: a
+y: b
+x: c
+```
+
+## Sort a map by keys
+Use sort_by to sort a map using a custom function
+
+Given a sample.yml file of:
+```yaml
+Y: b
+z: a
+x: c
+```
+then
+```bash
+yq 'sort_by(key | downcase)' sample.yml
+```
+will output
+```yaml
+x: c
+Y: b
+z: a
+```
+
 ## Sort is stable
 Note the order of the elements in unchanged when equal in sorting.