From 5ff031e541df66b560f76b8705fcff4c248ab494 Mon Sep 17 00:00:00 2001
From: Kevin Van Lierde <kevin.van.lierde@gmail.com>
Date: Thu, 3 Aug 2023 00:59:14 +0200
Subject: [PATCH] Better documentation for sorting + typescript

---
 README.md      | 19 +++++++++++++++++--
 lib/index.d.ts |  3 +++
 2 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index b98ed8a..9cb3091 100755
--- a/README.md
+++ b/README.md
@@ -79,7 +79,7 @@ All options are _optional_
 - **pattern** `string|string[]` - one or more glob patterns to group files into a collection
 - **filter** `Function` - a function that returns `false` for files that should be filtered _out_ of the collection
 - **limit** `number` - restrict the number of files in a collection to at most `limit`
-- **sort** `string|Function` - a sort string of the format `'<key_or_keypath>:<asc|desc>'`, followed by the sort order, for example: `date` or `pubdate:desc` or `order:asc`, or a custom sort function
+- **sort** `string|Function` - a sort string of the format `'<key_or_keypath>:<asc|desc>'`, followed by the sort order, for example: `date` or `pubdate:desc` or `order:asc`, or a custom sort function. Defaults to `path:asc` which is filesystem alphabetical order.
 - **metadata** `Object|string` - metadata to attach to the collection. Will be available as `metalsmith.metadata().collections.<name>.metadata`. This can be used for example to attach metadata for index pages. _If a string is passed, it will be interpreted as a file path to an external `JSON` or `YAML` metadata file_
 - **refer** `boolean` - will add `next`, `previous`, `first` and `last` keys to each file in a collection. `true` by default
 
@@ -141,6 +141,21 @@ There are 2 ways to create collections & they can be used together:
   ...contents
   ```
 
+#### Sorting
+
+By default sorting is done on `path:asc`, which is alphabetical filepath order.
+When `@metalsmith/collections` runs, it temporarily adds a `path` to the sorting context.
+
+When the sorting order (_asc_ ending or _desc_ ending) is omitted, _desc_ ending is implied.
+
+So `prop:asc` for the following file metadata would be ordered as:
+
+- `pubdate:asc`: `[Date(2023-01-01), Date(2023-01-05), Date(2023-01-03)]` -> `[Date(2023-01-01), Date(2023-01-03), Date(2023-01-05)]`
+- `path:asc`: `['news/one.md', 'news/two.md', 'news/three.md']` -> `['news/one.md', 'news/three.md', 'news/two.md']`
+- `order:asc`: `[5,2,6]` -> `[2,5,6]`
+
+These examples show how date-ordered collections like posts, news, feeds are sorted in _descending_ order (most recent first) and a timeline would be in _ascending_ order.
+
 ### Rendering collection items
 
 Here is an example of using [@metalsmith/permalinks](https://github.com/metalsmith/permalinks), followed by [@metalsmith/layouts](https://github.com/metalsmith/layouts) with [jstransformer-handlebars](https://github.com/jstransformers/jstransformer-handlebars) to render the `something-happened.md` news item, with links to the next and previous news items (using `refer: true` options):
@@ -196,7 +211,7 @@ No news at the moment...
 
 ### Custom sorting, filtering and limiting
 
-You could define an `order` property on a set of files and pass `sort: 'order:asc'` to `@metalsmith/collections` for example, or you could override the sort with a custom function (for example to do multi-level sorting). For instance, this function sorts the "subpages" collection by a numerical "index" property but places unindexed items last.
+You could define an `order` property on a set of files and pass `sort: 'order:asc'` to `@metalsmith/collections` for example, or you could override the sort with a custom function (for example to do multi-level sorting). The function below function sorts the "subpages" collection by a numerical "index" property but places unindexed items last.
 
 ```js
 metalsmith.use(
diff --git a/lib/index.d.ts b/lib/index.d.ts
index 04158a2..4f4f2f9 100644
--- a/lib/index.d.ts
+++ b/lib/index.d.ts
@@ -8,6 +8,7 @@ export type CollectionConfig = {
     pattern?: string | string[] | null;
     /**
      * - a sort string of the format `'<key_or_keypath>:<asc|desc>'`, followed by the sort order, or a custom sort function
+     * @default 'path:asc'
      * @example
      * 'date'
      * 'pubdate:desc'
@@ -20,10 +21,12 @@ export type CollectionConfig = {
     limit?: number;
     /**
      * - Adds `next`, `previous`, `first` and `last` keys to file metadata of matched files
+     * @default true
      */
     refer?: boolean;
     /**
      * - A function that gets a `Metalsmith.File` as first argument and returns `true` for every file to include in the collection
+     * @default () => true
      */
     filter?: Function;
     /**