Your CloudCannon configuration file allows you to customize your app experience by configuration CloudCannon's appearance and functionality.
This article covers all the keys available at the root level of your configuration file. To learn more about the configuration file, please read our documentation on the CloudCannon configuration file.
source: /
paths:
uploads: /assets/uploads
collections_config:
pages:
path: content
name: Pages
icon: wysiwyg
blog:
path: content/blog
name: Blog
icon: post_add
_enabled_editors:
- content
- data
data:
path: data
name: Site Elements
icon: important_devices
collection_groups:
- heading: Content
collections:
- pages
- blog
- heading: Data Files
collections:
- data
_enabled_editors:
- data
- content
- visual
_inputs:
blog_tags:
type: multiselect
options:
values: _select_data.blog_topics
_select_data:
blog_topics:
- Opinion
- Feature
- Resource
_structures:
example:
values:
- value:
name:
description:
image:
_editables:
content:
bold: true
italics: true
underline: true
_snippets_imports:
hugo:
include:
- hugo_youtube
- hugo_vimeo
_snippets:
base_url: documentation
data_config:
authors:
path: data/authors.csv
file_config:
- glob: data/locations.csv
_structures:
location_entries:
values:
- label: Location
value:
name:
lat:
long:
image:
editor:
default_path: /en/
source_editor:
tab_size: 2
show_gutter: false
theme: pastel_on_dark
timezone: Etc/UTC
commit_templates:
- template_string: '{message}'
markdown:
engine: commonmark
{
"source": "/",
"paths": {
"uploads": "/assets/uploads"
},
"collections_config": {
"pages": {
"path": "content",
"name": "Pages",
"icon": "wysiwyg"
},
"blog": {
"path": "content/blog",
"name": "Blog",
"icon": "post_add",
"_enabled_editors": [
"content",
"data"
]
},
"data": {
"path": "data",
"name": "Site Elements",
"icon": "important_devices"
}
},
"collection_groups": [
{
"heading": "Content",
"collections": [
"pages",
"blog"
]
},
{
"heading": "Data Files",
"collections": [
"data"
]
}
],
"_enabled_editors": [
"data",
"content",
"visual"
],
"_inputs": {
"blog_tags": {
"type": "multiselect",
"options": {
"values": "_select_data.blog_topics"
}
}
},
"_select_data": {
"blog_topics": [
"Opinion",
"Feature",
"Resource"
]
},
"_structures": {
"example": {
"values": [
{
"value": {
"name": null,
"description": null,
"image": null
}
}
]
}
},
"_editables": {
"content": {
"bold": true,
"italics": true,
"underline": true
}
},
"_snippets_imports": {
"hugo": {
"include": [
"hugo_youtube",
"hugo_vimeo"
]
}
},
"_snippets": null,
"base_url": "documentation",
"data_config": {
"authors": {
"path": "data/authors.csv"
}
},
"file_config": [
{
"glob": "data/locations.csv",
"_structures": {
"location_entries": {
"values": [
{
"label": "Location",
"value": {
"name": null,
"lat": null,
"long": null,
"image": null
}
}
]
}
}
}
],
"editor": {
"default_path": "/en/"
},
"source_editor": {
"tab_size": 2,
"show_gutter": false,
"theme": "pastel_on_dark"
},
"timezone": "Etc/UTC",
"commit_templates": [
{
"template_string": "{message}"
}
],
"markdown": {
"engine": "commonmark"
}
}Many of these configuration options have dedicated documentation. For more information, please read the documentation linked under each key description in the reference table.
Your CloudCannon configuration file has the following options available:
This key defines the base path for your source files, relative to the root folder of your repository. Unless you use a nested folder as the source for your Site you can leave this key empty or set it to /.
By default, this key is empty.
For more information, please read our documentation on the Site source folder in your configuration file.
This key enables you to define paths for your Rich Text editors or File inputs. The following nested keys are available:
dam_staticdam_uploadsdam_uploads_filenamestaticuploadsuploads_filenameuploads_use_relative_paths
This key has no default. If undefined at higher levels of the configuration cascade, paths will default to any values configured in the CloudCannon configuration file.
For more information, please read our documentation on Rich Text editors or File inputs.
This key defines your Collections.
The following nested keys are available for each Collection:
pathglobnamesingular_nameiconurldisable_urldocumentationdescriptionpreviewsortsort_options_editables_enabled_editors_inputs_select_data_structuresadd_optionscreatedisable_adddisable_add_folderdisable_file_actionsnew_preview_urlschemasschema_keyinclude_developer_files
By default, CloudCannon uses your source key to make assumptions about your Collections.
For more information, please read our documentation on Collections.
This key defines the groups and order of Collections in your Site Navigation. Each item in the array must contain the heading and collections keys.
The following nested keys are available for each entry in collection_groups:
headingcollections
This key has no default. If undefined, CloudCannon will sort your Collections in the following order: the Pages Collection, all output Collections in alphabetical order, then all non-output Collections in alphabetical order.
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.
collections_config:
blog:
_enabled_editors:
- content
{
"collections_config": {
"blog": {
"_enabled_editors": [
"content"
]
}
}
}For more information, please read our documentation on the Visual Editor, Content Editor, Data Editor, and Source Editor.
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:
typelabelcommentcontexthiddeninstance_valuecascadeoptions
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.
For more information, please read our documentation on inputs.
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.
collections_config:
blog:
_select_data:
blog_topics:
- Opinion
- Feature
- Resource
{
"collections_config": {
"blog": {
"_select_data": {
"blog_topics": [
"Opinion",
"Feature",
"Resource"
]
}
}
}
}For more information, please read our documentation on Select and Multiselect inputs.
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:
styleid_keyvalueshide_extra_inputsreorder_inputsremove_empty_inputsremove_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 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"
}
}
]
}
}
}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:
values:
- value:
name:
description:
url:
{
"collections_config": {
"blog": {
"_structures": {
"related_articles": {
"values": [
{
"value": {
"name": null,
"description": null,
"url": null
}
}
]
}
}
}
}
}For more information, please read our documentation on structures.
This key defines which Rich Text editors have custom configuration for the associated WYSIWYG toolbar.
The following nested keys are available:
contentblocklinktext
This key has no default.
For more information, please read our documentation on Rich Text editors.
This key defines snippet templates or libraries for your Site. Some libraries are SSG specific while others work for most SSGs.
The following nested keys are available:
docusaurus_mdxeleventy_liquideleventy_nunjuckshugojekyllmdxpython_markdown_extensions
This key has no default.
For more information, please read our documentation on Docusaurus Components, Eleventy Shortcodes, Hugo Shortcodes, MDX Components, or Python Markdown.
This key defines custom snippets for your Site.
The following nested keys are available for each snippet inside _snippets:
templateinlinepreviewdefinitions_inputs
This key has no default.
This key defines the base URL (or subpath) when generating output URLs for your Site. The base URL will prefix the output URL of each file.
This key has no default.
This key defines which file or folder data in your Site is available to populate Select and Multiselect inputs.
This key has no default.
For more information, please read our documentation on defining your data.
This key defines file-specific configuration without configuring a collection or modifying files.
The following nested keys are available for each entry in file_config:
glob(required)_select_data_structures_select_data_enabled_editors_inputs_editables
This key has no default.
This key defines the link for the Home button on the Dashboard page.
By default, this key is set to / (i.e., your index output URL).
This key defines the appearance and behavior of the Source Editor. The following nested keys are available:
tab_sizeshow_guttertheme
This key has no default.
For more information, please read our documentation on the Source Editor.
This key defines the timezone for your Site. Value must be in IANA timezone format.
By default, this key is Etc/UTC.
For more information, please read our documentation on Date and Time inputs.
This key defines your commit message templates. Commit messages appear on the Review changes modal when you save your changes.
This key has no default.
For more information, please read our documentation on commit templates.
This key defines your markdown engine for parsing Markdown content into HTML and any configuration options for your engine.
The following nested keys are available:
engineoptions
This key has no default.
For more information, please read our documentation on configuring your markdown engine.
Split Configuration Files#
These *_from_glob keys configure where CloudCannon should look for split Configuration Files. Each key must point to a file with the appropriate extension.
This key defines globs that filter which files CloudCannon should use for Collection 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.collections.yml. You can use this key anywhere you would use the collections_config key.
This key has no default.
Show exampleHide example
In this example, each Collection has its own Configuration File in the .cloudcannon/collections/ folder. The value of the collections_config_from_glob key tells CloudCannon to use all files in that folder that match the glob *.cloudcannon.collections.yml.
collections_config_from_glob:
- /.cloudcannon/collections/*.cloudcannon.collections.yml
{
"collections_config_from_glob": [
"/.cloudcannon/collections/*.cloudcannon.collections.yml"
]
}posts:
path: content/posts
icon: event
{
"posts": {
"path": "content/posts",
"icon": "event"
}
}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 exampleHide example
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.
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"
]
}
}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 exampleHide example
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.
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"
]
}
}
}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"
}
}
}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 exampleHide example
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.
_structures_from_glob:
- /.cloudcannon/structures/staffMembers.cloudcannon.structures.yml
{
"_structures_from_glob": [
"/.cloudcannon/structures/staffMembers.cloudcannon.structures.yml"
]
}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
}
}
]
}
}This key defines globs that filter which files CloudCannon should use for Structure value 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.structure-value.yml (note the singular form of "value"). You can use this key anywhere you would use the _structures.*.values key. Please see our documentation on structures_from_glob for defining a Structure in a split Configuration File.
This key has no default.
Show exampleHide example
In this example, the staff Array Input uses inline Structure values from the main Configuration File and also references another value from the boardMember.cloudcannon.structure_value.yml in the /.cloudcannon/structures/ folder.
_inputs:
staff:
type: array
options:
structures:
values_from_glob: /.cloudcannon/structures/boardMember.cloudcannon.structure-value.yml
values:
- label: Employee
value:
name:
title:
profile_picture:
- label: Manager
value:
name:
title:
profile_picture:
url:
{
"_inputs": {
"staff": {
"type": "array",
"options": {
"structures": null,
"values_from_glob": "/.cloudcannon/structures/boardMember.cloudcannon.structure-value.yml",
"values": [
{
"label": "Employee",
"value": {
"name": null,
"title": null,
"profile_picture": null
}
},
{
"label": "Manager",
"value": {
"name": null,
"title": null,
"profile_picture": null,
"url": null
}
}
]
}
}
}
}label: Board
value:
name:
title:
profile_picture:
url:
description:
{
"label": "Board",
"value": {
"name": null,
"title": null,
"profile_picture": null,
"url": null,
"description": null
}
}This key defines globs that filter which files CloudCannon should use for Snippet 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.snippets.yml. You can use this key anywhere you would use the _snippets key in the configuration cascade.
This key has no default.
Show exampleHide example
In this example, each Custom Snippet has its own Configuration File in the .cloudcannon/snippets/ folder. The value of the _snippets_from_glob key tells CloudCannon to use the callout.cloudcannon.snippets.yml file in that folder.
_snippets_imports:
eleventy_liquid: true
_snippets_from_glob:
- /.cloudcannon/snippets/callout.cloudcannon.snippets.yml
{
"_snippets_imports": {
"eleventy_liquid": true
},
"_snippets_from_glob": [
"/.cloudcannon/snippets/callout.cloudcannon.snippets.yml"
]
}callout:
template: eleventy_liquid_include
inline: false
preview:
text: Callout
definitions:
include_name: callout
named_args:
- source_key: type
editor_key: label
type: string
- editor_key: message
type: string
_inputs:
label:
type: select
options:
values:
- info
- warning
- error
{
"callout": {
"template": "eleventy_liquid_include",
"inline": false,
"preview": {
"text": "Callout"
},
"definitions": {
"include_name": "callout",
"named_args": [
{
"source_key": "type",
"editor_key": "label",
"type": "string"
},
{
"editor_key": "message",
"type": "string"
}
]
},
"_inputs": {
"label": {
"type": "select",
"options": {
"values": [
"info",
"warning",
"error"
]
}
}
}
}
}This key defines globs that filter which files CloudCannon should use for Collection 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.snippets-imports.yml. You can use this key anywhere you would use the _snippets_imports key in the configuration cascade.
This key has no default.
Show exampleHide example
In this example, we have several Snippet Configuration Files in the .cloudcannon/snippets/ folder. The value of the _snippets_import_from_glob key tells CloudCannon all files in that folder that match the glob *.cloudcannon.snippets-import.yml.
_snippets_imports_from_glob:
- /.cloudcannon/snippets/*.cloudcannon.snippets-imports.yml
{
"_snippets_imports_from_glob": [
"/.cloudcannon/snippets/*.cloudcannon.snippets-imports.yml"
]
}mdx: true
docusaurus_mdx:
exclude:
- docusaurus_mdx_truncate
{
"mdx": true,
"docusaurus_mdx": {
"exclude": [
"docusaurus_mdx_truncate"
]
}
}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 exampleHide example
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.
_editables_from_glob:
- /.cloudcannon/editables/*.cloudcannon.editables.yml
{
"_editables_from_glob": [
"/.cloudcannon/editables/*.cloudcannon.editables.yml"
]
}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
}
}