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#
specific doc
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.
The automatic configuration is a good start, but we recommend adding collections and/or extending configuration for automatically discovered collections in your global configuration under collections_config.
Here's a minimal configuration for two collections, with path and URL details automatically configured based on your Jekyll settings:
collections_config:
posts:
icon: event_available
staff:
icon: people
{
"collections_config": {
"posts": {
"icon": "event_available"
},
"staff": {
"icon": "people"
}
}
}module.exports = {
collections_config: {
posts: {
icon: "event_available"
},
staff: {
icon: "people"
}
}
};If required, you can prevent CloudCannon from automatically discovering collections by enabling the collections_config_override settings in your global configuration.
specific doc
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.
The automatic configuration is a good start, but we recommend adding collections and/or extending configuration for automatically discovered collections in your global configuration under collections_config.
Here's a minimal configuration for two collections, with path and URL details automatically configured based on your Hugo settings:
collections_config:
posts:
icon: event_available
staff:
icon: people
{
"collections_config": {
"posts": {
"icon": "event_available"
},
"staff": {
"icon": "people"
}
}
}module.exports = {
collections_config: {
posts: {
icon: "event_available"
},
staff: {
icon: "people"
}
}
};If required, you can prevent CloudCannon from automatically discovering collections by enabling the collections_config_override settings in your global configuration.
specific doc
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.
The automatic configuration is a good start, but we recommend adding collections and/or extending configuration for automatically discovered collections in your global configuration under collections_config.
Here's a minimal configuration for two collections, with path and URL details automatically configured based on your Eleventy settings:
collections_config:
posts:
icon: event_available
staff:
icon: people
{
"collections_config": {
"posts": {
"icon": "event_available"
},
"staff": {
"icon": "people"
}
}
}module.exports = {
collections_config: {
posts: {
icon: "event_available"
},
staff: {
icon: "people"
}
}
};If required, you can prevent CloudCannon from automatically discovering collections by enabling the collections_config_override settings in your global configuration.
specific doc
Define collections and configuration in your global configuration under collections_config.
Here's a minimal configuration for two collections:
collections_config:
posts:
path: content/posts
output: true
url: /posts/{category|slugify}/[slug].html
icon: event_available
staff:
path: content/staff_members
parser: yaml
output: false
icon: people
{
"collections_config": {
"posts": {
"path": "content/posts",
"output": true,
"url": "/posts/{category|slugify}/[slug].html",
"icon": "event_available"
},
"staff": {
"path": "content/staff_members",
"parser": "yaml",
"output": false,
"icon": "people"
}
}
}module.exports = {
collections_config: {
posts: {
path: "content/posts",
output: true,
url: "/posts/{category|slugify}/[slug].html",
icon: "event_available"
},
staff: {
path: "content/staff_members",
parser: "yaml",
output: false,
icon: "people"
}
}
};Examples#
Here are a number of examples demonstrating how to extend your base collection configuration.
Setting custom sort options:
collections_config:
staff:
sort:
key: surname
sort_options:
- key: surname
- key: surname
order: desc
- key: start_date
label: Longest employed first
{
"collections_config": {
"staff": {
"sort": {
"key": "surname"
},
"sort_options": [
{
"key": "surname"
},
{
"key": "surname",
"order": "desc"
},
{
"key": "start_date",
"label": "Longest employed first"
}
]
}
}
}module.exports = {
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:
collections_config:
staff:
preview:
subtext:
- key: role
gallery:
image:
- key: profile_image
fit: cover
{
"collections_config": {
"staff": {
"preview": {
"subtext": [
{
"key": "role"
}
],
"gallery": {
"image": [
{
"key": "profile_image"
}
],
"fit": "cover"
}
}
}
}
}module.exports = {
collections_config: {
staff: {
preview: {
subtext: [
{
key: "role"
}
],
gallery: {
image: [
{
key: "profile_image"
}
],
fit: "cover"
}
}
}
}
};Collection configuration now supports the new preview option. Read our migration guide if you are still using the old options: text_key, subtext_key and image_size.
Adding descriptive text and an external link to documentation above the collection file list:
collections_config:
staff:
description: Collection of staff members.
documentation:
url: https://example.com/documentation
text: Read the documentation here.
{
"collections_config": {
"staff": {
"description": "Collection of staff members.",
"documentation": {
"url": "https://example.com/documentation",
"text": "Read the documentation here."
}
}
}
}module.exports = {
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:
collections_config:
staff:
filter:
exclude:
- secret.yml
- external/mysterious-stranger.md
{
"collections_config": {
"staff": {
"filter": {
"exclude": [
"secret.yml",
"external/mysterious-stranger.md"
]
}
}
}
}module.exports = {
collections_config: {
staff: {
filter: {
exclude: [
"secret.yml",
"external/mysterious-stranger.md"
]
}
}
}
};Changing the options when adding a new item within the collection file list:
collections_config:
staff:
add_options:
- name: Add Staff Member
icon: person
- name: Add Contractor
schema: contractor
icon: engineering
{
"collections_config": {
"staff": {
"add_options": [
{
"name": "Add Staff Member",
"icon": "person"
},
{
"name": "Add Contractor",
"schema": "contractor",
"icon": "engineering"
}
]
}
}
}module.exports = {
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:
collections_config:
staff:
disable_add: true
disable_add_folder: true
disable_file_actions: true
{
"collections_config": {
"staff": {
"disable_add": true,
"disable_add_folder": true,
"disable_file_actions": true
}
}
}module.exports = {
collections_config: {
staff: {
disable_add: true,
disable_add_folder: true,
disable_file_actions: true
}
}
};Changing how items in this collection are referenced when relying on unconfigured defaults for other options:
collections_config:
staff:
singular_name: Staff Member
singular_key: staff_member
{
"collections_config": {
"staff": {
"singular_name": "Staff Member",
"singular_key": "staff_member"
}
}
}module.exports = {
collections_config: {
staff: {
singular_name: "Staff Member",
singular_key: "staff_member"
}
}
};Options#
Collection configuration entries have the following options available:
specific doc
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 tosource.[base_path]is the path of the file excluding filename, relative to sitesource.[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 collectionpath.[relative_base_path]is the path of the file excluding filename, relative to the collectionpath.[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 thetitlefrom inside the file.{id}is theidfrom inside the file.{title|lowercase}istitlefrom inside the file, lower cased.{category|slugify}iscategoryfrom inside the file, slugified.{tag|slugify|uppercase}istagfrom inside the file, slugified, then upper cased.{date|year}isdatefrom inside the file, with the 4-digit year extracted.{date|month}isdatefrom inside the file, with the 2-digit month extracted.{date|day}isdatefrom inside the file, with the 2-digit day extracted.
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.
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.
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.
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.
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.
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.
Text or Markdown to show above the collection file list.
Provides a custom link for documentation for editors shown above the collection file list. Contains the following fields:
urlfor thehrefvalue of the link (String, required).textfor the visible text used in the link (String). Defaults toDocumentation.iconfor the icon displayed next to the link. Must be a Material Icon name. Defaults toauto_stories.
collections_config:
data:
documentation:
url: "https://example.com/documentation/"
text: Read more about your data collection
Controls which files are displayed in the collection list. Contains the following fields:
basedefines the initial set of visible files in the collection file list. Defaults toall, orstrictfor the auto-discoveredpagescollection in Jekyll, Hugo and Eleventy. Must be one of:allshows all collection-like filesnonehides all filesstrictshows the files found in the last build for this collection
excludeis a set of paths for files to be hidden. Paths here take priority over those listed ininclude.includeis 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
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.
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.
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.
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.
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.
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.
Shows large image/icon preview per collection item. Has no default. See preview for details.
preview.gallery.fitdefaults tocontain, orcoverfor generated screenshots.preview.gallery.imagedefaults to a generated screenshot for files with a matching file in the build output, otherwise the first top-level image-like data found.
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.
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.
Shows a list of items that can contain an image, icon and text per collection item. Has no default. See preview for details.
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.
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.
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.
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.
Overrides the default singular input key of the collection. This is used for naming conventions for select and multiselect inputs.
Overrides the default singular display name of the collection. This is displayed in the collection add menu and file context menu.
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:
keydefines what field contains the value to sort on inside each collection item's data. Required.ordercontrols which sort values come first. Must be one ofasc,ascending,descordescending. Defaults toascending.
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.
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:
keydefines what field contains the value to sort on inside each collection item's data. Required.ordercontrols which sort values come first. Must be one ofasc,ascending,descordescending. Defaults toascending.labelis text to display in the sort option list. Defaults to generating a label fromkeyandorder.
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
Alias for name.