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.
collections:
staff:
output: truecollections_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{
"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",
"description": "Collection of staff members.",
"documentation": {
"url": "https://example.com/documentation",
"text": "Read the documentation here."
},
"add_options": [
{
"name": "Add Staff Member",
"icon": "person_add"
}
],
"filter": {
"exclude": [
"secret.yml"
]
}
}
}
}module.exports = {
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',
description: 'Collection of staff members.',
documentation: {
url: 'https://example.com/documentation',
text: 'Read the documentation here.'
},
add_options: [
{
name: 'Add Staff Member',
icon: 'person_add'
}
],
filter: {
exclude: [
'secret.yml'
]
}
}
}
};Hugo content
CloudCannon reads the files in the content and data folders from your Hugo site and automatically defines collections by default. The automatically defined collections are your top-level content sections keyed by folder name.
Add collections and/or extend configuration for automatically discovered collections in your global configuration under collections_config.
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
description: Collection of staff members.
documentation:
url: https://example.com/documentation
text: Read the documentation here.
add_options:
- name: Add Staff Member
icon: person_add
filter:
exclude:
- secret.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",
"description": "Collection of staff members.",
"documentation": {
"url": "https://example.com/documentation",
"text": "Read the documentation here."
},
"add_options": [
{
"name": "Add Staff Member",
"icon": "person_add"
}
],
"filter": {
"exclude": [
"secret.yml"
]
}
}
}
}module.exports = {
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',
description: 'Collection of staff members.',
documentation: {
url: 'https://example.com/documentation',
text: 'Read the documentation here.'
},
add_options: [
{
name: 'Add Staff Member',
icon: 'person_add'
}
],
filter: {
exclude: [
'secret.yml'
]
}
}
}
};Eleventy content
CloudCannon reads the pages, collections and data from your Eleventy site and automatically defines collections by default. The automatically defined collections match your Eleventy collections with files, keyed by name.
Add collections and/or extend configuration for automatically discovered collections in your global configuration under collections_config.
Each collection must have a unique path. Automatically discovered collections are only created if that path is not in use.
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
description: Collection of staff members.
documentation:
url: https://example.com/documentation
text: Read the documentation here.
add_options:
- name: Add Staff Member
icon: person_add
filter:
exclude:
- secret.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",
"description": "Collection of staff members.",
"documentation": {
"url": "https://example.com/documentation",
"text": "Read the documentation here."
},
"add_options": [
{
"name": "Add Staff Member",
"icon": "person_add"
}
],
"filter": {
"exclude": [
"secret.yml"
]
}
}
}
}module.exports = {
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',
description: 'Collection of staff members.',
documentation: {
url: 'https://example.com/documentation',
text: 'Read the documentation here.'
},
add_options: [
{
name: 'Add Staff Member',
icon: 'person_add'
}
],
filter: {
exclude: [
'secret.yml'
]
}
}
}
};Other content
Due to the flexible nature of other SSGs, collections are not automatically discovered. Define collections and configuration in your global configuration under collections_config.
collections_config:
staff:
path: content/staff_members
output: false
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
description: Collection of staff members.
documentation:
url: https://example.com/documentation
text: Read the documentation here.
add_options:
- name: Add Staff Member
icon: person_add
filter:
exclude:
- secret.yml
posts:
path: content/posts
output: true
parser: yaml
url: '/posts/{category|slugify}/[slug].html'{
"collections_config": {
"staff": {
"path": "content/staff_members",
"output": false,
"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",
"description": "Collection of staff members.",
"documentation": {
"url": "https://example.com/documentation",
"text": "Read the documentation here."
},
"add_options": [
{
"name": "Add Staff Member",
"icon": "person_add"
}
],
"filter": {
"exclude": [
"secret.yml"
]
}
},
"posts": {
"path": "content/posts",
"output": true,
"parser": "yaml",
"url": "/posts/{category|slugify}/[slug].html"
}
}
}module.exports = {
collections_config: {
staff: {
path: 'content/staff_members',
output: false,
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',
description: 'Collection of staff members.',
documentation: {
url: 'https://example.com/documentation',
text: 'Read the documentation here.'
},
add_options: [
{
name: 'Add Staff Member',
icon: 'person_add'
}
],
filter: {
exclude: [
'secret.yml'
]
}
},
posts: {
path: 'content/posts',
output: true,
parser: 'yaml',
url: '/posts/{category|slugify}/[slug].html'
}
}
};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.[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.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.
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.
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
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 filesnone hides all filesstrict shows the files found in the last build for this collectionexclude 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.
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.
