Define your collections

As of October 2024, this documentation is only applicable to Sites using Unified Configuration. For Sites that have not migrated to Unified Configuration, please read the documentation on our non-unified documentation website.

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.

Configuration#

Define collections and configuration in your CloudCannon configuration file under collections_config.

Here's a minimal configuration for two collections:

cloudcannon.config.yaml

copied

collections_config:
  posts:
    path: content/posts
    url: /posts/{category|slugify}/[slug].html
    icon: event_available
  staff:
    path: content/staff_members
    disable_url: true
    icon: people

cloudcannon.config.json

copied

{
  "collections_config": {
    "posts": {
      "path": "content/posts",
      "url": "/posts/{category|slugify}/[slug].html",
      "icon": "event_available"
    },
    "staff": {
      "path": "content/staff_members",
      "disable_url": true,
      "icon": "people"
    }
  }
}

Examples#

Here are a number of examples demonstrating how to extend your base collection configuration.

Setting custom sort options:

cloudcannon.config.yaml

copied

collections_config:
  staff:
    sort:
      key: surname
    sort_options:
      - key: surname
      - key: surname
        order: desc
      - key: start_date
        label: Longest employed first

cloudcannon.config.json

copied

{
  "collections_config": {
    "staff": {
      "sort": {
        "key": "surname"
      },
      "sort_options": [
        {
          "key": "surname"
        },
        {
          "key": "surname",
          "order": "desc"
        },
        {
          "key": "start_date",
          "label": "Longest employed first"
        }
      ]
    }
  }
}

Changing how the collection file list previews files:

cloudcannon.config.yaml

copied

collections_config:
  staff:
    preview:
      subtext:
        - key: role
      gallery:
        image:
          - key: profile_image
        fit: cover

cloudcannon.config.json

copied

{
  "collections_config": {
    "staff": {
      "preview": {
        "subtext": [
          {
            "key": "role"
          }
        ],
        "gallery": {
          "image": [
            {
              "key": "profile_image"
            }
          ],
          "fit": "cover"
        }
      }
    }
  }
}

Adding descriptive text and an external link to documentation above the collection file list:

cloudcannon.config.yaml

copied

collections_config:
  staff:
    description: Collection of staff members.
    documentation:
      url: https://example.com/documentation
      text: Read the documentation here.

cloudcannon.config.json

copied

{
  "collections_config": {
    "staff": {
      "description": "Collection of staff members.",
      "documentation": {
        "url": "https://example.com/documentation",
        "text": "Read the documentation here."
      }
    }
  }
}

Hiding certain files in the collection file list:

cloudcannon.config.yaml

copied

collections_config:
  staff:
    path: content/staff_members
    glob:
      - '**/*.yml'
      - '!secret.yml'

cloudcannon.config.json

copied

{
  "collections_config": {
    "staff": {
      "path": "content/staff_members",
      "glob": [
        "**/*.yml",
        "!secret.yml"
      ]
    }
  }
}

Changing the options when adding a new item within the collection file list:

cloudcannon.config.yaml

copied

collections_config:
  staff:
    add_options:
      - name: Add Staff Member
        icon: person
      - name: Add Contractor
        schema: contractor
        icon: engineering

cloudcannon.config.json

copied

{
  "collections_config": {
    "staff": {
      "add_options": [
        {
          "name": "Add Staff Member",
          "icon": "person"
        },
        {
          "name": "Add Contractor",
          "schema": "contractor",
          "icon": "engineering"
        }
      ]
    }
  }
}

Disabling adding items and folders, and preventing renaming, moving and deleting files within the collection file list:

cloudcannon.config.yaml

copied

collections_config:
  staff:
    disable_add: true
    disable_add_folder: true
    disable_file_actions: true

cloudcannon.config.json

copied

{
  "collections_config": {
    "staff": {
      "disable_add": true,
      "disable_add_folder": true,
      "disable_file_actions": true
    }
  }
}

Options#

Collection configuration entries have the following options available:

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.

create — Object or string#

The create path definition to control where new files are saved to inside this collection. Defaults to [relative_base_path]/{title|slugify}.md.

Read more details for create when choosing where to create new files.

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

icon — String#

Sets an icon to use alongside references to this collection. Must match Material Icon name. Defaults to the processed value of preview.icon if set, then falls back to wysiwyg for pages, event_available for posts, data_usage for data, and notes otherwise.

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.

url — String#

Used to specify the output URL for files in the collection. This is used when opening the Visual Editor, or copying the output URL for a file in the CloudCannon interface.

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.
[base_path] is the path of the file excluding filename, relative to site source.
[slug] is the filename, excluding extension. Is an empty string if this results in "index".
[filename] is the filename, including extension.
[ext] is the last extension, including ..
[relative_path] is the full path of the file, relative to the collection path.
[relative_base_path] is the path of the file excluding filename, relative to the collection path.
[full_slug] is an alias for [relative_base_path]/[slug]

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.
{date|year} is date from inside the file, with the 4-digit year extracted.
{date|month} is date from inside the file, with the 2-digit month extracted.
{date|day} is date from inside the file, with the 2-digit day extracted.

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.

disable_url — Boolean#

By default, CloudCannon will attempt to discover URLs within a collection automatically. This can be disabled to ensure files in a collection never have an output URL assigned.

path — String#

The top-most folder where the files in this collection are stored. It is relative to source. Each collection must have a unique path.

If the collection is automatically discovered (Jekyll, Hugo and Eleventy only), this is set for you. Automatically discovered collections are only created if their paths are not used by a manually configured collection.

If the collection is not automatically discovered (all SSGs excluding Jekyll, Hugo and Eleventy), this is required.

glob — Array of Strings#

This key applies a glob or globs to filter the Collection. Globs in this array are relative to the Collection path.

Globs can be positive (e.g. *.yml), or negative (e.g. !**/*.json). Files are included in a Collection if they match any positive globs and do not match any negative globs. If you do not define any positive globs, CloudCannon will include all non-developer files in a Collection unless they match a negative glob.

For more information about developer files, please read our documentation on the include_developer_files key.

For example, to include all files in the data folder except for the secret.yml file:

collections_config:
  data:
    path: data
    glob:
      - '!secret.yml'

To include only .yml files within the data folder or any nested folders:

collections_config:
  data:
    path: data
    glob:
      - '**/*.yml'

To include only .yml files, except for the secret.yml file:

collections_config:
  data:
    path: data
    glob:
      - '**/*.yml'
      - '!secret.yml'

include_developer_files — Boolean#

By default, CloudCannon excludes files that probably shouldn't be edited in a CMS, for example files like README.md or package.json. CloudCannon excludes these files even if you have configured globs to allow them.

This key enables you to see developer files in your Collection browser, assuming they are not filtered out by any configured globs. Defaults to false.

preview — Object#

The preview definition for changing the way collection items are previewed across the editor.

See the preview options documentation for detailed information on setting this option.

You can also set preview for each schema in your collection.

preview.gallery — Object#

Shows large image/icon preview per collection item. Has no default. See preview for details.

preview.gallery.fit defaults to contain, or cover for generated screenshots.
preview.gallery.image defaults to a generated screenshot for files with a matching file in the build output, otherwise the first top-level image-like data found.

preview.icon — Array, string or boolean#

Controls the icon shown on each collection item. Must match a Material Icon name. Defaults to checking the icon key then falls back to the containing collection's icon.

If set to false, no icon is displayed.

If image is set, it will cover icon when loaded successfully.

preview.image — Array, string or boolean#

Controls the image shown per collection item. Defaults to checking the keys thumbnail_image, thumbnail_image_path, image, and image_path in that order, then falls back to finding any top-level image-like field in the collection item's data.

If set to false, no image is displayed.

If no image is found, icon is displayed instead.

preview.metadata — Array#

Shows a list of items that can contain an image, icon and text per collection item. Has no default. See preview for details.

preview.subtext — Array, string or boolean#

Controls the supporting text per collection item. Defaults to the url key of the collection item, or the date key for blog-like collections.

If set to false, no subtext is displayed.

Subtext is hidden if text and subtext is the same. If there’s no text, subtext is used instead.

preview.text — Array, string or boolean#

Controls the main text shown per collection item. Defaults to checking the keys name and title, then falls back to the first text-like value found.

If set to false, no text is displayed.

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.

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_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 file list. Defaults to the first option in sort_options, then falls back descending path. As an exception, defaults to descending date for blog-like collections. 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

Selecting a sort order in-app from the available sort options stores that preference, taking priority over this option the next time the collection file list is opened.

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

title — String#

Alias for name.

Define your collections

Configuration#

Examples#

Options#

Related Articles