Choose your preferred SSG:
Choose your preferred SSG:

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.

Jekyll content

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
    description: Collection of staff members.
    documentation:
      url: https://example.com/documentation
      text: Read the documentation here.
    icon: people
    add_options:
      - name: Add Staff Member
        icon: person_add
    filter:
      exclude:
        - secret.yml

Hugo content

Eleventy content

Other content

add_options - Array of objects

Changes the options presented in the +Add menu in the collection file list. Defaults to an automatically generated list from schemas, or first file in that collection if no schemas are configured.

Read more about changing the default set of add options here.

disable_add - Boolean

Prevents users from adding new files in the collection file list if true.

Defaults to true for the Jekyll, Hugo and Eleventy data collection in the base data folder only (data sub-folders act as non-output collections). Otherwise, defaults to false.

disable_add_folder - Boolean

Prevents users from adding new folders in the collection file list if true.

Defaults to true for the Jekyll, Hugo and Eleventy data collection in the base data folder only (data sub-folders act as non-output collections). Otherwise, defaults to false.

disable_file_actions - Boolean

Prevents users from renaming, moving and deleting files in the collection file list if true.

Defaults to true for the Jekyll, Hugo and Eleventy data collection in the base data folder only (data sub-folders act as non-output collections). Otherwise, defaults to false.

description - String

Text or Markdown to show above the collection file list.

documentation - Object

Provides a custom link for documentation for editors shown above the collection file list. Contains the following fields:

  • url for the href value of the link (String, required).
  • text for the visible text used in the link (String). Defaults to Documentation.
  • icon for the icon displayed next to the link. Must be a Material Icon name. Defaults to auto_stories.
collections_config:
  data:
    documentation:
      url: "https://example.com/documentation/"
      text: Read more about your data collection
filter - Object

Controls which files are displayed in the collection list. Contains the following fields:

  • base defines the initial set of visible files in the collection file list. Defaults to all, or strict for the auto-discovered pages collection in Jekyll, Hugo and Eleventy. Must be one of:
    • all shows all collection-like files
    • none hides all files
    • strict shows the files found in the last build for this collection
  • exclude is a set of paths for files to be hidden. Paths here take priority over those listed in include.
  • include is a set of paths for files to be included. Has no effect if the files are already visible.

Both include and exclude override the initial set of visible files set with base. The paths for both are relative to the containing collection path.

It is unlikely you will ever need to set base to strict, unless it’s on a collection that contains other collection folders (e.g. pages in the root folder, and other collections in sub-folders).

collections_config:
  data:
    path: data
    filter:
      base: none
      include:
        - authors.csv
        - locations/offices.yml
  secrets:
    path: content/secrets
    filter:
      exclude:
        - top-secret.yml
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.

new_preview_url - String

Preview your unbuilt pages (e.g. drafts) to another page’s output URL. The Visual Editor will load that set preview URL and use the Data Bindings and Previews to render your new page without saving.

For example new_preview_url: /about/ will load the /about/ URL on new or unbuilt pages in the Visual Editor.

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.

schemas - Object

The set of schemas for this collection. Schemas are used when creating and editing files in this collection. Each entry corresponds to a schema that describes a data structure for this collection.

The keys in this object should match the values used for schema_key inside each of this collection’s files. default is a special entry and is used when a file has no schema.

Read more about schemas and the available options.

schema_key - String

The key used in each file to identify the schema that file uses. The value this key represents in each of this collection’s files should match the keys in schemas. Defaults to _schema.

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.

text_key - String

Defines a front matter field to use when displaying text 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