@metalsmith/collections 1.3.0 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,70 @@
+### Changelog
+
+All notable changes to this project will be documented in this file. Dates are displayed in UTC.
+
+Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
+
+#### [v2.0.0](https://github.com/metalsmith/collections/compare/v1.3.1...v2.0.0)
+
+- Closes #98: adds 'first' & 'last' references when refer:true [`#98`](https://github.com/metalsmith/collections/issues/98)
+- BREAKING: Closes #101: condenses sortBy, reverse into sort option. Renames filterBy option to filter. [`#101`](https://github.com/metalsmith/collections/issues/101)
+- Updates README.md, fixes ESLint issues, versions build to allow npm installing from repo [`f9da8e4`](https://github.com/metalsmith/collections/commit/f9da8e4d3952c3452fbef52cdc5951bd4e48b9f6)
+- BREAKING: references (previous, next,..) are set on file.collection[name][previous/next] as arrays [`8c7d9d6`](https://github.com/metalsmith/collections/commit/8c7d9d68fa5b48f314707a3d29075438a8cb43f2)
+- BREAKING: collections are only available via metalsmith.metadata().collections [`e8e2760`](https://github.com/metalsmith/collections/commit/e8e2760e72b06211f8d5f9f11296a82efe8efc4f)
+- Require metalsmith > 2.6.0 & use metalsmith.matter instead of removed dependency read-metadata [`c0748fa`](https://github.com/metalsmith/collections/commit/c0748fa69c55456c39214121998719b01a695064)
+- BREAKING: collection metadata can only be added from in-source files [`df507d6`](https://github.com/metalsmith/collections/commit/df507d6b20d9a44215dc34e3c3ce25517032c66f)
+- BREAKING: Make metadata accessible from Collection array instead of '.metadata' property [`42f45c8`](https://github.com/metalsmith/collections/commit/42f45c876946f66578e770c38c3b0ac7b1a247ac)
+- BREAKING: Adds 'path' property to sorting context, and changes the default sorting to path:asc [`64b5f72`](https://github.com/metalsmith/collections/commit/64b5f7203ec0afa3c9c76e29af277b4e91b61738)
+- Drops support for Node < 14.14.0, updates CI, drops Gitter notification [`36eb59d`](https://github.com/metalsmith/collections/commit/36eb59daf06e35f748b3c9872e77f1ee947e63e7)
+- BREAKING: no longer sets 'file.path' property [`df26510`](https://github.com/metalsmith/collections/commit/df26510b210ae2731295ff4f733c4550e32e741c)
+- Better documentation for sorting + typescript [`1d3f81e`](https://github.com/metalsmith/collections/commit/1d3f81e5997375673c49efcbb5f4e7a7408068b5)
+
+#### [v1.3.1](https://github.com/metalsmith/collections/compare/v1.3.0...v1.3.1)
+
+> 26 November 2024
+
+- Fix: make all option properties optional [`b85b6cf`](https://github.com/metalsmith/collections/commit/b85b6cf75f949188191415147338ae28c5b9fbac)
+- Renames default export to collections for better intellisense [`61ec7f9`](https://github.com/metalsmith/collections/commit/61ec7f93fe4fac2112909b4fee233507affe05a2)
+- Includes sourcemap for better stack traces [`b5b8059`](https://github.com/metalsmith/collections/commit/b5b80597cf821b3c478b864ddf5739d60aadce0d)
+- Fix: conditional exports types [`e8bb72a`](https://github.com/metalsmith/collections/commit/e8bb72ac22298324669b3e7b45d7177c88b13c2a)
+
+#### [v1.3.0](https://github.com/metalsmith/collections/compare/v1.2.2...v1.3.0)
+
+> 27 September 2022
+
+- Provides dual ESM/CJS bundle [`61430d4`](https://github.com/metalsmith/collections/commit/61430d489ae87df1276f61de8aad2755c0491cc9)
+- switched debugger to metalsmith.debug [`8df9e65`](https://github.com/metalsmith/collections/commit/8df9e65b6b03f4c3d96a81d477a21d69aeafadbf)
+- Adds Typescript types support [`9f9b36c`](https://github.com/metalsmith/collections/commit/9f9b36ca569153ad84be89facdc6a2630e86a6af)
+
+#### [v1.2.2](https://github.com/metalsmith/collections/compare/v1.2.1...v1.2.2)
+
+> 28 July 2022
+
+- Resolves #102: remove multimatch, use metalsmith.match [`#102`](https://github.com/metalsmith/collections/issues/102)
+- Drops support for Node < 12 [`6a7271c`](https://github.com/metalsmith/collections/commit/6a7271c9a170e88ae91e1d05e2f7162606566f3f)
+
+#### [v1.2.1](https://github.com/metalsmith/collections/compare/v1.2.0...v1.2.1)
+
+> 3 February 2022
+
+- Closes #27 by adding a test for repeat builds [`#27`](https://github.com/metalsmith/collections/issues/27)
+- Fixes incorrect next and previous references [`665de09`](https://github.com/metalsmith/collections/commit/665de091b3bbb7b74741d15e17e471ae225ba2ec)
+- Fixes collection property on files and adds test: no dupes, no nested arrays (#99) [`727769d`](https://github.com/metalsmith/collections/commit/727769d95464e61739523538006cb863220cfae6)
+
+#### [v1.2.0](https://github.com/metalsmith/collections/compare/v1.1.0...v1.2.0)
+
+> 29 January 2022
+
+- feat: refactor, clean code, remove redundant dependencies, add tests [`d481b92`](https://github.com/metalsmith/collections/commit/d481b927b6137df81e8fc71de99c1277f6a131c2)
+- docs: update README, prepare changelog for v1.2 [`c004ed0`](https://github.com/metalsmith/collections/commit/c004ed00216145f3cfa82042ab9243e42c23edb3)
+- [skip travis] dev: fix readme badges [`87e4d37`](https://github.com/metalsmith/collections/commit/87e4d370530065a790c0b077d820fcc47bd6594c)
+
+#### [v1.1.0](https://github.com/metalsmith/collections/compare/v1.0.0...v1.1.0)
+
+> 15 December 2021
+
+- Added standardised code formatting and QA [`#86`](https://github.com/metalsmith/collections/pull/86)
+- Updated History with v1 PRs [`#85`](https://github.com/metalsmith/collections/pull/85)
+- Aligned dotfiles & repo files with core plugins. Added LICENSE, updated devDependencies [`0f2480b`](https://github.com/metalsmith/collections/commit/0f2480b4c2baa22268229ad3d686fb9e21773602)
+- Updated multimatch to 4.0.0, debug to 4.3.3 [`71d6f65`](https://github.com/metalsmith/collections/commit/71d6f65b9ec5572196e17dfebf5cff2361853f9d)
+- Added better JSDoc types, return named plugin function [`3aa3443`](https://github.com/metalsmith/collections/commit/3aa3443802c2f814c90cf39c7b43de8fc3d3ff13)

package/README.md

@@ -10,12 +10,11 @@ A Metalsmith plugin that lets you group files together into ordered collections,
 
 ## Features
 
-- can match files by `collection` file metadata
-- can match files by pattern
+- can match files by `collection` file metadata or pattern
 - can limit the number of files in a collection
 - can filter files in a collection based on file metadata
-- adds collections to global metadata
-- adds `next` and `previous` references to each file in the collection
+- adds collections to global metadata under the `collections` key.
+- adds `next`, `previous`, `first` and `last` references to each file's collection references
 
 ## Installation
 
@@ -44,44 +43,46 @@ import { dirname } from 'path'
 const __dirname = dirname(new URL(import.meta.url).pathname)
 
 // defaults, only create collections based on file metadata
-Metalsmith(__dirname)
-  .use(markdown())
-  .use(collections())
+Metalsmith(__dirname).use(markdown()).use(collections())
 
 // defaults for a "news" collection, except pattern option
 Metalsmith(__dirname)
   .use(markdown())
-  .use(collections({
-    news: { pattern: 'news/**/*.html' }
-  }))
+  .use(
+    collections({
+      news: { pattern: 'news/**/*.html' }
+    })
+  )
 
 // explicit defaults for a "news" collection, except pattern option
 Metalsmith(__dirname)
   .use(markdown())
-  .use(collections({
-    pattern: { pattern: 'news/**/*.html' },
-    metadata: null,
-    filterBy: () => true,
-    sortBy: defaultSort,
-    reverse: false,
-    limit: Infinity,
-    refer: true
-  })
+  .use(
+    collections({
+      pattern: { pattern: 'news/**/*.html' },
+      metadata: null,
+      filter: () => true,
+      sort: 'date:desc',
+      limit: Infinity,
+      refer: true
+    })
+  )
 ```
 
-_Note: all examples in the readme use the same collections definitions under [Defining collections](#defining-collections)_
+With the example above, the file `src/news/world/something.html`'s `collection` property will become `['news']` but with extra properties attached, so that `file.collection.news.previous.title` resolves, as well as `file.collection.news.previous[0].title`
+
+_Note: all subsequent examples in the readme use the same collections definitions under [Defining collections](#defining-collections)_
 
 ### Options
 
 All options are _optional_
 
 - **pattern** `string|string[]` - one or more glob patterns to group files into a collection
-- **filterBy** `Function` - a function that returns `false` for files that should be filtered _out_ of the 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`
-- **sortBy** `string|Function` - a file metadata key to sort by (for example `date` or `pubdate` or `title`), or a custom sort function
-- **reverse** `boolean` - whether the sort should be reversed (e.g., for a news/blog collection, you typically want `reverse: true`)
+- **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 `previous` and `next` keys to each file in a collection. `true` by default
+- **refer** `boolean` - will add `next`, `previous`, `first` and `last` keys to each file in a collection. `true` by default
 
 ### Defining collections
 
@@ -97,11 +98,10 @@ There are 2 ways to create collections & they can be used together:
         metadata: {
           title: 'Latest news',
           description: 'All the latest in politics & world news',
-          slug: 'news'
+          permalink: 'news'
         },
         pattern: 'news/**/*.html',
-        sortBy: 'pubdate',
-        reverse: true
+        sort: 'pubdate:desc'
       },
       services: 'services/**/*.html'
     })
@@ -142,33 +142,77 @@ 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 the file `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/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):
+> [!IMPORTANT]
+> Mind the difference between **collection** and **collections**: the _collections_ object is stored on `metalsmith.metadata()` and accessible to all files when using @metalsmith/layouts or in-place. Matched files each get an own _collection_ property, - an array of collection names -, with each collection also accessible by name (file.collection\[name]).
+
+Here is an example of using [@metalsmith/permalinks](https://github.com/metalsmith/permalinks), followed by [@metalsmith/layouts](https://github.com/metalsmith/layouts) with [jstransformer-nunjucks](https://github.com/jstransformers/jstransformer-nunjucks) to render the `something-happened.md` news item, with links to the next and previous news items (using `refer: true` options):
 
 `layouts/news.njk`
 
-```handlebars
-<h1>{{ title }}</h1> {{!-- something-happened.md title --}}
-<a href="/{{ collections.news.metadata.slug }}">Back to news</a> {{!-- news collection metadata.slug --}}
+```nunjucks
+<h1>{{ title }}</h1>
+
+{# permalink is expected to be set from collection metadata here #}
+<a href="{{ baseurl }}/{{ collections.news.permalink }}">See all {{ collections.news.title }}</a>
+{% endfor %}
 {{ contents | safe }}
 <hr>
-{{!-- previous & next are added by @metalsmith/collections --}}
-{{#if previous}}
+{{#if collection.news.previous.length }}
 Read the previous news:
-<a href="/{{ previous.path }}">{{ previous.title }}</a>
+<a href="/{{ collection.news.next.permalink }}">{{ collection.news.next.title }}</a>
 {{/if}}
-{{#if next}}
+{{#if collection.news.next.length }}
 Read the next news:
-<a href="/{{ next.path }}">{{ next.title }}</a>
+<a href="/{{ collection.news.previous.permalink }}">{{ collection.news.previous.title }}</a>
 {{/if}}
 ```
 
-_Note: If you don't need the `next` and `previous` references, you can pass the option `refer: false`_
+The previous example shows how to get the "first" previous/ next references, the next example show how you can iterate over each collection and render the full list of next/ previous items.
+
+```nunjucks
+<h1>{{ title }}</h1>
+
+Part of: {% for name in collection -%}
+<a href="{{ baseurl }}/{{ collections[name].permalink }}">{{ collections[name].title }}</a>{% if not loop.last %}, {% endif%}
+{%- endfor %}
+{% for name in collection %}
+  {% if collection[name].previous.length %}
+  {% for prev in collection[name].previous %}
+  <a href="{{ prev.permalink }}"><-- {{ name }} / {{ prev.title }}</p>
+  {% endfor %}
+  {% endif %}
+  {% for next in collection[name].next %}
+  <a href="{{ next.permalink }}"> {{ name }} / {{ next.title }} --></p>
+  {% endfor %}
+  {% endif %}
+{% endfor %}
+```
+
+The example above supposes an ordering of `pubdate:desc` (newest to oldest) or similar, which is why the "next news" corresponds to the `previous` property.
+If one would map the news dates they would be like: `['2023-01-20', 2023-01-10', '2023-01-01']`.
+
+_Note: If you don't need the `next`, `previous`, `first` or `last` references, you can pass the option `refer: false`_
 
 ### Rendering collection index
 
-All matched files are added to an array that is exposed as a key of metalsmith global metadata, for example the `news` collection would be accessible at `Metalsmith.metadata().collections.news `. Below is an example of how you could render an index page for the `news` collection:
+All matched files are added to an array that is exposed as a key of metalsmith global metadata, for example the `news` collection would be accessible at `Metalsmith.metadata().collections.news `. Below is a handlebarsexample of how you could render an index page for the `news` collection:
 
 `layouts/news-index.hbs`
 
@@ -176,12 +220,11 @@ All matched files are added to an array that is exposed as a key of metalsmith g
 <h1>{{ title }}</h1> {{!-- news collection metadata.title --}}
 <p>{{ description }}</p> {{!-- news collection metadata.description --}}
 <hr>
-{{!-- previous & next are added by @metalsmith/collections --}}
 {{#if collections.news.length }}
   <ul>
   {{#each collections.news}}
     <li>
-      <h3><a href="/{{path}}">{{ title }}</a></h3>
+      <h3><a href="{{ baseurl }}/{{ permalink }}">{{ title }}</a></h3>
       <p>{{ excerpt }}</p>
     </li>
   {{/each}}
@@ -194,13 +237,13 @@ No news at the moment...
 
 ### Custom sorting, filtering and limiting
 
-You could define an `order` property on a set of files and pass `sortBy: "order"` 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(
   collections({
     subpages: {
-      sortBy: function (a, b) {
+      sort(a, b) {
         let aNum, bNum
 
         aNum = +a.index
@@ -221,9 +264,9 @@ metalsmith.use(
 )
 ```
 
-_Note: the `sortBy` option also understands nested keypaths, e.g. `display.order`_
+_Note: the `sort` option also understands nested keypaths, e.g. `display.order:asc`_
 
-The `filterBy` function is passed a single argument which corresponds to each file's metadata. You can use the metadata to perform comparisons or carry out other decision-making logic. If the function you supply evaluates to `true`, the file will be added to the collection. If it evaluates to `false`, the file will not be added. The filterBy function below could work for a collection named `thisYearsNews` as it would filter out all the items that are older than this year:
+The `filter` function is passed a single argument which corresponds to each file's metadata. You can use the metadata to perform comparisons or carry out other decision-making logic. If the function you supply evaluates to `true`, the file will be added to the collection. If it evaluates to `false`, the file will not be added. The filter function below could work for a collection named `thisYearsNews` as it would filter out all the items that are older than this year:
 
 ```js
 function filterBy(file) {
@@ -240,18 +283,18 @@ metalsmith.use(
   collections({
     recentArticles: {
       pattern: 'articles/**/*.html',
-      sortBy: 'date',
+      sort: 'date',
       limit: 10
     },
     archives: {
       pattern: 'archives/**/*.html',
-      sortBy: 'date'
+      sort: 'date'
     }
   })
 )
 ```
 
-_Note: the collection is first sorted, reversed, filtered, and then limited, if applicable._
+_Note: the collection is first sorted, filtered, and then limited, if applicable._
 
 ### Collection Metadata
 
@@ -271,14 +314,13 @@ metalsmith.use(
 )
 ```
 
-Collection metadata can be loaded from a `json` or `yaml` file (path relative to `Metalsmith.directory()`):
+Collection metadata can be loaded from a `json` or `yaml` file (path relative to `Metalsmith.source()`):
 
 ```js
 metalsmith.use(
   collections({
     articles: {
-      sortBy: 'date',
-      reverse: true,
+      sort: 'date:asc',
       metadata: 'path/to/file.json'
     }
   })
@@ -311,8 +353,7 @@ Add the `@metalsmith/collections` key to your `metalsmith.json` `plugins` key:
     {
       "@metalsmith/collections": {
         "articles": {
-          "sortBy": "date",
-          "reverse": true
+          "sort": "date:asc"
         }
       }
     }