Roadmap 2.0

[webketje]

This issue provides an overview of intended (potentially breaking) changes for collections 2.0 release
Please comment if you disagree, feedback is welcome!

• BREAKING - Only store collections in metadata.collections. In 1.x for example a collection called news is also stored as metalsmith.metadata().news. This plugin should not pollute, and potentially overwrite, multiple other metadata keys
• BREAKING - Store collection metadata as properties on the collection, instead of in the property metadata. This makes for cleaner access in templates, eg collections.news.title instead of collections.news.metadata.title, and is in line with how metadata is defined for files and build metadata. Might be safer in that case to have collections be an object with items: Array<File> property instead of an array.
• Pushing the file objects (as references) in collections is problematic for adding previous/next references when a file is assigned multiple collections: which collection would the previous/next references then refer to? The first? The last? The current tests are lacking in this regard. But the file objects cannot be cloned as "collection items" because they will get out of sync with subsequent plugin transforms. The file objects need the reference to be on them to be accessible in templates. 3 paths to go:
  • BREAKING - Remove support for multiple collections. All good without extra tests
  • BREAKING - The previous and next references become objects with a key matching each collection assigned to the file, eg. next.tech & next.hobby.
  • BREAKING - The previous and next references are removed. The collection key on the file becomes an object with a key matching each collection, whose value is [name:string, previous:[...File],next:[...File]]. Layouts can then do: {{ collection.news.next.title }} or when looping `{{# each collection }}{{#each this }}{{/each}}
• Allow specifying either collection or collections in file front-matter, but normalize it to collection as an array.

Anyhow it seems to increasingly make sense to map collections as:

{
  name: 'my-collection',
  items: [File, File, File],
  ...metadata
}

And to remap them on the file objects as collection as:

{
  name: 'my-collection',
  ...metadata
  previous: [File, File],
  next: [File, File]
}

Usage examples:

• Get the first collection (in nunjucks): {{ collection | first }}

[Melindrea]

As someone who's interested in the next/prior references--I think my preferred option is the middle one. Since that's the most flexible one for sure, and having next/prior (and also first/last, but that's a different point altogether) are in my opinion quite important.

Though, hmm. Another way to implement that particular thing might be to keep track of where in the collection an item is? Because if I know that there are 5 elements in the collection I'm interested in, and I'm currently on element 2, that means that the previous element is element 1 and the next is element 3, and I can create next/previous/pagination with that knowledge.