The configuration cascade is a set of sources containing customizable options for the editor. Each source has a different scope and priority. This allows you to set global defaults and override those for specific collections or files.
When CloudCannon needs an option you have set in the configuration cascade, it looks at each scope in order. In most cases, the cascade stops looking when an option is found. This means the most specific value is used in place of any less specific values.
Input configuration (i.e. _inputs) has a different cascading default, where CloudCannon continues looking over less specific sources to merge into a single option.
Sources#
The configuration cascade sources are as follows, from lowest priority to highest:
- CloudCannon configuration file
- Collection configuration
- Schema configuration
- Front matter
- Containing structure
Global configuration
For configuring everywhere on your site. For example:
_inputs:
image_path:
type: image
comment: Helpful message here
options:
width: 90
height: 120
_select_data:
colors:
- Red
- Blue{
"_inputs": {
"image_path": {
"type": "image",
"comment": "Helpful message here",
"options": {
"width": 90,
"height": 120
}
}
},
"_select_data": {
"colors": [
"Red",
"Blue"
]
}
}Collection configuration
For configuring all files within a collection. For example:
collections_config:
pages:
_inputs:
image_path:
type: image
comment: Helpful message here
options:
width: 90
height: 120
_select_data:
colors:
- Red
- Blue{
"collections_config": {
"pages": {
"_inputs": {
"image_path": {
"type": "image",
"comment": "Helpful message here",
"options": {
"width": 90,
"height": 120
}
}
},
"_select_data": {
"colors": [
"Red",
"Blue"
]
}
}
}
}Schema configuration
For configuring all files within one of a collection's schemas. For example:
collections_config:
pages:
schemas:
default:
path: schemas/page.md
_inputs:
image_path:
type: image
comment: Helpful message here
options:
width: 90
height: 120
landing_page:
path: schemas/landing-page.md
_select_data:
colors:
- Red
- Blue{
"collections_config": {
"pages": {
"schemas": {
"default": {
"path": "schemas/page.md",
"_inputs": {
"image_path": {
"type": "image",
"comment": "Helpful message here",
"options": {
"width": 90,
"height": 120
}
}
}
},
"landing_page": {
"path": "schemas/landing-page.md",
"_select_data": {
"colors": [
"Red",
"Blue"
]
}
}
}
}
}
}Front matter
For configuring a single file. For example:
image_path: /uploads/me.png
_inputs:
image_path:
type: image
comment: Helpful message here
options:
width: 90
height: 120
_select_data:
colors:
- Red
- Blue{
"image_path": "/uploads/me.png",
"_inputs": {
"image_path": {
"type": "image",
"comment": "Helpful message here",
"options": {
"width": 90,
"height": 120
}
}
},
"_select_data": {
"colors": [
"Red",
"Blue"
]
}
}image_path = "/uploads/me.png"
[_inputs.image_path]
type = "image"
comment = "Helpful message here"
[_inputs.image_path.options]
width = 90
height = 120
[_select_data]
colors = [ "Red", "Blue" ]Containing structure
For configuring inputs inside a structure. For example:
_structures:
gallery:
values:
- label: Image
icon: image
_inputs:
image:
type: image
options:
width: 50
height: 50
caption:
comment: Applies inside this structure
_select_data:
colors:
- Red
- Blue
value:
image: /uploads/placeholder.png
caption:
color:{
"_structures": {
"gallery": {
"values": [
{
"label": "Image",
"icon": "image",
"_inputs": {
"image": {
"type": "image",
"options": {
"width": 50,
"height": 50
}
},
"caption": {
"comment": "Applies inside this structure"
}
},
"_select_data": {
"colors": [
"Red",
"Blue"
]
},
"value": {
"image": "/uploads/placeholder.png",
"caption": null,
"color": null
}
}
]
}
}
}[[_structures.gallery.values]]
label = "Image"
icon = "image"
[_structures.gallery.values._inputs.image]
type = "image"
[_structures.gallery.values._inputs.image.options]
width = 50
height = 50
[_structures.gallery.values._inputs.caption]
comment = "Applies inside this structure"
[_structures.gallery.values._select_data]
colors = [ "Red", "Blue" ]
[_structures.gallery.values.value]
image = "/uploads/placeholder.png"For nested structured data, you can nest _structures alongside the other configuration groups inside a structure definition.
Options#
Since configuration cascade options can be defined alongside your data, they always begin with an underscore in an effort to avoid clashing with a key you would use.
The following configuration cascade options are available:
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.
Appears in: schemas.*, collections_config.*, file_config[*].
Show examplesHide examples
In this example, we have configured the Snippet tool for WYSIWYG toolbars in the blog Collection.
collections_config:
blog:
_editables:
content:
snippet: true{
"collections_config": {
"blog": {
"_editables": {
"content": {
"snippet": true
}
}
}
}
}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.
Appears in: schemas.*, collections_config.*, file_config[*].
Show examplesHide examples
In this example, we have enabled only the Content Editor in the blog Collection.
collections_config:
blog:
_enabled_editors:
- content{
"collections_config": {
"blog": {
"_enabled_editors": [
"content"
]
}
}
}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.
Appears in: create, [*], schemas.*, collections_config.*, file_config[*], pull_request_templates[*], commit_templates[*], Snippet.
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.
_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.
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"
]
}
}
}
}
}
}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.
Appears in: [*], create, schemas.*, collections_config.*, file_config[*], Snippet.
Show examplesHide examples
In this example, we have configured the blog_tags Multiselect input for the blog Collection.
collections_config:
blog:
_select_data:
blog_topics:
- Opinion
- Feature
- Resource{
"collections_config": {
"blog": {
"_select_data": {
"blog_topics": [
"Opinion",
"Feature",
"Resource"
]
}
}
}
}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.
Appears in: [*], create, schemas.*, collections_config.*, file_config[*], Snippet.
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.
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.
_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"
}
}
]
}
}
}