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 automatically reads the pages, collections and data from your Jekyll site and populates some default configuration.

You can change the configuration for any collection in your _config.yml file at the cloudcannon.collections level. Configuration here is combined with the configuration at the collections level.

_config.yml

collections:
  staff:
    output: true

cloudcannon:
  collections:
    staff:
      _sort_key: surname
      _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🆕"

path - String

The top-most folder where the files in this collection are stored. It is relative to source. This is an optional field as CloudCannon auto-detects this.

CloudCannon automatically reads the files in the content and data folders from your Hugo site and populates some default configuration.

You can change the configuration for any collection in your site config at the cloudcannon.collections level. Defining collections here supplements the defaults CloudCannon automatically finds.

config.toml

[cloudcannon.collections.staff]
_sort_key = "surname"
_subtext_key = "role"
_image_key = "profile_image"
_image_size = "cover"
_singular_name = "Staff Member"
_singular_key = "staff_member"
_disable_add = "false"
_icon = "people"

[cloudcannon.collections.staff._add_options]
name = "Add Staff Member"
icon = "person_add"
href = "cloudcannon::editor/:collections_dir/_staff/.:extension🆕"

path - String

The top-most folder where the files in this collection are stored. It is relative to source. This is an optional field as CloudCannon auto-detects this.

CloudCannon automatically reads the pages, collections and data from your Eleventy site and populates some default configuration.

You can change the configuration for any collection in your _data/cloudcannon.* file at the collections level. Defining collections here overrides the defaults CloudCannon automatically finds.

_data/cloudcannon.js

module.exports = {
  collections: {
    staff: {
      path: 'content/staff',
      output: false,
      _sort_key: 'surname',
      _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🆕'
        }
      ]
    }
  }
};

path - String

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

CloudCannon automatically runs reader after each build to populate the collections configuration. You’ll need to define each collection in your cloudcannon.config.* file at the collections-config level.

The path field is required for each collection for the Site Navigation to find the files to display.

cloudcannon.data.cjs

module.exports = {
  'collections-config': {
    staff: {
      path: 'content/staff_members',
      output: false,
      _sort_key: 'surname',
      _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/content/staff_members/.:extension🆕'
        }
      ]
    },
    posts: {
      path: 'content/posts',
      output: true,
      parser: 'yaml',
      url: '/posts/{category|slugify}/[slug].html'
    }
  }
}

path - String

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

url - String or Function

Used to build the url field for items in the collection. Similar to permalink in many SSGs. Defaults to ''.

Functions are are supported with cloudcannon.config.js or cloudcannon.config.cjs files. Given file path, parsed file content and an object with filters as arguments. The return value should be the slash-prefixed URL string.

Strings are used as a template to build the URL. There are two types of placeholders available, file and data. Placeholders resulting in empty values are supported. Sequential slashes in URLs are condensed to one.

File placeholders are always available:

[path] is the full path of the file, relative to source.
[slug] is the filename, excluding extension.
[ext] is the last extension, including ..

Data placeholders are populated from front matter or data values in the file, and support a number of filters:

{title} is the title from inside the file.
{id} is the id from inside the file.
{title|lowercase} is title from inside the file, lower cased.
{category|slugify} is category from inside the file, slugified.
{tag|slugify|uppercase} is tag from inside the file, slugified, then upper cased.

parser - String or Function

Define how reader processes your files into the JSON written to _cloudcannon/info.json. These are the available parsers and default file extensions covered:

csv (.csv)
front-matter (.md, .mkd, .markdown, .html, .htm)
json (.json)
properties (.properties)
toml (.toml)
yaml (.yaml, .yml)

Functions are are supported with cloudcannon.config.js or cloudcannon.config.cjs files. Given file path, raw file content and an object with parsers and filters as arguments. The return value should be an object representing this file.

_sort_key - String

Must match a front matter field of the collection items. Sets the sort order of the collection. Default is false.

_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.

_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.

_singular_name - String

Overrides the default singular display name of the collection.

_singular_key - String

Overrides the default singular input key of the collection.

_disable_add - Boolean

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

_icon - String

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

_add_options - Array of objects

Changes the options presented in the add dropdown menu list.

_enabled_editors - Array of strings

Controls how your team edits specific files, use this to set a preferred editor and/or disable the others. The first value sets which editor opens from the collection list, the other values specify which editors are accessible. Available values are visual and content for the Visual Editor and Content Editor, respectively. The Source Editor is always available for those with permission.

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.

output - Boolean

Whether or not files in this collection produce files in the build output.

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.

title - String

Alias for name.