Collections#

A collection in liara groups content together into an optionally ordered collection. This grouping is efficient, i.e. iterating a sorted collection does not incur any sorting cost. It is also efficient to look up the next/previous entry in an collection.

Definition#

A collection definition consists of the following elements:

  • The name (that’s the key used in the YAML file)

  • filter: The filter – this is an URL pattern which defines all elements that are in this collection.

  • order_by: The ordering – optionally specifies how the collection should be ordered. This is a metadata accessor, to access nested fields, separate the individual accesses using .. For instance, date.year will access the date metadata field first, and then the year attribute. If you want to reverse the order, add a leading -, for example -date.year. If the metadata is missing, an error will be raised. Use exclude_without if you want to remove items which don’t have certain metadata fields. Multiple fields can be specified by using a list.

  • exclude_without: Optionally exclude nodes without the specified metadata field(s). Multiple fields can be specified by using a list.

  • node_kinds: The node kinds to include – optionally, the kinds of nodes to include in the collection can be specified. If nothing is specified, only document nodes are included by default.

For example:

blog:
  filter: '/blog/**'
  order_by: 'date'
  exclude_without: 'date'

Defines a collection named blog, which contains all elements under /blog, ordered by the date metadata field.

Usage#

Collections can be obtained from the Site object using get_collection(). If ordered, get_next_in_collection() and get_previous_in_collection() can be used to provide next/previous links. The other use of collections are Indices.