Collections Reference

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.

A Collection is a group of related files with a similar format (e.g., a folder of pages, blog posts, or data files). Collections are a core part of your CloudCannon CMS experience.

This article covers all keys available in CloudCannon for configuring your Collections. For more information, please read our documentation on Collections in general and configuring your Collections.

All Collections options are configured within the collections_config key in your CloudCannon configuration file.

collections_config — Object#

This key defines your Collections. The following nested keys are available for each Collection:

path
glob
name
singular_name
icon
url
disable_url
documentation
description
preview
sort
sort_options
_editables
_enabled_editors
_inputs
_select_data
_structures
add_options
create
disable_add
disable_add_folder
disable_file_actions
new_preview_url
schemas
schema_key
include_developer_files

By default, CloudCannon uses your source key to make assumptions about your Collections.

Show exampleHide example

In this example, we have configured a blog Collection. Key settings include two Schemas to populate files with different content, a Blog Tags input populated by a fixed data set, and a custom Create Path to generate file names from structured data.

cloudcannon.config.yaml

copied

collections_config:
  blog:
    path: content/blog
    glob:
      - '!_index.md'
    name: Blog
    icon: post_add
    url: /blog/
    documentation:
      url: https://example.com/travel-blog-style-guide
      text: Documentation
      icon: auto_stories
    description: |-
      This Collection is for *Travel blogs* and *Customer stories*.

      If your have any questions, please contact Heather.
    _editables: 
    _enabled_editors:
      - content
    _inputs:
      blog_tags:
        type: multiselect
        label: Blog type
        comment: Select a blog type
        context:
          open: false
          title: Help
          icon: help
          content: |
            Blog tags help our users filter articles by topic.
        options:
          values: _select_data.blog_topics
    _select_data:
      blog_topics:
        - Opinion
        - Feature
        - Resource
    create:
      extra_data:
        filename: '{date|year}-{date|month}-{date|day}-{title}'
      path: '[relative_base_path]/{filename|slugify}.[ext]'
    disable_add: false
    disable_add_folder: false
    disable_file_actions: false
    schemas:
      blog:
        path: schemas/travel_blog.md
        name: Blog Post
        icon: post_add
      customer_story:
        path: schemas/customer_story.md
        name: Customer Story
        icon: post_add
    schema_key: _blog_template
    include_developer_files: false

cloudcannon.config.json

copied

{
  "collections_config": {
    "blog": {
      "path": "content/blog",
      "glob": [
        "!_index.md"
      ],
      "name": "Blog",
      "icon": "post_add",
      "url": "/blog/",
      "documentation": {
        "url": "https://example.com/travel-blog-style-guide",
        "text": "Documentation",
        "icon": "auto_stories"
      },
      "description": "This Collection is for *Travel blogs* and *Customer stories*.\n\nIf your have any questions, please contact Heather.",
      "_editables": null,
      "_enabled_editors": [
        "content"
      ],
      "_inputs": {
        "blog_tags": {
          "type": "multiselect",
          "label": "Blog type",
          "comment": "Select a blog type",
          "context": {
            "open": false,
            "title": "Help",
            "icon": "help",
            "content": "Blog tags help our users filter articles by topic.\n"
          },
          "options": {
            "values": "_select_data.blog_topics"
          }
        }
      },
      "_select_data": {
        "blog_topics": [
          "Opinion",
          "Feature",
          "Resource"
        ]
      },
      "create": {
        "extra_data": {
          "filename": "{date|year}-{date|month}-{date|day}-{title}"
        },
        "path": "[relative_base_path]/{filename|slugify}.[ext]"
      },
      "disable_add": false,
      "disable_add_folder": false,
      "disable_file_actions": false,
      "schemas": {
        "blog": {
          "path": "schemas/travel_blog.md",
          "name": "Blog Post",
          "icon": "post_add"
        },
        "customer_story": {
          "path": "schemas/customer_story.md",
          "name": "Customer Story",
          "icon": "post_add"
        }
      },
      "schema_key": "_blog_template",
      "include_developer_files": false
    }
  }
}

In this example, we have configured a team Collection. Key settings include custom sorting options, add options, and Card previews.

cloudcannon.config.yaml

copied

collections_config:
  team:
    path: _data/team
    name: Our Team
    singular_name: Team Member
    icon: groups
    disable_url: true
    description: This Collection has a file for every member of our team!
    preview:
      text:
        - key: name
      subtext:
        - key: job_title
      icon:
        - key: profile_picture
    sort:
      key: name
      order: ascending
    sort_options:
      - key: name
        order: ascending
        label: Name (A-Z)
      - key: name
        order: descending
        label: Name (Z-A)
      - key: job_title
        order: ascending
        label: Job Title (A-Z)
      - key: date
        order: descending
        label: Job Title (Z-A)
    _enabled_editors:
      - data
    add_options:
      - name: Office Locations
        icon: map
        href: /our-offices
    schemas:
      manager:
        path: schemas/manager.yml
        name: Manager
        icon: face
      employee:
        path: schemas/employee.yml
        name: Employee
        icon: support_agent

cloudcannon.config.json

copied

{
  "collections_config": {
    "team": {
      "path": "_data/team",
      "name": "Our Team",
      "singular_name": "Team Member",
      "icon": "groups",
      "disable_url": true,
      "description": "This Collection has a file for every member of our team!",
      "preview": {
        "text": [
          {
            "key": "name"
          }
        ],
        "subtext": [
          {
            "key": "job_title"
          }
        ],
        "icon": [
          {
            "key": "profile_picture"
          }
        ]
      },
      "sort": {
        "key": "name",
        "order": "ascending"
      },
      "sort_options": [
        {
          "key": "name",
          "order": "ascending",
          "label": "Name (A-Z)"
        },
        {
          "key": "name",
          "order": "descending",
          "label": "Name (Z-A)"
        },
        {
          "key": "job_title",
          "order": "ascending",
          "label": "Job Title (A-Z)"
        },
        {
          "key": "date",
          "order": "descending",
          "label": "Job Title (Z-A)"
        }
      ],
      "_enabled_editors": [
        "data"
      ],
      "add_options": [
        {
          "name": "Office Locations",
          "icon": "map",
          "href": "/our-offices"
        }
      ],
      "schemas": {
        "manager": {
          "path": "schemas/manager.yml",
          "name": "Manager",
          "icon": "face"
        },
        "employee": {
          "path": "schemas/employee.yml",
          "name": "Employee",
          "icon": "support_agent"
        }
      }
    }
  }
}

Collection setup#

These keys configure how a Collection functions in CloudCannon.

path — String#

This key defines the folder path for the collection key in which it is nested.

The value for this key is relative to your Site source. Each Collection must have a unique path.

This key has no default.

Show exampleHide example

In this example, the files for the blog Collection are located in the content/blog folder.

cloudcannon.config.yaml

copied

collections_config:
  blog:
    path: content/blog

cloudcannon.config.json

copied

{
  "collections_config": {
    "blog": {
      "path": "content/blog"
    }
  }
}

glob — Array of Strings#

This key defines globs which filter the files visible in the Collection browser for a given Collection. Values 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.

Defining a negative glob for a Collection does not remove a file from the associated Collection folder in your Git repository. Similarly, defining a positive glob for a file in a folder outside your Collection path does not move the file.

This key has no default.

Show exampleHide example

In this example, the Collection browser will show all files in the data folder except for the secret.yml file.

cloudcannon.config.yaml

copied

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

cloudcannon.config.json

copied

{
  "collections_config": {
    "data": {
      "path": "data",
      "glob": [
        "!secret.yml"
      ]
    }
  }
}

In this example, the Collection browser will show only .yml files in the data folder or any nested folders.

cloudcannon.config.yaml

copied

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

cloudcannon.config.json

copied

{
  "collections_config": {
    "data": {
      "path": "data",
      "glob": [
        "**/*.yml"
      ]
    }
  }
}

In this example, the Collection browser will show only .yml files in the data folder, except for the secret.yml file.

cloudcannon.config.yaml

copied

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

cloudcannon.config.json

copied

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

url — String#

This key defines the output URL for files in a given Collection. CloudCannon uses the output URL in the Visual Editor, and on your Testing Domain and Custom Domain.

Values for this key can be a mix of plain text and template strings, and should begin and end with the / character. Template strings can contain data placholders and fixed placeholders, which CloudCannon will replace with the data it references when generating the output URL.

For more information about data placeholders and fixed placeholders, please read our documentation on configuring your template strings.

By default, CloudCannon will use the key name of the Collection.

Show exampleHide example

In this example, the output URL for files in this Collection will be /travel/ rather than the default /blog/.

cloudcannon.config.yaml

copied

collections_config:
  blog:
    url: /travel/[slug]/

cloudcannon.config.json

copied

{
  "collections_config": {
    "blog": {
      "url": "/travel/[slug]/"
    }
  }
}

disable_url — Boolean#

This key toggles whether CloudCannon will generate an output URL for a given Collection.

Setting this key to true will prevent CloudCannon from generating an output URL for a Collection.

By default, this key is false (i.e., generate an output URL for this Collection).

Show exampleHide example

In this example, data is an non-output Collection and we don't want output URLs generated.

cloudcannon.config.yaml

copied

collections_config:
  data:
    disable_url: true

cloudcannon.config.json

copied

{
  "collections_config": {
    "data": {
      "disable_url": true
    }
  }
}

include_developer_files — Boolean#

This key toggles whether CloudCannon removes developer files from your Collection browser. CloudCannon excludes files that probably shouldn't be edited in a CMS from your Collection browser, for example files like README.md or package.json. CloudCannon excludes these files even if you have configured globs to allow them.

Setting this key to true will allow CloudCannon to show developer files, assuming they are not filtered out by any configured globs.

By default, this key is false (i.e., do not include developer files).

Show exampleHide example

In this example, we want to see developer files in the Collection browser for the data Collection.

cloudcannon.config.yaml

copied

collections_config:
  data:
    include_developer_files: true

cloudcannon.config.json

copied

{
  "collections_config": {
    "data": {
      "include_developer_files": true
    }
  }
}

Collection display#

These keys configure how a Collection appears in CloudCannon.

name — String#

This key defines the display name for a Collection. The name appears in the Site Navigation and at the top of the Collection browser. Changing the display name does not affect the Collection key name.

By default, CloudCannon uses the Collection key name in title case (i.e., blog_files becomes "Blog Files").

Show exampleHide example

In this example, CloudCannon will call the blog Collection "Travel Blog" in the Site Navigation and the Collection browser.

cloudcannon.config.yaml

copied

collections_config:
  blog:
    name: Travel Blog

cloudcannon.config.json

copied

{
  "collections_config": {
    "blog": {
      "name": "Travel Blog"
    }
  }
}

description — String#

This key defines the description text that appears on the Collection browser page. Collection descriptions are useful for adding extra context for your team members.

CloudCannon supports a limited selection of Markdown formatting for the value of this key: links, bold, italic, subscript, superscript, and inline code.

This key has no default.

Show exampleHide example

cloudcannon.config.yaml

copied

collections_config:
  blog: |-
    description:|- This Collection is for *Travel blogs* and *Customer stories*.
    If your have any questions, please contact Heather.

cloudcannon.config.json

copied

{
  "collections_config": {
    "blog": "description:|- This Collection is for *Travel blogs* and *Customer stories*.\nIf your have any questions, please contact Heather."
  }
}

icon — String#

This key defines the icon for a Collection. Collection icons appear in the Site Navigation and are the default icon for Collection file Cards if you have not defined preview.icon.

For more information about the preview icon, please read our documentation on the preview key.

Values can be from Google's Material Icons library.

By default, CloudCannon uses the Material Icon with the closest name to your Collection key name.

Show exampleHide example

In this example, we have configured the post_add icon for the blog Collection.

cloudcannon.config.yaml

copied

collections_config:
  blog:
    icon: post_add

cloudcannon.config.json

copied

{
  "collections_config": {
    "blog": {
      "icon": "post_add"
    }
  }
}

documentation — Object#

This key defines the documentation link at the top of a Collection browser. Collection documentation is useful for assisting your team members.

The following nested keys are available:

url (required)
text
icon

This key has no default.

Show exampleHide example

In this example, the documentation link for the data Collection goes to CloudCannon Documentation.

cloudcannon.config.yaml

copied

collections_config:
  data:
    documentation:
      url: https://cloudcannon.com/documentation/
      text: CloudCannon Documentation
      icon: star

cloudcannon.config.json

copied

{
  "collections_config": {
    "data": {
      "documentation": {
        "url": "https://cloudcannon.com/documentation/",
        "text": "CloudCannon Documentation",
        "icon": "star"
      }
    }
  }
}

documentation.url — String#

This key defines the URL for the documentation link at the top of a Collection browser. You must define this key for the documentation object to function.

This key has no default.

Show exampleHide example

In this example, we have configured the blog Collection documentation link to go to example.com.

cloudcannon.config.yaml

copied

collections_config:
  blog:
    documentation:
      url: https://example.com

cloudcannon.config.json

copied

{
  "collections_config": {
    "blog": {
      "documentation": {
        "url": "https://example.com"
      }
    }
  }
}

documentation.text — String#

This key defines the link text for the documentation link at the top of a Collection browser.

By default, this key is Documentation.

Show exampleHide example

In this example, the text for the documentation link is CloudCannon Documentation.

cloudcannon.config.yaml

copied

collections_config:
  data:
    documentation:
      url: https://cloudcannon.com/documentation/
      text: CloudCannon Documentation

cloudcannon.config.json

copied

{
  "collections_config": {
    "data": {
      "documentation": {
        "url": "https://cloudcannon.com/documentation/",
        "text": "CloudCannon Documentation"
      }
    }
  }
}

documentation.icon — String#

This key defines the icon for the documentation link at the top of a Collection browser.

Values can be from Google's Material Icons library.

By default, this key is auto_stories.

Show exampleHide example

In this example, we have configured the star icon for the blog Collection documentation link.

cloudcannon.config.yaml

copied

collections_config:
  blog:
    documentation:
      url: https://www.cloudcannon.com/documentation/
      icon: star

cloudcannon.config.json

copied

{
  "collections_config": {
    "blog": {
      "documentation": {
        "url": "https://www.cloudcannon.com/documentation/",
        "icon": "star"
      }
    }
  }
}

preview — Object#

This key defines the appearance of a Card. You can configure Card preview for Collections, Schemas, Object inputs, Array inputs, Select and Multiselect inputs, Structures, the Structure modal, Snippets, and the Snippet modal.

The following nested keys are available:

text
subtext
icon
icon_color
image
metadata
gallery

This key has no default.

Show exampleHide example

In this example, we have configured the file Cards in the Collection browser.

cloudcannon.config.yaml

copied

collections_config:
  blog:
    preview:
      text:
        - key: title
      subtext:
        - key: author
      icon: edit_note
      icon_color:
        - key: color
        - '#ff0000'
      image:
        - key: image
      metadata:
        - template:
            - url
        - icon: event
          text:
            - template: Published on {date|date_long}
      gallery:
        - key: featured_image

cloudcannon.config.json

copied

{
  "collections_config": {
    "blog": {
      "preview": {
        "text": [
          {
            "key": "title"
          }
        ],
        "subtext": [
          {
            "key": "author"
          }
        ],
        "icon": "edit_note",
        "icon_color": [
          {
            "key": "color"
          },
          "#ff0000"
        ],
        "image": [
          {
            "key": "image"
          }
        ],
        "metadata": [
          {
            "template": [
              "url"
            ]
          },
          {
            "icon": "event",
            "text": [
              {
                "template": "Published on {date|date_long}"
              }
            ]
          }
        ],
        "gallery": [
          {
            "key": "featured_image"
          }
        ]
      }
    }
  }
}

For more information, please read our documentation on configuring your Card previews.

sort — Object#

This key defines how CloudCannon sorts your Collection files when you first open your Collection browser. Configuring this key allows you to sort your Collection using a structured data key in your files.

The following nested keys are available:

key (required)
order

By default, CloudCannon sorts your Collection files alphabetically by filename in ascending order by default. However, if you have configured the sort_options key, CloudCannon will use the first array item in sort_options.

If you use the Sort dropdown in your Collection browser to order your Collection files, CloudCannon will preferentially use your most recent sorting method over the value configured in the sort key.

Show exampleHide example

In this example, CloudCannon will sort files in the blog Collection by the date key in the frontmatter of each file, in descending order.

cloudcannon.config.yaml

copied

collections_config:
  blog:
    sort:
      key: date
      order: descending

cloudcannon.config.json

copied

{
  "collections_config": {
    "blog": {
      "sort": {
        "key": "date",
        "order": "descending"
      }
    }
  }
}

sort.key — String#

This key defines which key CloudCannon should use to sort files in your Collection browser. You must define this key for the sort object to function.

Value must be the name of a structured data key in your Collection files. If some files in your Collection do not have this data key, CloudCannon will sort those in ascending alphabetical order, after the file sorted by your data key in the Collection browser.

This key has no default.

Show exampleHide example

In this example, CloudCannon will sort files in the blog Collection by the date key in the frontmatter of each file, in descending order.

cloudcannon.config.yaml

copied

collections_config:
  blog:
    sort:
      key: date
      order: descending

cloudcannon.config.json

copied

{
  "collections_config": {
    "blog": {
      "sort": {
        "key": "date",
        "order": "descending"
      }
    }
  }
}

sort.order — String#

This key defines the order in which Collection files are sorted in your Collection browser. CloudCannon will sort files according to the value of sort.key.

Values can be one of the following: asc, ascending, desc, or descending.

By default, this key is ascending.

Show exampleHide example

In this example, CloudCannon will sort files in the blog Collection by the date key in the frontmatter of each file, in descending order.

cloudcannon.config.yaml

copied

collections_config:
  blog:
    sort:
      key: date
      order: descending

cloudcannon.config.json

copied

{
  "collections_config": {
    "blog": {
      "sort": {
        "key": "date",
        "order": "descending"
      }
    }
  }
}

sort_options — Array of Objects#

This key defines the options for the Sort dropdown in a Collection browser. Configuring sort options for a Collection will remove CloudCannon's default sorting options from the Sort dropdown.

The following nested keys are available for each entry in the sort_options array:

key (required)
order
label

By default, CloudCannon provides sorting options for path, file size, file creation time, and last modified, in ascending and descending order. CloudCannon will also read data keys from your early Collection files and provide options to sort by those key values.

Show exampleHide example

In this example, the Sort dropdown in the blog Collection browser only contains options for sorting by author and date in ascending and descending order.

cloudcannon.config.yaml

copied

collections_config:
  blog:
    sort_options:
      - key: author
        order: ascending
        label: Author (A-Z)
      - key: author
        order: descending
        label: Author (Z-A)
      - key: date
        order: ascending
        label: Date (Newest First)
      - key: date
        order: descending
        label: Date (Oldest First)

cloudcannon.config.json

copied

{
  "collections_config": {
    "blog": {
      "sort_options": [
        {
          "key": "author",
          "order": "ascending",
          "label": "Author (A-Z)"
        },
        {
          "key": "author",
          "order": "descending",
          "label": "Author (Z-A)"
        },
        {
          "key": "date",
          "order": "ascending",
          "label": "Date (Newest First)"
        },
        {
          "key": "date",
          "order": "descending",
          "label": "Date (Oldest First)"
        }
      ]
    }
  }
}

sort_options.key — String#

This key defines which key an option in the Sort dropdown should use to sort files in your Collection browser. You must define this key for every entry in the sort_options array for the object to function.

This key has no default.

Show exampleHide example

In this example, the "Author (A-Z)" option in the Sort dropdown will use the author key to sort files in the blog Collection browser.

cloudcannon.config.yaml

copied

collections_config:
  blog:
    sort_options:
      - key: author
        order: ascending
        label: Author (A-Z)

cloudcannon.config.json

copied

{
  "collections_config": {
    "blog": {
      "sort_options": [
        {
          "key": "author",
          "order": "ascending",
          "label": "Author (A-Z)"
        }
      ]
    }
  }
}

sort_options.order — String#

This key defines which order an option in the Sort dropdown should use to sort files in your Collection browser. CloudCannon will sort files according to the value of sort_options.key for each option in the Sort dropdown.

Values can be one of the following: asc, ascending, desc, or descending.

By default, this key is ascending.

Show exampleHide example

In this example, the "Author (A-Z)" option in the Sort dropdown will sort files in the blog Collection browser in ascending order.

cloudcannon.config.yaml

copied

collections_config:
  blog:
    sort_options:
      - key: author
        order: ascending
        label: Author (A-Z)

cloudcannon.config.json

copied

{
  "collections_config": {
    "blog": {
      "sort_options": [
        {
          "key": "author",
          "order": "ascending",
          "label": "Author (A-Z)"
        }
      ]
    }
  }
}

sort_options.label — String#

This key defines the label used for a file sorting option in the Sort dropdown.

This key has no default.

Show exampleHide example

In this example, the sorting method which uses the author key is called "Author (A-Z)" in the Sort dropdown.

cloudcannon.config.yaml

copied

collections_config:
  blog:
    sort_options:
      - key: author
        order: ascending
        label: Author (A-Z)

cloudcannon.config.json

copied

{
  "collections_config": {
    "blog": {
      "sort_options": [
        {
          "key": "author",
          "order": "ascending",
          "label": "Author (A-Z)"
        }
      ]
    }
  }
}

singular_name — String#

This key defines the singular noun for your Collection name. CloudCannon uses the singular noun in the + Add button in the top right of the Collection browser when you select the option to add a new file. This is useful if your Collection name is an irregular plural (e.g., "syllabi" or "syllabuses" to "syllabus").

By default, CloudCannon removes the s character from regular plurals to create a singular noun (e.g., "posts" to "post").

This key has no default.

Show exampleHide example

In this example, the + Add button option to add a Collection file will read "Add Team Member" rather that "Add Team".

cloudcannon.config.yaml

copied

collections_config:
  team:
    singular_name: Team Member

cloudcannon.config.json

copied

{
  "collections_config": {
    "team": {
      "singular_name": "Team Member"
    }
  }
}

Collection editing interfaces#

These keys configure how CloudCannon’s editing interfaces function for a Collection.

_editables — Object#

This key defines which Rich Text editors have custom configuration for the associated WYSIWYG toolbar.

The following nested keys are available:

content
block
link
text
image

This key has no default.

Show exampleHide example

In this example, we have configured the Snippet tool for WYSIWYG toolbars in the blog Collection.

cloudcannon.config.yaml

copied

collections_config:
  blog:
    _editables:
      content:
        snippet: true

cloudcannon.config.json

copied

{
  "collections_config": {
    "blog": {
      "_editables": {
        "content": {
          "snippet": true
        }
      }
    }
  }
}

For more information, please read our documentation on Rich Text editors.

_enabled_editors — Array#

This key defines which editing interfaces are available by default for files at a given level of the configuration cascade. Whether an editing interface is available for a specific file is determined by other factors.

Values can be one of the following: visual, content, or data. Specifying one or more editing interfaces will disable all unspecified editing interfaces. You cannot disable the Source Editor with this key.

By default, this key is set to visual, content, and data. If undefined at higher levels of the configuration cascade, _enabled_editables will default to any values configured in the CloudCannon configuration file.

Show exampleHide example

In this example, we have enabled only the Content Editor in the blog Collection.

cloudcannon.config.yaml

copied

collections_config:
  blog:
    _enabled_editors:
      - content

cloudcannon.config.json

copied

{
  "collections_config": {
    "blog": {
      "_enabled_editors": [
        "content"
      ]
    }
  }
}

For more information, please read our documentation on the Visual Editor, Content Editor, Data Editor, and Source Editor.

_inputs — Object#

This key defines which inputs are available at a given level of the configuration cascade.

The following nested keys are available for each input inside _inputs:

type
label
comment
context
hidden
instance_value
cascade
options

This key has no default. If undefined at higher levels of the configuration cascade, _inputs will default to any values configured in the CloudCannon configuration file.

Show exampleHide example

In this example, we have configured the blog_tags Multiselect input for the blog Collection.

cloudcannon.config.yaml

copied

collections_config:
  blog:
    _inputs:
      blog_tags:
        type: multiselect
        label: Blog type
        comment: Select a blog type
        context:
          open: false
          title: Help
          icon: help
          content: |
            Blog tags help our users filter articles by topic.
        options:
          values: _select_data.blog_topics

cloudcannon.config.json

copied

{
  "collections_config": {
    "blog": {
      "_inputs": {
        "blog_tags": {
          "type": "multiselect",
          "label": "Blog type",
          "comment": "Select a blog type",
          "context": {
            "open": false,
            "title": "Help",
            "icon": "help",
            "content": "Blog tags help our users filter articles by topic.\n"
          },
          "options": {
            "values": "_select_data.blog_topics"
          }
        }
      }
    }
  }
}

For more information, please read our documentation on inputs.

_select_data — Object#

This key defines defines fixed data sets to populate Select and Multiselect inputs at a given level of the configuration cascade.

This key has no default. If undefined at higher levels of the configuration cascade, _select_data will default to any values configured in the CloudCannon configuration file.

Show exampleHide example

In this example, we have configured the blog_tags Multiselect input for the blog Collection.

cloudcannon.config.yaml

copied

collections_config:
  blog:
    _select_data:
      blog_topics:
        - Opinion
        - Feature
        - Resource

cloudcannon.config.json

copied

{
  "collections_config": {
    "blog": {
      "_select_data": {
        "blog_topics": [
          "Opinion",
          "Feature",
          "Resource"
        ]
      }
    }
  }
}

For more information, please read our documentation on Select and Multiselect inputs.

_structures — Object#

This key defines which structures are available for Object inputs and Array inputs at a given level of the configuration cascade.

The following nested keys are available for each structure inside _structures:

style
id_key
values
hide_extra_inputs
reorder_inputs
remove_empty_inputs
remove_extra_inputs

This key has no default. If undefined at higher levels of the configuration cascade, _structures will default to any values configured in the CloudCannon configuration file.

Show exampleHide example

In this example, we want to populate an Array input in the blog Collection with Related Articles, including the name, description, and url fields.

cloudcannon.config.yaml

copied

collections_config:
  blog:
    _structures:
      related_articles:
        style: select
        values:
          - preview:
              text:
                - key: name
              subtext:
                - key: url
            value:
              name: 
              description: 
              url:

cloudcannon.config.json

copied

{
  "collections_config": {
    "blog": {
      "_structures": {
        "related_articles": {
          "style": "select",
          "values": [
            {
              "preview": {
                "text": [
                  {
                    "key": "name"
                  }
                ],
                "subtext": [
                  {
                    "key": "url"
                  }
                ]
              },
              "value": {
                "name": null,
                "description": null,
                "url": null
              }
            }
          ]
        }
      }
    }
  }
}

In this example, we want to populate an Array input with Staff members, including the name, job_description, and profile_picture fields for all staff types, and the url field for Managers only.

cloudcannon.config.yaml

copied

_structures:
  staff:
    style: modal
    hide_extra_inputs: false
    values:
      - value:
          _type: Employee
          name: 
          job_description: 
          profile_picture: 
        preview:
          text:
            - key: name
            - Employee
          subtext:
            - key: job_description
            - Description of position
          image:
            - key: profile_picture
          icon: support_agent
      - value:
          _type: Manager
          name: 
          job_description: 
          profile_picture: 
          url: 
        preview:
          text:
            - key: name
            - Manager
          subtext:
            - key: job_description
            - Description of position
          image:
            - key: profile_picture
          icon: face

cloudcannon.config.json

copied

{
  "_structures": {
    "staff": {
      "style": "modal",
      "hide_extra_inputs": false,
      "values": [
        {
          "value": {
            "_type": "Employee",
            "name": null,
            "job_description": null,
            "profile_picture": null
          },
          "preview": {
            "text": [
              {
                "key": "name"
              },
              "Employee"
            ],
            "subtext": [
              {
                "key": "job_description"
              },
              "Description of position"
            ],
            "image": [
              {
                "key": "profile_picture"
              }
            ],
            "icon": "support_agent"
          }
        },
        {
          "value": {
            "_type": "Manager",
            "name": null,
            "job_description": null,
            "profile_picture": null,
            "url": null
          },
          "preview": {
            "text": [
              {
                "key": "name"
              },
              "Manager"
            ],
            "subtext": [
              {
                "key": "job_description"
              },
              "Description of position"
            ],
            "image": [
              {
                "key": "profile_picture"
              }
            ],
            "icon": "face"
          }
        }
      ]
    }
  }
}

For more information, please read our documentation on structures.

Creating and updating pages#

These keys configure how you create new files and maintain existing files for a Collection.

schemas — Object#

This key defines which Schemas are available to populate files in this Collection. Defining a Schema for a collection will add it to the + Add button dropdown at the top right of the Collection browser.

The following nested keys are available for each Schema insdie schemas:

path
reorder_input
hide_extra_inputs
remove_empty_inputs
remove_extra_inputs
name
icon
preview
_editables
_enabled_editors
_inputs
_select_data
_structures
create
new_preview_url

This key has no default. If undefined, clicking the + Add button to add a new file to a Collection will clone the last file in the Collection and clear any markup content and the values of any structured data keys.

Show exampleHide example

In this example, the + Add button in the Collection browser has an option for Customer Story which will populate a new file in the blog Collection with the contents of the customer_story.mdx file. If the Schema file is updated, CloudCannon will preserve the old inputs to prevent you from losing structured data in older files.

cloudcannon.config.yaml

copied

collections_config:
  blog:
    schemas:
      customer_story:
        path: /schemas/customer_story.mdx
        reorder_inputs: true
        hide_extra_inputs: false
        remove_empty_inputs: false
        remove_extra_inputs: false
        name: Customer Story
        icon: notes

cloudcannon.config.json

copied

{
  "collections_config": {
    "blog": {
      "schemas": {
        "customer_story": {
          "path": "/schemas/customer_story.mdx",
          "reorder_inputs": true,
          "hide_extra_inputs": false,
          "remove_empty_inputs": false,
          "remove_extra_inputs": false,
          "name": "Customer Story",
          "icon": "notes"
        }
      }
    }
  }
}

In this example, the + Add button in the Collection browser has an option for Term Definition which will populate a new file in the glossary Collection with the contents of the glossary_term.yml file. The term_description input is configured specifically for files created with this Schema.

cloudcannon.config.yaml

copied

collections_config:
  glossary:
    schemas:
      term_definition:
        path: /schemas/glossary_term.yml
        name: Term Definition
        icon: abc
        _enabled_editors:
          - data
        _inputs:
          term_description:
            type: textarea
            comment: Keep this as short as possible (i.e., 125 characters).
            context:
              open: false
              title: Help
              icon: help
              content: Try not to use the term name in the description.
            options:
              show_count: true

cloudcannon.config.json

copied

{
  "collections_config": {
    "glossary": {
      "schemas": {
        "term_definition": {
          "path": "/schemas/glossary_term.yml",
          "name": "Term Definition",
          "icon": "abc",
          "_enabled_editors": [
            "data"
          ],
          "_inputs": {
            "term_description": {
              "type": "textarea",
              "comment": "Keep this as short as possible (i.e., 125 characters).",
              "context": {
                "open": false,
                "title": "Help",
                "icon": "help",
                "content": "Try not to use the term name in the description."
              },
              "options": {
                "show_count": true
              }
            }
          }
        }
      }
    }
  }
}

For more information, please read our documentation on Schemas.

schema_key — Array of Objects#

This key defines the name for the structured data key that references the Schema a file uses. CloudCannon automatically adds this key to the top of your file when you create it using a Schema.

Values which beginning with the _ character are hidden from the Data Editor and the sidebar of the Content and Visual Editors.

By default, this key is _schema.

Show exampleHide example

In this example, we want to make Schemas more friendly for our non-technical team members, so we have configured the schema key in the front matter of files in the blog Collection to be blog_template.

cloudcannon.config.yaml

copied

collections_config:
  blog:
    schema_key: _blog_template

cloudcannon.config.json

copied

{
  "collections_config": {
    "blog": {
      "schema_key": "_blog_template"
    }
  }
}

For more information, please read our documentation on Schemas.

add_options — Array of Objects#

This key defines the options available in the + Add button dropdown at the top right of your Collection browser. Configuring add options for a Collection will remove CloudCannon's default "Add a file" option from the + Add button dropdown.

The following nested keys are available for each standard entry in add_options:

name
icon
editor
base_path
collection
schema
default_content_file

The following nested keys are available for each URL entry in add_options:

name
icon
href

By default, CloudCannon adds the "Add a file" and "Create new folder" options to the + Add dropdown. Additionally, any Schemas you have configured for a Collection will also appear in the + Add dropdown. For more information on these options, please read our reference documentation on disable_add, disable_add_folder, and schemas.

Show exampleHide example

In this example, we want team members in the _posts Collection to create new files in theblog subfolder of the _drafts Collection. CloudCannon will open these files in the Content Editor.

cloudcannon.config.yaml

copied

collections_config:
  _posts:
    add_options:
      - name: Add draft blog
        icon: post_add
        editor: content
        base_path: /../_drafts/blog

cloudcannon.config.json

copied

{
  "collections_config": {
    "_posts": {
      "add_options": [
        {
          "name": "Add draft blog",
          "icon": "post_add",
          "editor": "content",
          "base_path": "/../_drafts/blog"
        }
      ]
    }
  }
}

In this example, the + Add button dropdown in the team Collection browser has a link to the Office Locations page on our live website.

cloudcannon.config.yaml

copied

collections_config:
  team:
    add_options:
      - name: Office Locations
        icon: map
        href: /our-offices

cloudcannon.config.json

copied

{
  "collections_config": {
    "team": {
      "add_options": [
        {
          "name": "Office Locations",
          "icon": "map",
          "href": "/our-offices"
        }
      ]
    }
  }
}

add_options.name — String#

This key defines the name of an option in the + Add button dropdown.

This key has no default, unless you have configured add_options.schema. In this case, this key defaults to the name of the matching Schema.

Show exampleHide example

In this example, the + Add button dropdown in the team Collection browser has a link to the Office Locations page on our live website.

cloudcannon.config.yaml

copied

collections_config:
  team:
    add_options:
      - name: Office Locations
        icon: map
        href: /our-offices

cloudcannon.config.json

copied

{
  "collections_config": {
    "team": {
      "add_options": [
        {
          "name": "Office Locations",
          "icon": "map",
          "href": "/our-offices"
        }
      ]
    }
  }
}

add_options.icon — String#

This key defines the icon for an option in the + Add button dropdown.

Values can be from Google's Material Icons library.

By default, this key is add, unless you have configured add_options.schema. In this case, this key defaults to the icon of the matching Schema.

Show exampleHide example

In this example, the + Add button dropdown in the team Collection browser has a link to the Office Locations page on our live website.

cloudcannon.config.yaml

copied

collections_config:
  team:
    add_options:
      - name: Office Locations
        icon: map
        href: /our-offices

cloudcannon.config.json

copied

{
  "collections_config": {
    "team": {
      "add_options": [
        {
          "name": "Office Locations",
          "icon": "map",
          "href": "/our-offices"
        }
      ]
    }
  }
}

add_options.editor — String#

This key defines which editing interface CloudCannon will use when you select an option from the + Add button dropdown.

Values can be one of the following: visual, content, or data.

By default, CloudCannon will open the new file in an appropriate editing interface for that file type. If CloudCannon cannot determine an appropriate editing interface, it will show a warning.

Show exampleHide example

In this example, we want new draft blog files to open in the Content Editor.

cloudcannon.config.yaml

copied

collections_config:
  _posts:
    add_options:
      - name: Add draft blog
        icon: post_add
        editor: content
        base_path: /../_drafts/blog

cloudcannon.config.json

copied

{
  "collections_config": {
    "_posts": {
      "add_options": [
        {
          "name": "Add draft blog",
          "icon": "post_add",
          "editor": "content",
          "base_path": "/../_drafts/blog"
        }
      ]
    }
  }
}

add_options.base_path — String#

This key defines a path for files created using an option in the + Add button dropdown. This path overrides the path for the current Collection and subfolder open in the Collection browser. This key is useful if you need to specify a specific subfolder within a Collection.

The value for this key is relative to your Collection path.

By default, this key is the path for the current Collection and subfolder open in the Collection browser.

Show exampleHide example

In this example, we want team members in the _posts Collection to create new files in theblog subfolder of the _drafts Collection rather than the current Collection browser they have open. By configuring the base_path value to /../_drafts/blog, new files will be created in a different Collection subfolder (i.e., _drafts) when a team member selects this option from the + Add button dropdown.

cloudcannon.config.yaml

copied

collections_config:
  _posts:
    add_options:
      - name: Add draft blog
        icon: post_add
        editor: content
        base_path: /../_drafts/blog

cloudcannon.config.json

copied

{
  "collections_config": {
    "_posts": {
      "add_options": [
        {
          "name": "Add draft blog",
          "icon": "post_add",
          "editor": "content",
          "base_path": "/../_drafts/blog"
        }
      ]
    }
  }
}

add_options.collection — String#

This key defines the Collection for files created using an option in the + Add button dropdown. This Collections overrides the current Collection open in the Collection browser.

The value for this key should be the key name of a Collection.

By default, this key is the current Collection open in the Collection browser.

Show exampleHide example

In this example, we want team members in the articles Collection to create new files in the new_articles Collection rather than the current Collection browser they have open. By configuring the collection value to new_articles, new files will be created in a different Collection (i.e., new_articles) when a team member selects this option from the + Add button dropdown.

cloudcannon.config.yaml

copied

collections_config:
  articles:
    add_options:
      - name: Add articles
        collection: new_articles
        schema: articles

cloudcannon.config.json

copied

{
  "collections_config": {
    "articles": {
      "add_options": [
        {
          "name": "Add articles",
          "collection": "new_articles",
          "schema": "articles"
        }
      ]
    }
  }
}

add_options.schema — String#

This key defines which Schema CloudCannon should use to populate a file created with an option in the + Add button dropdown. This Schema is relative to the Collection configured in add_options.collection. Configuring this key will override add_options.default_content_file.

The value for this key should be the key name of a Schema.

By default, this key is the default Schema in the Collection configured in add_options.collection.

Show exampleHide example

In this example, we want CloudCannon to populate new files with the contents of the articles Schema when a team member selects this option from the + Add button dropdown.

cloudcannon.config.yaml

copied

collections_config:
  articles:
    add_options:
      - name: Add articles
        collection: new_articles
        schema: articles

cloudcannon.config.json

copied

{
  "collections_config": {
    "articles": {
      "add_options": [
        {
          "name": "Add articles",
          "collection": "new_articles",
          "schema": "articles"
        }
      ]
    }
  }
}

add_options.default_content_file — String#

This key defines which file CloudCannon should use to populate a file created with an option in the + Add button dropdown if the Collection defined in add_options.collection has no Schemas configured. The add_options.schema key will override default_content_file.

This key has no default.

Show exampleHide example

In this example, we want CloudCannon to populate the initial contents of new files with event_template.yml.

cloudcannon.config.yaml

copied

collections_config:
  events:
    add_options:
      name: Add new event
      collection: upcoming_events
      default_content_file: event_template.yml

cloudcannon.config.json

copied

{
  "collections_config": {
    "events": {
      "add_options": {
        "name": "Add new event",
        "collection": "upcoming_events",
        "default_content_file": "event_template.yml"
      }
    }
  }
}

add_options.href — String#

This key defines the link for a URL option in the + Add button dropdown.

Values can be an external URL or an internal URL relative to the current Site.

This key has no default.

Show exampleHide example

In this example, the + Add button dropdown in the team Collection browser has a link to the Office Locations page on our live website.

cloudcannon.config.yaml

copied

collections_config:
  team:
    add_options:
      - name: Office Locations
        icon: map
        href: /our-offices

cloudcannon.config.json

copied

{
  "collections_config": {
    "team": {
      "add_options": [
        {
          "name": "Office Locations",
          "icon": "map",
          "href": "/our-offices"
        }
      ]
    }
  }
}

create — Object#

This key defines the path to which CloudCannon will save new files in a Collection. CloudCannon generates "Create Paths" when you open the Review changes modal.

The following nested keys are available:

path (required)
extra_data
publish_to
_inputs
_select_data
_structures

This key has no default.

Show exampleHide example

In this example, CloudCannon will generate a Create Path for new files in the blog Collection using the date and title structured data keys. For example, CloudCannon will generate a create path of blog/2024-10-31-spooky-getaway.md for a file with the date 31st October 2024 and the title "Spooky Getaway".

cloudcannon.config.yaml

copied

collections_config:
  blog:
    create:
      extra_data:
        filename: '{date|year}-{date|month}-{date|day}-{title}'
      path: '[relative_base_path]/{filename|slugify}.[ext]'

cloudcannon.config.json

copied

{
  "collections_config": {
    "blog": {
      "create": {
        "extra_data": {
          "filename": "{date|year}-{date|month}-{date|day}-{title}"
        },
        "path": "[relative_base_path]/{filename|slugify}.[ext]"
      }
    }
  }
}

For more information, please read our documentation on Create Paths.

disable_add — Boolean#

This key toggles whether team members can use the + Add button in the top right of the Collection browser to add files to a Collection. This key does not affect your ability to add files using the File browser.

Setting this key to true will prevent team members from adding new files through the Collection browser.

By default, this key is false (i.e., team members can add to the Collection) for most SSGs. For Eleventy, Hugo, and Jekyll, this key defaults to true for the data Collection (all subfolders in the data folder are non-output Collections).

If both disable_add anddisable_add_folder are set to true, and you have not defined any other add_options, then the + Add button will not appear in the top right of the Collection browser.

Show exampleHide example

In this example, we want to prevent team members from adding new files to the data Collection through the Collection browser.

cloudcannon.config.yaml

copied

collections_config:
  data:
    disable_add: true

cloudcannon.config.json

copied

{
  "collections_config": {
    "data": {
      "disable_add": true
    }
  }
}

disable_add_folder — Boolean#

This key toggles whether team members can use the + Add button in the top right of the Collection browser to add subfolders to a Collection. This key does not affect your ability to add subfolders using the File browser.

Setting this key to true will prevent team members from adding new subfolders through the Collection browser.

By default, this key is false (i.e., team members can add folders to the Collection) for most SSGs. For Eleventy, Hugo, and Jekyll, this key defaults to true for the data Collection (all subfolders in the data folder are non-output Collections).

Show exampleHide example

In this example, we want to prevent team members from adding new subfolders to the data Collection through the Collection browser.

cloudcannon.config.yaml

copied

collections_config:
  data:
    disable_add_folder: true

cloudcannon.config.json

copied

{
  "collections_config": {
    "data": {
      "disable_add_folder": true
    }
  }
}

disable_file_actions — Boolean#

This key toggles whether team members can use the Move, Clone, Rename, and Delete file actions in a Collections. You can access these file actions in the Context menu at the top right of a file Card in the Collection browser or in an editing interface. This key does not affect file actions in the File browser.

Setting this key to true will prevent team members from using file actions in the Collection browser.

By default, this key is false (i.e., team members can use file actions) for most SSGs. For Eleventy, Hugo, and Jekyll, this key defaults to true for the data Collection.

Show exampleHide example

In this example, we want to prevent team members from using file actions in the data Collection through the Collection browser.

cloudcannon.config.yaml

copied

collections_config:
  data:
    disable_file_actions: true

cloudcannon.config.json

copied

{
  "collections_config": {
    "data": {
      "disable_file_actions": true
    }
  }
}

new_preview_url — String#

This key defines a new URL for previewing your unbuilt pages in the Visual Editor. The Visual Editor will load the new preview URL and use Data Bindings and Previews to render your page without saving or building.

This key does not affect the URL for your Testing Domain or Custom Domain.

This key has no default.

Show exampleHide example

In this example, the Visual Editor will open the /about/ page when you open an unbuilt page from the blog Collection.

cloudcannon.config.yaml

copied

collections_config:
  blog:
    new_preview_url: /about/

cloudcannon.config.json

copied

{
  "collections_config": {
    "blog": {
      "new_preview_url": "/about/"
    }
  }
}