Defining your collections

Collections allow you to show groups of related content in the Site Navigation. Each collection corresponds to a folder in your site files. Navigating to a collection shows a preview of each file and allows your editors to see all the content at a glance.

You can define the collections themselves, change how you add new files, and change the way these files show with the configuration you set here.

CloudCannon reads the pages, collections and data from your Jekyll site and automatically defines collections by default. The automatically defined collections match your Jekyll collections defined in _config.yml.

Add collections and/or extend configuration for automatically discovered collections in your global configuration under collections_config.

_config.yml
collections:
  staff:
    output: true
cloudcannon.config.yml
collections_config:
  staff:
    sort:
      key: surname
    sort_options:
      - key: surname
      - key: surname
        order: desc
      - key: start_date
        label: Longest employed first
    subtext_key: role
    image_key: profile_image
    image_size: cover
    singular_name: Staff Member
    singular_key: staff_member
    disable_add: false
    icon: people
    add_options:
      - name: Add Staff Member
        icon: person_add
        href: "cloudcannon::editor/:collections_dir/_staff/.:extension🆕"
add_options - Array of objects

Changes the options presented in the add dropdown menu list.

disable_add - Boolean

Prevents users from adding new collection items. Default is false.

filter - String

Controls which files are displayed in the collection list. If set to strict, only the files discovered for this collection in the build are displayed, otherwise all collection-like files in the folder are displayed.

icon - String

Overrides the default collection icon with an icon from Google’s Material Icons. Must match Material Icon name.

image_key - String

Defines a front matter field to use when displaying an image on an item. Must match a front matter field of the collection items.

image_size - String

Sets how images are displayed in the list. Must be unset, cover or contain.

name - String

The display name of this collection. Used in headings and in the context menu for items in the collection. This is optional as CloudCannon auto-generates this from the collection key.

output - Boolean

Whether or not files in this collection produce files in the build output. Changes the default grouping for this collection in the navigation, and is used in consideration for the default _enabled_editors from the configuration cascade.

path - String

The top-most folder where the files in this collection are stored. It is relative to source.

If the collection is automatically discovered, this is set for you.

If the collection is not automatically discovered, this is required.

singular_key - String

Overrides the default singular input key of the collection. This is used for naming conventions for select and multiselect inputs.

singular_name - String

Overrides the default singular display name of the collection. This is displayed in the collection add menu and file context menu.

sort - Object

Sets the default sorting for the collection each time it is opened. Defaults to the first option in sort_options, then falls back descending path. As an exception, defaults to descending date for the posts collection. Contains the following fields:

  • key defines what field contains the value to sort on inside each collection item’s data. Required.
  • order controls which sort values come first. Must be one of asc, ascending, desc or descending. Defaults to ascending.
key: name
order: desc
sort_options - Array of objects

Controls the available options in the sort menu. Defaults to generating the options from the first item in the collection, falling back to ascending path and descending path. Each option contains the following fields:

  • key defines what field contains the value to sort on inside each collection item’s data. Required.
  • order controls which sort values come first. Must be one of asc, ascending, desc or descending. Defaults to ascending.
  • label is text to display in the sort option list. Defaults to generating a label from key and order.

If set to false or an empty array, the sort menu is hidden. sort still applies here, supporting a fixed sort order.

sort_options:
  - key: name
  - key: age
    order: desc
    label: Oldest first
subtext_key - String

Defines a front matter field to use when displaying subtext on an item. Must match a front matter field of the collection items.

title - String

Alias for name.

If required, you can prevent CloudCannon from automatically discovering collections by enabling the collections_config_override settings in your global configuration.

Was this article helpful? or Suggest an improvement >

Related articles