collections_config.*

Description:

This key defines your Collections, which are the sets of content files for your site grouped by folder.

Appears in:

└── collections_config
    └── *

collections_config
- *

Type:

Object

Properties:

add_optionsArray<add_options[*]>#

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.

Additionally, any Schemas you have configured for a Collection will also appear in the + Add dropdown.

Show examplesHide examples

In this example, we have configured two standard add options for the people Collection. The first option uses the employee Schema, and the second option uses the contractor Schema and opens files in the Data Editor.

Copied to clipboard

collections_config:
  people:
    add_options:
      - name: Add Staff Member
        schema: employee
        icon: face
        editor: data
      - name: Add Contractor
        icon: support_agent
        schema: contractor
        editor: data
    schemas:
      employee:
        path: /.cloudcannon/schemas/employee.yml
      contractor:
        path: /.cloudcannon/schemas/contractor.yml

{
  "collections_config": {
    "people": {
      "add_options": [
        {
          "name": "Add Staff Member",
          "schema": "employee",
          "icon": "face",
          "editor": "data"
        },
        {
          "name": "Add Contractor",
          "icon": "support_agent",
          "schema": "contractor",
          "editor": "data"
        }
      ],
      "schemas": {
        "employee": {
          "path": "/.cloudcannon/schemas/employee.yml"
        },
        "contractor": {
          "path": "/.cloudcannon/schemas/contractor.yml"
        }
      }
    }
  }
}

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

Copied to clipboard

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

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

createObject#

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.

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

Show examplesHide examples

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".

Copied to clipboard

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

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

descriptionstring#

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 examplesHide examples

In this example, we have configured a description for the blog Collection with markdown formatting.

Copied to clipboard

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

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

disable_addboolean#

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.

Setting this key to true will prevent team members from adding new files through the Collection browser. This key does not affect your ability to add files using the File browser.

If both disable_add and disable_add_folder are set to true, the + Add button will not appear in the top right of the Collection browser.

Defaults to: false

Show examplesHide examples

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

Copied to clipboard

collections_config:
  data:
    disable_add: true

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

disable_add_folderboolean#

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.

Setting this key to true will prevent team members from adding new subfolders through the Collection browser. This key does not affect your ability to add subfolders using the File browser.

If both disable_add and disable_add_folder are set to true, the + Add button will not appear in the top right of the Collection browser.

Defaults to: false

Show examplesHide examples

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

Copied to clipboard

collections_config:
  data:
    disable_add_folder: true

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

disable_file_actionsboolean#

This key toggles whether team members can use the Move, Clone, Rename, and Delete file actions in a Collection. You can normally 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.

Setting this key to true will prevent team members from using file actions in the Collection browser. This key does not affect file actions in the File browser.

Defaults to: false

Show examplesHide examples

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

Copied to clipboard

collections_config:
  data:
    disable_file_actions: true

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

disable_urlboolean#

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.

Defaults to: false

Show examplesHide examples

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

Copied to clipboard

collections_config:
  data:
    disable_url: true

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

documentationObject#

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

Collection documentation is useful for assisting your team members.

Show examplesHide examples

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

Copied to clipboard

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

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

_editablesObject#

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

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

Show examplesHide examples

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

Copied to clipboard

collections_config:
  blog:
    _editables:
      content:
        snippet: true

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

_editables_from_globArray<_editables_from_glob[*]>#

This key defines globs that filter which files CloudCannon should use for configuring Rich Text formatting.

Values in this array are relative to the root of your repository (i.e., /, not the value of source) and must end in the file extension .cloudcannon.editables.yml.

You can use this key anywhere you would use the _editables key in the configuration cascade.

This key has no default.

Show examplesHide examples

In this example, we have several WYSIWYG Toolbar Configuration Files in the .cloudcannon/editables/ folder, with each file containing multiple definitions. The value of the _editables_from_glob key tells CloudCannon all files in that folder that match the glob *.cloudcannon.editables.yml.

Copied to clipboard

_editables_from_glob:
  - /.cloudcannon/editables/*.cloudcannon.editables.yml

{
  "_editables_from_glob": [
    "/.cloudcannon/editables/*.cloudcannon.editables.yml"
  ]
}

Copied to clipboard

text:
  bold: true
  italic: true
  underline: true
block:
  format: p h3
  undo: true
  redo: true
link:
  bold: true
  italic: true
  underline: true

{
  "text": {
    "bold": true,
    "italic": true,
    "underline": true
  },
  "block": {
    "format": "p h3",
    "undo": true,
    "redo": true
  },
  "link": {
    "bold": true,
    "italic": true,
    "underline": true
  }
}

_enabled_editorsArray<_enabled_editors[*]>#

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.

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

Show examplesHide examples

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

Copied to clipboard

collections_config:
  blog:
    _enabled_editors:
      - content

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

globGlob Array|Glob#

This key defines globs which filter the files visible in the Collection browser for a given Collection.

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.

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.

Show examplesHide examples

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

Copied to clipboard

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

{
  "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.

Copied to clipboard

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

{
  "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.

Copied to clipboard

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

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

iconstring#

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 Symbols library.

Defaults to: notes

Allowed values: 123 360 10k 10mp 11mp 12mp 13mp 14mp 15mp 16mp and 3574 more.

Show examplesHide examples

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

Copied to clipboard

collections_config:
  blog:
    icon: post_add

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

include_developer_filesboolean#

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.

Defaults to: false

Show examplesHide examples

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

Copied to clipboard

collections_config:
  data:
    include_developer_files: true

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

_inputsObject<_inputs.*>#

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

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 examplesHide examples

In this example, we have configured the date_created key as a Date and Time Input, which will automatically populate when you create a file using this input. Editors cannot alter this input as the interface is disabled.

Copied to clipboard

_inputs:
  date_created:
    type: datetime
    label: Date of article creation
    comment: UTC +0 timezone
    context:
      open: false
      title: Help
      icon: help
      content: This date field will automatically populate when you create an article.
    hidden: false
    disabled: true
    instance_value: NOW
    cascade: true
    options:
      timezone: Etc/UTC

{
  "_inputs": {
    "date_created": {
      "type": "datetime",
      "label": "Date of article creation",
      "comment": "UTC +0 timezone",
      "context": {
        "open": false,
        "title": "Help",
        "icon": "help",
        "content": "This date field will automatically populate when you create an article."
      },
      "hidden": false,
      "disabled": true,
      "instance_value": "NOW",
      "cascade": true,
      "options": {
        "timezone": "Etc/UTC"
      }
    }
  }
}

In this example, we have configured the blog_tags key as a Multiselect Input in the blog Collection.

Copied to clipboard

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:
            - Opinion
            - Feature
            - Resource

{
  "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": [
              "Opinion",
              "Feature",
              "Resource"
            ]
          }
        }
      }
    }
  }
}

_inputs_from_globArray<_inputs_from_glob[*]>#

This key defines globs that filter which files CloudCannon should use for Input configuration.

Values in this array are relative to the root of your repository (i.e., /, not the value of source) and must end in the file extension .cloudcannon.inputs.yml.

You can use this key anywhere you would use the _inputs key in the configuration cascade.

This key has no default.

Show examplesHide examples

In this example, we have several Input Configuration Files in the .cloudcannon/inputs/ folder, with each file containing multiple Input definitions. The value of the _inputs_from_glob key tells CloudCannon to only use the seo.cloudcannon.inputs.yml and blog-details.cloudcannon.inputs.yml files in that folder.

Copied to clipboard

collections_config:
  posts:
    path: content/posts
    icon: event
    inputs_from_glob:
      - /.cloudcannon/inputs/seo.cloudcannon.inputs.yml
      - /.cloudcannon/inputs/blogDetails.cloudcannon.inputs.yml

{
  "collections_config": {
    "posts": {
      "path": "content/posts",
      "icon": "event",
      "inputs_from_glob": [
        "/.cloudcannon/inputs/seo.cloudcannon.inputs.yml",
        "/.cloudcannon/inputs/blogDetails.cloudcannon.inputs.yml"
      ]
    }
  }
}

Copied to clipboard

seo_title:
  type: text
  options:
    required: true
    max_length: 50
seo_description:
  type: textarea
  options:
    show_count: true
    required: true
    max_length: 125
seo_image:
  type: image
  options:
    path:
      uploads: images
    accepts_mime_types:
      - image/png
      - image/jpeg
    required: true
    pattern: (?i)\.(jpe?g|png)$
    pattern_message: Please select a JPG or PNG image file

{
  "seo_title": {
    "type": "text",
    "options": {
      "required": true,
      "max_length": 50
    }
  },
  "seo_description": {
    "type": "textarea",
    "options": {
      "show_count": true,
      "required": true,
      "max_length": 125
    }
  },
  "seo_image": {
    "type": "image",
    "options": {
      "path": {
        "uploads": "images"
      },
      "accepts_mime_types": [
        "image/png",
        "image/jpeg"
      ],
      "required": true,
      "pattern": "(?i)\\.(jpe?g|png)$",
      "pattern_message": "Please select a JPG or PNG image file"
    }
  }
}

namestring#

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 examplesHide examples

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

Copied to clipboard

collections_config:
  blog:
    name: Travel Blog

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

new_preview_urlstring#

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 Editable Regions, or 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.

Show examplesHide examples

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

Copied to clipboard

collections_config:
  blog:
    new_preview_url: /about/

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

pathstring Required#

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.

Show examplesHide examples

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

Copied to clipboard

collections_config:
  blog:
    path: content/blog

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

previewObject#

This key defines the appearance of a Card.

You can configure Card preview for Collections, Schemas, Object inputs, Array inputs, Select inputs, Structures, the Structure modal, Snippets, and the Snippet modal.

For more information about previews, please read our documentation on configuring card previews.

Show examplesHide examples

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

Copied to clipboard

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

{
  "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"
          }
        ]
      }
    }
  }
}

In this example, we have configured the appearance of Cards in inputs using the Structure staff.

Copied to clipboard

_structures:
  staff:
    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

{
  "_structures": {
    "staff": {
      "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"
          }
        }
      ]
    }
  }
}

schema_keystring#

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.

Show examplesHide examples

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.

Copied to clipboard

collections_config:
  blog:
    schema_key: _blog_template

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

schemasObject<schemas.*>#

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.

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 examplesHide examples

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.

Copied to clipboard

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

{
  "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.

Copied to clipboard

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

{
  "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
              }
            }
          }
        }
      }
    }
  }
}

schemas_from_globArray<schemas_from_glob[*]>#

This key defines globs that filter which files CloudCannon should use for Schema configuration.

Values in this array are relative to the root of your repository (i.e., /, not the value of source) and must end in the file extension .cloudcannon.schemas.yml.

You can use this key anywhere you would use the schemas key.

This key has no default.

Show examplesHide examples

In this example, we have several Schemas Configuration Files in the .cloudcannon/schemas/ folder. The value of the schemas_from_glob key tells CloudCannon to use all files in that folder that match the glob *.cloudcannon.schemas.yml except for pages.cloudcannon.schemas.yml due to the negative glob.

Copied to clipboard

posts:
  path: content/posts
  icon: event
  schemas_from_glob:
    - /.cloudcannon/schemas/*.cloudcannon.schemas.yml
    - '!/.cloudcannon/schemas/pages.cloudcannon.schemas.yml'

{
  "posts": {
    "path": "content/posts",
    "icon": "event",
    "schemas_from_glob": [
      "/.cloudcannon/schemas/*.cloudcannon.schemas.yml",
      "!/.cloudcannon/schemas/pages.cloudcannon.schemas.yml"
    ]
  }
}

_select_dataObject<_select_data.*>#

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.

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

Show examplesHide examples

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

Copied to clipboard

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

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

singular_namestring#

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").

Show examplesHide examples

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

Copied to clipboard

collections_config:
  team:
    singular_name: Team Member

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

sort_optionsArray<sort_options[*]>#

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.

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 examplesHide examples

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.

Copied to clipboard

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)

{
  "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)"
        }
      ]
    }
  }
}

_structuresObject<Structure>#

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

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.

For more information, please read our documentation on structures.

Show examplesHide examples

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

Copied to clipboard

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

{
  "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.

Copied to clipboard

_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

{
  "_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"
          }
        }
      ]
    }
  }
}

_structures_from_globArray<_structures_from_glob[*]>#

This key defines globs that filter which files CloudCannon should use for Structure configuration.

Values in this array are relative to the root of your repository (i.e., /, not the value of source) and must end in the file extension .cloudcannon.structures.yml.

You can use this key anywhere you would use the _structures key in the configuration cascade.

Please see our documentation on values_from_glob for defining individual Structure values in a split Configuration File.

This key has no default.

Show examplesHide examples

In this example, we have several Structure Configuration Files in the .cloudcannon/structures/ folder. The value of the _structures_from_glob key tells CloudCannon to use the staffMembers.cloudcannon.structures.yml file in that folder.

Copied to clipboard

_structures_from_glob:
  - /.cloudcannon/structures/staffMembers.cloudcannon.structures.yml

{
  "_structures_from_glob": [
    "/.cloudcannon/structures/staffMembers.cloudcannon.structures.yml"
  ]
}

Copied to clipboard

staff:
  style: modal
  values:
    - label: Employee
      value:
        name: 
        job_description: 
        profile_picture: 
    - label: Manager
      value:
        name: 
        job_description: 
        profile_picture: 
        url:

{
  "staff": {
    "style": "modal",
    "values": [
      {
        "label": "Employee",
        "value": {
          "name": null,
          "job_description": null,
          "profile_picture": null
        }
      },
      {
        "label": "Manager",
        "value": {
          "name": null,
          "job_description": null,
          "profile_picture": null,
          "url": null
        }
      }
    ]
  }
}

urlstring#

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 placeholders 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.

Show examplesHide examples

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

Copied to clipboard

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

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

view_optionsArray<view_options[*]>#

This key defines the options for the View dropdown in the Collection browser.

The value is an array of view option strings. The first option listed is used as the default view.

Show examplesHide examples

In this example, we have configured three view options for the developer_articles Collection, with card as the default view.

Copied to clipboard

collections_config:
  developer_articles:
    path: developer/articles
    icon: article
    view_options:
      - card
      - list
      - gallery

{
  "collections_config": {
    "developer_articles": {
      "path": "developer/articles",
      "icon": "article",
      "view_options": [
        "card",
        "list",
        "gallery"
      ]
    }
  }
}

Examples:

User Articles

User Guides

User Glossary

Developer Articles

Developer Guides

Developer Reference

`collections_config.*`

Table of contents