latest--cloudcannon-config.latest.schema
shared| Type | object |
|---|---|
| Schema URL | https://catalog.lintel.tools/schemas/schemastore/cloudcannon-configuration/_shared/latest--cloudcannon-config.latest.schema.json |
| Parent schema | cloudcannon-configuration |
The main CloudCannon configuration.
Properties
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 /.
For more information, please read our documentation on the Site source folder in your configuration file.
Examples
In this example, we have configured the source path to src so CloudCannon will look for source files in the src folder.
source: src
This key defines your Collections.
Examples
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.
collections_config:
blog:
path: content/blog
glob:
- '!_index.md'
name: Blog
icon: post_add
url: /blog/[full_slug]/
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
In this example, we have configured a team Collection. Key settings include custom sorting options, add options, and Card previews.
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
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.
Examples
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'
posts:
path: content/posts
icon: event
This key defines custom order and grouping for Collections in your Site Navigation.
The value is an array of group objects. Each group object must contain a heading key and a collections key.
If undefined, CloudCannon will sort your Collections in the order they are defined under the collections_config key.
Examples
In this example, we have configured Collection groups to organize Collections into "Content" and "Data Files" sections in the Site Navigation.
collection_groups:
- heading: Content
collections:
- pages
- blog
- heading: Data Files
collections:
- data
This key defines which base URL (or subpath) CloudCannon should use when matching output URLs for your Site.
The base URL will prefix the output URL of each file.
Examples
In this example, we have configured the base URL to /documentation/ so all output URLs will be prefixed with this path.
base_url: /documentation/
This key defines which file or folder data in your Site is available to populate Select Inputs.
Examples
In this example, we have configured data config to make data files available for Select Inputs and Multiselect Inputs.
data_config___1___:
authors:
path___2___: data/authors.csv
offices:
path___3___: data/offices
This key defines file-specific configuration without configuring a collection or modifying files.
This key has no default.
This key defines settings for the default editor actions on your site.
1 nested properties
This key defines the link for the Home button on the Dashboard page.
Examples
In this example, we have configured the Home button to link to /blog/ instead of the default /.
editor:
default_path: /blog/
This key defines the appearance and behavior of the Source Editor.
For more information, please read our documentation on the Source Editor.
Examples
In this example, we have configured the Source Editor with custom theme, tab size, and gutter settings.
source_editor:
theme: basic_dark
tab_size: 2
show_gutter: true
4 nested properties
This key defines the auto-indentation of each line and how many spaces a tab indentation counts as.
Examples
In this example, we have configured the Source Editor to use 2 spaces for tab indentation.
source_editor:
tab_size: 2
This key defines the color theme for syntax highlighting.
Examples
In this example, we have configured the Source Editor to use the dark theme for syntax highlighting.
source_editor:
theme: dark
This key toggles the gutter on the left of the editing interface, displaying line numbers and code folding controls.
Examples
In this example, CloudCannon will show the gutter with line numbers in the Source Editor.
source_editor:
show_gutter: true
This key toggles whether CloudCannon will enable soft wrapping of code in the Source Editor.
Setting this key to true will enable soft wrapping of code, allowing long lines to wrap to the next line without horizontal scrolling.
Examples
In this example, CloudCannon will enable soft wrapping of code in the Source Editor.
source_editor:
soft_wrap: true
This key defines the Pull Request templates available on your Site.
The value is an array of template objects. Each template object can contain optional label, title, body, template_path, and _inputs keys.
This key has no default.
Examples
In this example, we have two Pull Request templates in the pull_request_templates array.
pull_request_templates:
- label: General changes
_inputs:
title:
options:
required: true
body:
type: markdown
options:
bold: true
italic: true
link: true
format: p h1 h2 h3
- label: Delete content
title: Delete content
_inputs:
title:
options:
disabled: true
template_path: .github/templates/delete-content.md
This key defines commit message templates available when saving changes.
The value is an array of template objects. Each template object can contain optional label, template_path, template_string, wrap_width, extra_data, and _inputs keys.
Commit messages appear on the Review changes modal when you save your changes.
Examples
In this example, we have configured a commit template with a template string and input configuration.
commit_templates:
- label: Default
template_string: '{commit_type}: {message|trim}'
_inputs:
commit_type:
type: select
options:
allow_empty: true
values:
- feature
- fix
- test
cascade: true
In this example, we have configured a commit template that uses a file for the template content.
commit_templates:
- label: Commit message from file
template_path: /.git/commit-message.txt
In this example, we have configured a commit template with a template string, input configuration, and extra data for nested templates.
commit_templates:
- label: Breaking change
template_string: '{message}{breaking_change|if=breaking_change_message}'
_inputs:
breaking_change_message:
type: text
extra_data:
breaking_change: '⚠️ {breaking_change_message}'
This key defines the commit template to use when pulling changes from the upstream repository.
An upstream commit message template can contain plain text and placeholders. Placeholders insert data related to the commit and use [ ] brackets. CloudCannon supports the following commit placeholders:
[branch]— the name of the current branch.[publish_branch]— the name of the Publish Branch from which you merge upstream changes.[author]— the email address of the person responsible for the upstream merge.[date]— the date of the upstream merge in the format "Tue Nov 28 2023 21:46:17 GMT+0000".
Examples
In this example, we have configured a commit template with placeholders for upstream pulls.
upstream_commit_template: "Merge branch [publish_branch] into develop of [branch] by [author] at [date]"
This key defines your markdown engine for parsing Markdown content into HTML and any configuration options for your engine.
Examples
In this example, we have configured CloudCannon to use the commonmark Markdown engine with various options including attributes and attribute elements.
markdown:
engine: commonmark
options:
attributes: true
attributes_elements:
inline: none
block: space right
ul: below
ol: below
blockquote: below
p: below
img: below
hr: below
table: below
li: none
2 nested properties
This key defines which Markdown processing engine CloudCannon will use to convert between HTML and Markdown.
Examples
In this example, we have configured CloudCannon to use the kramdown Markdown engine.
markdown:
engine: kramdown
In this example, we have configured CloudCannon to use the commonmark Markdown engine with custom options.
markdown:
engine: commonmark
options:
html: true
breaks: true
This key defines configuration options for the Markdown processing engine.
The value is an object that can contain various options controlling how Markdown is converted to HTML and vice versa.
Examples
In this example, we have configured Markdown options to enable HTML output, convert line breaks, and enable GitHub Flavored Markdown.
markdown:
engine: commonmark
options:
html: true
breaks: true
gfm: true
19 nested properties
This key toggles whether CloudCannon will output HTML tags from source when converting Markdown to HTML.
Setting this key to true will allow HTML tags in the Markdown source to be output in the resulting HTML.
By default, this key is false (i.e., HTML tags in Markdown source are not output).
Examples
In this example, we have configured Markdown to output HTML tags from source.
markdown:
engine: commonmark
options:
html: true
This key toggles whether CloudCannon will use XHTML-style closing for single tags when converting Markdown to HTML.
Setting this key to true will use / to close single tags (e.g., <br /> instead of <br>).
By default, this key is false (i.e., single tags are not closed with /).
Examples
In this example, we have configured Markdown to use XHTML-style closing for single tags.
markdown:
engine: commonmark
options:
xhtml: true
This key toggles whether CloudCannon will convert line breaks (\n) in paragraphs into <br> tags when converting Markdown to HTML.
Setting this key to true will convert line breaks within paragraphs into <br> tags.
By default, this key is false (i.e., line breaks in paragraphs are not converted to <br> tags).
Examples
In this example, we have configured Markdown to convert line breaks in paragraphs into <br> tags.
markdown:
engine: commonmark
options:
breaks: true
This key toggles whether CloudCannon will automatically convert URL-like text to links when converting Markdown to HTML.
Setting this key to true will automatically convert text that looks like URLs into clickable links.
By default, this key is false (i.e., URL-like text is not automatically converted to links).
Examples
In this example, we have configured Markdown to automatically convert URL-like text to links.
markdown:
engine: commonmark
options:
linkify: true
This key toggles whether CloudCannon will enable typographic replacements and quote beautification when converting Markdown to HTML.
Setting this key to true will enable language-neutral replacements (such as dashes and ellipses) and beautify quotes based on the quotes configuration.
By default, this key is false (i.e., typographic replacements and quote beautification are disabled).
Examples
In this example, we have configured Markdown to enable typographic replacements and quote beautification.
markdown:
engine: commonmark
options:
typographer: true
quotes: '«»„""'
This key defines double and single quotes replacement pairs for quote beautification when typographer is enabled.
The value is a string that specifies quote pairs. For example, you can use "«»„"" for Russian, ""„"‚"" for German, and ["«\xA0", "\xA0»", "‹\xA0", "\xA0›"] for French (including nbsp).
This key only takes effect when typographer is enabled.
Examples
In this example, we have configured quote replacement pairs for Russian typography.
markdown:
engine: commonmark
options:
typographer: true
quotes: '«»„""'
This key toggles whether CloudCannon will output lists with an extra space when converting HTML to Markdown.
Setting this key to true will add an extra space in list items when outputting Markdown.
By default, this key is false (i.e., lists are output without an extra space).
Examples
In this example, we have configured Markdown to output lists with an extra space.
markdown:
engine: commonmark
options:
spaced_lists: true
This key toggles whether CloudCannon will add line breaks between sentences when converting HTML to Markdown.
Setting this key to true will add line breaks between sentences in the output Markdown.
By default, this key is false (i.e., line breaks are not added between sentences).
Examples
In this example, we have configured Markdown to add line breaks between sentences.
markdown:
engine: commonmark
options:
sentence_per_line: true
This key toggles whether CloudCannon will enable GitHub Flavored Markdown (GFM) mode when processing Markdown.
Setting this key to true will enable GFM mode, which includes features like tables, strikethrough, task lists, and autolinks.
By default, this key is false (i.e., GFM mode is disabled).
Examples
In this example, we have configured Markdown to enable GitHub Flavored Markdown mode.
markdown:
engine: commonmark
options:
gfm: true
This key defines which style of code block fences CloudCannon will use when converting HTML to Markdown.
The value can be \``(three backticks) or~~~` (three tildes).
Examples
In this example, we have configured Markdown to use tildes for code block fences.
markdown:
engine: commonmark
options:
code_block_fences: '~~~'
This key toggles whether CloudCannon will treat 4 spaces of indentation as a code block when processing Markdown.
Setting this key to true will read indented blocks (4 spaces) as code blocks.
By default, this key is false (i.e., indented blocks are not treated as code blocks).
Examples
In this example, we have configured Markdown to treat 4 spaces of indentation as code blocks.
markdown:
engine: commonmark
options:
treat_indentation_as_code: true
This key toggles whether CloudCannon will render snippets as plain text within code blocks when processing Markdown.
Setting this key to true will prevent snippets from being processed within code blocks, rendering them as plain text instead.
By default, this key is false (i.e., snippets within code blocks may be processed).
Examples
In this example, we have configured Markdown to render snippets as plain text within code blocks.
markdown:
engine: commonmark
options:
escape_snippets_in_code_blocks: true
This key toggles whether CloudCannon will output tables in Markdown format when converting HTML to Markdown.
Setting this key to true will convert HTML tables to Markdown table format.
By default, this key is false (i.e., tables are not output in Markdown format).
Examples
In this example, we have configured Markdown to output tables in Markdown format.
markdown:
engine: commonmark
options:
table: true
This key toggles whether CloudCannon will output strikethrough text wrapped in double tildes when converting HTML to Markdown.
Setting this key to true will output strikethrough text as ~~strike~~ in Markdown.
By default, this key is false (i.e., strikethrough text is not output in double tildes format).
Examples
In this example, we have configured Markdown to output strikethrough text wrapped in double tildes.
markdown:
engine: commonmark
options:
strikethrough: true
This key toggles whether CloudCannon will output subscript text wrapped in tildes when converting HTML to Markdown.
Setting this key to true will output subscript text as ~sub~ in Markdown.
By default, this key is false (i.e., subscript text is not output in tildes format).
Examples
In this example, we have configured Markdown to output subscript text wrapped in tildes.
markdown:
engine: commonmark
options:
subscript: true
This key toggles whether CloudCannon will output superscript text wrapped in carets when converting HTML to Markdown.
Setting this key to true will output superscript text as ^super^ in Markdown.
By default, this key is false (i.e., superscript text is not output in carets format).
Examples
In this example, we have configured Markdown to output superscript text wrapped in carets.
markdown:
engine: commonmark
options:
superscript: true
This key toggles whether CloudCannon will generate IDs for headings when converting Markdown to HTML.
Setting this key to true will automatically generate ID attributes for heading elements based on their text content.
By default, this key is false (i.e., IDs are not generated for headings).
Examples
In this example, we have configured Markdown to generate IDs for headings.
markdown:
engine: commonmark
options:
heading_ids: true
This key toggles whether CloudCannon will save element attributes in Markdown format instead of converting them to HTML when converting HTML to Markdown.
Setting this key to true will preserve element attributes in Markdown format (using attribute lists) rather than converting them to HTML.
By default, this key is false (i.e., element attributes are converted to HTML).
Examples
In this example, we have configured Markdown to save element attributes in Markdown format.
markdown:
engine: commonmark
options:
attributes: true
This key defines positioning behavior of Markdown attributes for different element types when converting HTML to Markdown.
The value is an object that can contain inline, block, or element-specific properties. Each property value specifies where attribute lists should be positioned for that element type. Valid values are none, right, space right, below, newline below, or right-of-prefix.
This key only takes effect when attributes is enabled.
Examples
In this example, we have configured attribute positioning for inline and block elements.
markdown:
engine: commonmark
options:
attributes: true
attribute_elements:
inline: right
block: below
2 nested properties
This key defines where attribute lists are positioned for inline elements when converting HTML to Markdown.
The value can be none, right, space right, below, newline below, or right-of-prefix. This applies to all inline elements unless overridden by element-specific configuration.
This key only takes effect when attributes is enabled.
Examples
In this example, we have configured inline elements to place attributes on the right.
markdown:
engine: commonmark
options:
attributes: true
attribute_elements:
inline: right
This key defines where attribute lists are positioned for block-level elements when converting HTML to Markdown.
The value can be none, right, space right, below, newline below, or right-of-prefix. This applies to all block-level elements unless overridden by element-specific configuration.
This key only takes effect when attributes is enabled.
Examples
In this example, we have configured block-level elements to place attributes below the element.
markdown:
engine: commonmark
options:
attributes: true
attribute_elements:
block: below
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.
Examples
In this example, we have enabled only the Content Editor in the blog Collection.
collections_config:
blog:
_enabled_editors:
- content
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.
Examples
In this example, we have configured the Snippet tool for WYSIWYG toolbars in the blog Collection.
collections_config:
blog:
_editables:
content:
snippet: true
5 nested properties
This key defines input options for the Content Editor.
44 nested properties
This key defines what format an image is converted to prior to upload.
Examples
In this example, we have configured an Image Input to convert images to WebP format prior to upload.
_inputs:
hero_image:
type: image
options:
mime_type: image/webp
This key defines how image files are resized prior to upload, using a bounding box defined by width and height options.
Valid values are cover, contain, crop, or stretch:
coverkeeps aspect ratio and ensures the image covers the bounding boxcontainkeeps aspect ratio and ensures the image fits inside the bounding boxcropprompts the user with and interface to select an aspect-ratio-respecting areastretchignores aspect ratio and resizes the image to the bounding box
This key does not apply to existing images, and does not work if width and height options are not defined.
Examples
In this example, we have configured an Image Input to resize images using the cover style to ensure images cover the bounding box while maintaining aspect ratio.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines the width of the bounding box used in the resizing method defined by resize_style.
This key defines the height of the bounding box used in the resizing method defined by resize_style.
Examples
In this example, we have configured the height of the bounding box for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines whether you can upscale an image to fit the bounding box while resizing an image prior to upload.
Has no effect if files are not resized.
Examples
In this example, we have configured an Image Input to allow upscaling images to fit the bounding box while resizing.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
expandable: true
This key toggles whether CloudCannon will instruct a rich text editor to save width and height attributes on image elements.
Setting this key to true will instruct the rich text editor to save width and height attributes on image elements. This can prevent pop-in as a page loads.
By default, this key is false (i.e., width and height attributes are not saved on image elements). This defaults to true if the Image Size Attributes site flag is enabled (this is enabled for sites created before June 23 2023, in order to keep those sites working).
Examples
In this example, CloudCannon will save width and height attributes on image elements in a Rich Text Input.
_inputs:
content:
type: markdown
options:
image_size_attributes: true
This key defines which sources and DAMs you are allowed to upload to and browse.
The value can be an array of strings. Valid values include site-files and the reference key for any DAM connected to your site.
If site-files is omitted from the array, site files will not be available as an asset source for this input.
Examples
In this example, we have configured allowed sources for an Image Input.
_inputs:
image:
type: image
options:
allowed_sources:
- site-files
- my-cloudinary-dam
This key toggles whether CloudCannon will skip the image resizing process configured for this input when selecting existing images.
Setting this key to true will skip the image resizing process when selecting existing images.
Examples
In this example, CloudCannon will skip the image resizing process when selecting existing images for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
prevent_resize_existing_files: true
This key defines definitions for creating additional images of different sizes when uploading or selecting existing files.
Examples
In this example, we have configured an Image Input to create additional images of different sizes when uploading or selecting files.
_inputs:
hero_image:
type: image
options:
sizes:
- size: 2x
- size: 3x
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to bold selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to bold selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to copy formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to copy formatting from selected text. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not copy other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to italicize selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to italicize selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to redo recent edits undone with undo.
Setting this key to true will enable a tool in your WYSIWYG toolbar to redo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to remove formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to remove formatting. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not remove other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to strike through selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to strike through selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to subscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to subscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to superscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to superscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to underline selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to underline selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to undo recent edits.
Setting this key to true will enable a tool in your WYSIWYG toolbar to undo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will allow you to strip custom markup from content edited in a rich text editor, allowing you to clean files of unnecessary HTML content.
Setting this key to true will enable stripping custom markup from content. The remove_custom_markup key is disabled if allow_custom_markup is enabled.
This key toggles whether CloudCannon will allow you to edit custom markup in rich text editors and explicitly accept the risk of unintentionally deleting elements that cannot be recreated.
Setting this key to true will enable editing of custom markup. When using allow_custom_markup outside of editable regions, content that uses JavaScript will not be editable for security reasons. These inputs will appear as uneditable snippets.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to wrap selected blocks of text in a block quote.
Setting this key to true will enable a tool in your WYSIWYG toolbar to wrap selected blocks of text in a block quote.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an unordered list or convert selected text to an unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an unordered list or convert selected text to an unordered list.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to center align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to center align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a control in your WYSIWYG toolbar to create an inline code element, containing any selected text.
Setting this key to true will enable a control in your WYSIWYG toolbar to create an inline code element.
By default, this key is false (i.e., the inline code control is not displayed).
This key toggles whether CloudCannon will display a control in your WYSIWYG toolbar to insert a code block in editable regions.
Setting this key to true will enable a control in your WYSIWYG toolbar to insert a code block.
By default, this key is false (i.e., the code block control is not displayed).
This key toggles whether CloudCannon will display tools in your WYSIWYG toolbar to turn selected text into inline code and selected text into a code block.
Setting this key to true will enable two tools in your WYSIWYG toolbar to turn selected text into inline code and selected text into a code block.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a region of raw HTML for YouTube, Vimeo, social media posts, or other media.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a region of raw HTML. Embedded content is sanitized to mitigate XSS risks, which includes removing style tags. Embeds containing script tags are not loaded a rich text editor.
This key toggles whether CloudCannon will display a dropdown menu tool in your WYSIWYG toolbar for structured text.
Setting this key to true will enable a dropdown menu tool in your WYSIWYG toolbar for structured text. Valid values include for p, h1, h2, h3, h4, h5, h6, pre, address, and div. Include a space between each values, e.g. format: p h1 h2.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a horizontal line.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a horizontal line.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an image and enter alternative text and title text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an image. Select an existing image, upload an image, or use an external link.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to increase the indentation of a list item in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to increase the indentation of a list item.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to justify selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to justify selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to left align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to left align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an ordered list or convert selected text to an ordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an ordered list or convert selected text to an ordered list.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to decrease the indentation of a list item in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to decrease the indentation of a list item.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to right align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to right align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a Snippet, if any are available.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a Snippet.
This key toggles whether CloudCannon will display a dropdown menu in your WYSIWYG toolbar to apply a style to selected text.
Examples
In this example, we have enabled a dropdown menu in our WYSIWYG toolbar to apply a style to selected text. The styles are defined in the /css/styles.css file.
_editables:
content:
styles: /css/styles.css
This example file defines the styles that CloudCannon can add to your WYSIWYG toolbar.
/* Can be applied to blocks of content */
p.callout {
margin: 10px;
border: 1px solid #f5f5f5;
background-color: #eee;
}
/* Can be applied to inline content */
span.big-blue-text {
font-size: 2rem;
color: blue;
}
/* Applied to content, excluded from style dropdown */
h2 {
font-family: cursive;
}
/* Applied to content, excluded from style dropdown */
.align-left { text-align: left; }
.align-center { text-align: center; }
.align-right { text-align: right; }
.align-justify { text-align: justify; }
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a table.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a table. Further table options are available from the table context menu in the rich text editor.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to merge a list item with the item above it in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to merge a list item with the item above it.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to merge a list item with the item below it in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to merge a list item with the item below it.
This key defines input options for block Editable Regions.
44 nested properties
This key defines what format an image is converted to prior to upload.
Examples
In this example, we have configured an Image Input to convert images to WebP format prior to upload.
_inputs:
hero_image:
type: image
options:
mime_type: image/webp
This key defines how image files are resized prior to upload, using a bounding box defined by width and height options.
Valid values are cover, contain, crop, or stretch:
coverkeeps aspect ratio and ensures the image covers the bounding boxcontainkeeps aspect ratio and ensures the image fits inside the bounding boxcropprompts the user with and interface to select an aspect-ratio-respecting areastretchignores aspect ratio and resizes the image to the bounding box
This key does not apply to existing images, and does not work if width and height options are not defined.
Examples
In this example, we have configured an Image Input to resize images using the cover style to ensure images cover the bounding box while maintaining aspect ratio.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines the width of the bounding box used in the resizing method defined by resize_style.
This key defines the height of the bounding box used in the resizing method defined by resize_style.
Examples
In this example, we have configured the height of the bounding box for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines whether you can upscale an image to fit the bounding box while resizing an image prior to upload.
Has no effect if files are not resized.
Examples
In this example, we have configured an Image Input to allow upscaling images to fit the bounding box while resizing.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
expandable: true
This key toggles whether CloudCannon will instruct a rich text editor to save width and height attributes on image elements.
Setting this key to true will instruct the rich text editor to save width and height attributes on image elements. This can prevent pop-in as a page loads.
By default, this key is false (i.e., width and height attributes are not saved on image elements). This defaults to true if the Image Size Attributes site flag is enabled (this is enabled for sites created before June 23 2023, in order to keep those sites working).
Examples
In this example, CloudCannon will save width and height attributes on image elements in a Rich Text Input.
_inputs:
content:
type: markdown
options:
image_size_attributes: true
This key defines which sources and DAMs you are allowed to upload to and browse.
The value can be an array of strings. Valid values include site-files and the reference key for any DAM connected to your site.
If site-files is omitted from the array, site files will not be available as an asset source for this input.
Examples
In this example, we have configured allowed sources for an Image Input.
_inputs:
image:
type: image
options:
allowed_sources:
- site-files
- my-cloudinary-dam
This key toggles whether CloudCannon will skip the image resizing process configured for this input when selecting existing images.
Setting this key to true will skip the image resizing process when selecting existing images.
Examples
In this example, CloudCannon will skip the image resizing process when selecting existing images for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
prevent_resize_existing_files: true
This key defines definitions for creating additional images of different sizes when uploading or selecting existing files.
Examples
In this example, we have configured an Image Input to create additional images of different sizes when uploading or selecting files.
_inputs:
hero_image:
type: image
options:
sizes:
- size: 2x
- size: 3x
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to bold selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to bold selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to copy formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to copy formatting from selected text. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not copy other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to italicize selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to italicize selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to redo recent edits undone with undo.
Setting this key to true will enable a tool in your WYSIWYG toolbar to redo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to remove formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to remove formatting. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not remove other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to strike through selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to strike through selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to subscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to subscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to superscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to superscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to underline selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to underline selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to undo recent edits.
Setting this key to true will enable a tool in your WYSIWYG toolbar to undo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will allow you to strip custom markup from content edited in a rich text editor, allowing you to clean files of unnecessary HTML content.
Setting this key to true will enable stripping custom markup from content. The remove_custom_markup key is disabled if allow_custom_markup is enabled.
This key toggles whether CloudCannon will allow you to edit custom markup in rich text editors and explicitly accept the risk of unintentionally deleting elements that cannot be recreated.
Setting this key to true will enable editing of custom markup. When using allow_custom_markup outside of editable regions, content that uses JavaScript will not be editable for security reasons. These inputs will appear as uneditable snippets.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to wrap selected blocks of text in a block quote.
Setting this key to true will enable a tool in your WYSIWYG toolbar to wrap selected blocks of text in a block quote.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an unordered list or convert selected text to an unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an unordered list or convert selected text to an unordered list.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to center align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to center align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a control in your WYSIWYG toolbar to create an inline code element, containing any selected text.
Setting this key to true will enable a control in your WYSIWYG toolbar to create an inline code element.
By default, this key is false (i.e., the inline code control is not displayed).
This key toggles whether CloudCannon will display a control in your WYSIWYG toolbar to insert a code block in editable regions.
Setting this key to true will enable a control in your WYSIWYG toolbar to insert a code block.
By default, this key is false (i.e., the code block control is not displayed).
This key toggles whether CloudCannon will display tools in your WYSIWYG toolbar to turn selected text into inline code and selected text into a code block.
Setting this key to true will enable two tools in your WYSIWYG toolbar to turn selected text into inline code and selected text into a code block.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a region of raw HTML for YouTube, Vimeo, social media posts, or other media.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a region of raw HTML. Embedded content is sanitized to mitigate XSS risks, which includes removing style tags. Embeds containing script tags are not loaded a rich text editor.
This key toggles whether CloudCannon will display a dropdown menu tool in your WYSIWYG toolbar for structured text.
Setting this key to true will enable a dropdown menu tool in your WYSIWYG toolbar for structured text. Valid values include for p, h1, h2, h3, h4, h5, h6, pre, address, and div. Include a space between each values, e.g. format: p h1 h2.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a horizontal line.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a horizontal line.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an image and enter alternative text and title text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an image. Select an existing image, upload an image, or use an external link.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to increase the indentation of a list item in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to increase the indentation of a list item.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to justify selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to justify selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to left align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to left align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an ordered list or convert selected text to an ordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an ordered list or convert selected text to an ordered list.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to decrease the indentation of a list item in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to decrease the indentation of a list item.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to right align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to right align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a Snippet, if any are available.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a Snippet.
This key toggles whether CloudCannon will display a dropdown menu in your WYSIWYG toolbar to apply a style to selected text.
Examples
In this example, we have enabled a dropdown menu in our WYSIWYG toolbar to apply a style to selected text. The styles are defined in the /css/styles.css file.
_editables:
content:
styles: /css/styles.css
This example file defines the styles that CloudCannon can add to your WYSIWYG toolbar.
/* Can be applied to blocks of content */
p.callout {
margin: 10px;
border: 1px solid #f5f5f5;
background-color: #eee;
}
/* Can be applied to inline content */
span.big-blue-text {
font-size: 2rem;
color: blue;
}
/* Applied to content, excluded from style dropdown */
h2 {
font-family: cursive;
}
/* Applied to content, excluded from style dropdown */
.align-left { text-align: left; }
.align-center { text-align: center; }
.align-right { text-align: right; }
.align-justify { text-align: justify; }
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a table.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a table. Further table options are available from the table context menu in the rich text editor.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to merge a list item with the item above it in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to merge a list item with the item above it.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to merge a list item with the item below it in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to merge a list item with the item below it.
This key defines input options for link Editable Regions.
1 nested properties
This key defines input options for image Editable Regions.
10 nested properties
This key defines what format an image is converted to prior to upload.
Examples
In this example, we have configured an Image Input to convert images to WebP format prior to upload.
_inputs:
hero_image:
type: image
options:
mime_type: image/webp
This key defines how image files are resized prior to upload, using a bounding box defined by width and height options.
Valid values are cover, contain, crop, or stretch:
coverkeeps aspect ratio and ensures the image covers the bounding boxcontainkeeps aspect ratio and ensures the image fits inside the bounding boxcropprompts the user with and interface to select an aspect-ratio-respecting areastretchignores aspect ratio and resizes the image to the bounding box
This key does not apply to existing images, and does not work if width and height options are not defined.
Examples
In this example, we have configured an Image Input to resize images using the cover style to ensure images cover the bounding box while maintaining aspect ratio.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines the width of the bounding box used in the resizing method defined by resize_style.
This key defines the height of the bounding box used in the resizing method defined by resize_style.
Examples
In this example, we have configured the height of the bounding box for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines whether you can upscale an image to fit the bounding box while resizing an image prior to upload.
Has no effect if files are not resized.
Examples
In this example, we have configured an Image Input to allow upscaling images to fit the bounding box while resizing.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
expandable: true
This key toggles whether CloudCannon will instruct a rich text editor to save width and height attributes on image elements.
Setting this key to true will instruct the rich text editor to save width and height attributes on image elements. This can prevent pop-in as a page loads.
By default, this key is false (i.e., width and height attributes are not saved on image elements). This defaults to true if the Image Size Attributes site flag is enabled (this is enabled for sites created before June 23 2023, in order to keep those sites working).
Examples
In this example, CloudCannon will save width and height attributes on image elements in a Rich Text Input.
_inputs:
content:
type: markdown
options:
image_size_attributes: true
This key defines which sources and DAMs you are allowed to upload to and browse.
The value can be an array of strings. Valid values include site-files and the reference key for any DAM connected to your site.
If site-files is omitted from the array, site files will not be available as an asset source for this input.
Examples
In this example, we have configured allowed sources for an Image Input.
_inputs:
image:
type: image
options:
allowed_sources:
- site-files
- my-cloudinary-dam
This key toggles whether CloudCannon will skip the image resizing process configured for this input when selecting existing images.
Setting this key to true will skip the image resizing process when selecting existing images.
Examples
In this example, CloudCannon will skip the image resizing process when selecting existing images for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
prevent_resize_existing_files: true
This key defines definitions for creating additional images of different sizes when uploading or selecting existing files.
Examples
In this example, we have configured an Image Input to create additional images of different sizes when uploading or selecting files.
_inputs:
hero_image:
type: image
options:
sizes:
- size: 2x
- size: 3x
This key defines input options for text Editable Regions.
14 nested properties
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to bold selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to bold selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to copy formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to copy formatting from selected text. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not copy other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to italicize selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to italicize selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to redo recent edits undone with undo.
Setting this key to true will enable a tool in your WYSIWYG toolbar to redo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to remove formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to remove formatting. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not remove other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to strike through selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to strike through selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to subscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to subscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to superscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to superscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to underline selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to underline selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to undo recent edits.
Setting this key to true will enable a tool in your WYSIWYG toolbar to undo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will allow you to strip custom markup from content edited in a rich text editor, allowing you to clean files of unnecessary HTML content.
Setting this key to true will enable stripping custom markup from content. The remove_custom_markup key is disabled if allow_custom_markup is enabled.
This key toggles whether CloudCannon will allow you to edit custom markup in rich text editors and explicitly accept the risk of unintentionally deleting elements that cannot be recreated.
Setting this key to true will enable editing of custom markup. When using allow_custom_markup outside of editable regions, content that uses JavaScript will not be editable for security reasons. These inputs will appear as uneditable snippets.
This key defines custom snippets for your Site.
This key has no default.
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.
Examples
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'
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.
Examples
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'
mdx: true
docusaurus_mdx:
exclude:
- docusaurus_mdx_truncate
This key defines extended options used when creating more complex custom snippets.
A record of reusable values that can be referenced in snippet templates. Values are substituted using { ref: "key" } for direct replacement or { spread_ref: "key" } for spreading arrays/objects. Common definition types include parser formats, argument models, select option lists, and simple string values like shortcode names.
Examples
Define reusable values like shortcode names, argument models, and parser formats that can be referenced in snippet templates.
_snippets_definitions:
# Simple string value for the shortcode name
shortcode_name: "highlight"
content_key: "content"
# Array of argument models for positional arguments
positional_args:
- editor_key: "language"
type: "string"
- editor_key: "linenos"
type: "boolean"
optional: true
default: false
# Parser format configuration
custom_format:
root_pair_delimiter:
- " "
root_value_delimiter: "="
string_boundary:
- '"'
- "'"
- ""
allow_booleans: true
allow_numbers: true
Reference definitions in snippet templates using { ref: "key" } syntax. This allows you to reuse common configurations across multiple snippets.
_snippets_definitions:
shortcode_name: "figure"
named_args:
- editor_key: "src"
type: "string"
- editor_key: "alt"
type: "string"
optional: true
_snippets_templates:
my_shortcode_template:
snippet: "{{< [[name]] [[args]] >}}"
params:
name:
parser: "literal"
options:
literal:
ref: "shortcode_name"
args:
parser: "key_values"
options:
models:
ref: "named_args"
_snippets:
figure:
template: "my_shortcode_template"
definitions:
shortcode_name: "figure"
named_args:
- editor_key: "src"
type: "string"
- editor_key: "alt"
type: "string"
Define a list of select options for use in snippet inputs, such as a list of programming languages for a code highlighting snippet.
_snippets_definitions:
languages:
- name: "JavaScript"
value: "js"
- name: "Python"
value: "python"
- name: "Ruby"
value: "ruby"
- name: "HTML"
value: "html"
- name: "CSS"
value: "css"
Definitions
This key defines paths for your Rich Text editors or File inputs.
If undefined at higher levels of the configuration cascade, paths will default to any
values configured in the CloudCannon configuration file.
Examples
In this example, we have configured paths for the blog Collection to set custom upload and static paths.
collections_config:
blog:
paths:
uploads: /uploads/blog/
static: /assets/
This key defines the path for the location of statically copied assets.
Examples
In this example, we have configured the static path for the blog Collection.
collections_config:
blog:
paths:
static: /assets/
This key defines the paths for the default location of newly uploaded site files.
You can use dynamic placeholders for uploads and dam_uploads.
Examples
In this example, we have configured the uploads path for the blog Collection.
collections_config:
blog:
paths:
uploads: /uploads/blog/
This key defines the path for the name of the uploaded file.
Examples
In this example, we have configured the uploads filename path for the blog Collection.
collections_config:
blog:
paths:
uploads_filename: '{filename|slugify}'
This key defines the path for the default location of newly uploaded DAM files.
You can use dynamic placeholders for uploads and dam_uploads.
Examples
In this example, we have configured the DAM uploads path for the blog Collection.
collections_config:
blog:
paths:
dam_uploads: /dam/uploads/blog/
This key defines the path for the name of the uploaded file, when uploading DAM files.
Examples
In this example, we have configured the DAM uploads filename path for the blog Collection.
collections_config:
blog:
paths:
dam_uploads_filename: '{filename|slugify}'
This key defines the path for the location of statically copied assets for DAM files.
Examples
In this example, we have configured the DAM static path for the blog Collection.
collections_config:
blog:
paths:
dam_static: /assets/dam/
This key toggles whether CloudCannon will use relative paths instead of absolute paths for uploaded files.
Setting this key to true will make CloudCannon use relative paths for uploaded files, which are relative to the file being edited rather than the repository root.
Examples
In this example, we have configured uploads to use relative paths for files uploaded in the Content Editor.
_editables:
content:
paths:
uploads_use_relative_path: true
This key defines the path for the location of statically copied assets.
Examples
In this example, we have configured the static path for the blog Collection.
collections_config:
blog:
paths:
static: /assets/
This key defines the paths for the default location of newly uploaded site files.
You can use dynamic placeholders for uploads and dam_uploads.
Examples
In this example, we have configured the uploads path for the blog Collection.
collections_config:
blog:
paths:
uploads: /uploads/blog/
This key defines the path for the name of the uploaded file.
Examples
In this example, we have configured the uploads filename path for the blog Collection.
collections_config:
blog:
paths:
uploads_filename: '{filename|slugify}'
This key defines the path for the default location of newly uploaded DAM files.
You can use dynamic placeholders for uploads and dam_uploads.
Examples
In this example, we have configured the DAM uploads path for the blog Collection.
collections_config:
blog:
paths:
dam_uploads: /dam/uploads/blog/
This key defines the path for the name of the uploaded file, when uploading DAM files.
Examples
In this example, we have configured the DAM uploads filename path for the blog Collection.
collections_config:
blog:
paths:
dam_uploads_filename: '{filename|slugify}'
This key defines the path for the location of statically copied assets for DAM files.
Examples
In this example, we have configured the DAM static path for the blog Collection.
collections_config:
blog:
paths:
dam_static: /assets/dam/
This key toggles whether CloudCannon will use relative paths instead of absolute paths for uploaded files.
Setting this key to true will make CloudCannon use relative paths for uploaded files, which are relative to the file being edited rather than the repository root.
Examples
In this example, we have configured uploads to use relative paths for files uploaded in the Content Editor.
_editables:
content:
paths:
uploads_use_relative_path: true
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 /.
For more information, please read our documentation on the Site source folder in your configuration file.
Examples
In this example, we have configured the source path to src so CloudCannon will look for source files in the src folder.
source: src
This key defines your Collections.
Examples
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.
collections_config:
blog:
path: content/blog
glob:
- '!_index.md'
name: Blog
icon: post_add
url: /blog/[full_slug]/
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
In this example, we have configured a team Collection. Key settings include custom sorting options, add options, and Card previews.
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
This key defines your Collections, which are the sets of content files for your site grouped by folder.
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.
Examples
In this example, the files for the blog Collection are located in the content/blog folder.
collections_config:
blog:
path: content/blog
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.
Examples
In this example, the Collection browser will show all files in the data folder except for the secret.yml file.
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.
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.
collections_config:
data:
path: data
glob:
- '**/*.yml'
- '!secret.yml'
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.
Examples
In this example, the output URL for files in this Collection will be /travel/ rather than the default /blog/.
collections_config:
blog:
url: /travel/[slug]/
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.
Examples
In this example, data is an non-output Collection and we don't want output URLs generated.
collections_config:
data:
disable_url: true
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.
Examples
In this example, we want to see developer files in the Collection browser for the data Collection.
collections_config:
data:
include_developer_files: true
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").
Examples
In this example, CloudCannon will call the blog Collection "Travel Blog" in the Site Navigation and the Collection browser.
collections_config:
blog:
name: Travel Blog
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.
Examples
In this example, we have configured a description for the blog Collection with markdown formatting.
collections_config:
blog:
description:|-
This Collection is for *Travel blogs* and *Customer stories*.
If your have any questions, please contact Heather.
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.
Examples
In this example, we have configured the post_add icon for the blog Collection.
collections_config:
blog:
icon: post_add
This key defines the documentation link at the top of a Collection browser. Collection documentation is useful for assisting your team members.
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.
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.
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)
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.
Examples
In this example, we have configured three view options for the developer_articles Collection, with card as the default view.
collections_config:
developer_articles:
path: developer/articles
icon: article
view_options:
- card
- list
- gallery
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").
Examples
In this example, the + Add button option to add a Collection file will read "Add Team Member" rather that "Add Team".
collections_config:
team:
singular_name: Team Member
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.
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.
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.
collections_config:
team:
add_options:
- name: Office Locations
icon: map
href: /our-offices
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.
Examples
In this example, we want to prevent team members from adding new files to the data Collection through the Collection browser.
collections_config:
data:
disable_add: true
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.
Examples
In this example, we want to prevent team members from adding new subfolders to the data Collection through the Collection browser.
collections_config:
data:
disable_add_folder: true
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.
Examples
In this example, we want to prevent team members from using file actions in the data Collection through the Collection browser.
collections_config:
data:
disable_file_actions: true
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.
Examples
In this example, the Visual Editor will open the /about/ page when you open an unbuilt page from the blog Collection.
collections_config:
blog:
new_preview_url: /about/
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.
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.
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.
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
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.
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.
posts:
path: content/posts
icon: event
schemas_from_glob:
- '/.cloudcannon/schemas/*.cloudcannon.schemas.yml'
- '!/.cloudcannon/schemas/pages.cloudcannon.schemas.yml'
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.
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.
collections_config:
blog:
schema_key: _blog_template
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.
Examples
In this example, we have enabled only the Content Editor in the blog Collection.
collections_config:
blog:
_enabled_editors:
- content
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.
Examples
In this example, we have configured the Snippet tool for WYSIWYG toolbars in the blog Collection.
collections_config:
blog:
_editables:
content:
snippet: true
5 nested properties
This key defines input options for the Content Editor.
44 nested properties
This key defines what format an image is converted to prior to upload.
Examples
In this example, we have configured an Image Input to convert images to WebP format prior to upload.
_inputs:
hero_image:
type: image
options:
mime_type: image/webp
This key defines how image files are resized prior to upload, using a bounding box defined by width and height options.
Valid values are cover, contain, crop, or stretch:
coverkeeps aspect ratio and ensures the image covers the bounding boxcontainkeeps aspect ratio and ensures the image fits inside the bounding boxcropprompts the user with and interface to select an aspect-ratio-respecting areastretchignores aspect ratio and resizes the image to the bounding box
This key does not apply to existing images, and does not work if width and height options are not defined.
Examples
In this example, we have configured an Image Input to resize images using the cover style to ensure images cover the bounding box while maintaining aspect ratio.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines the width of the bounding box used in the resizing method defined by resize_style.
This key defines the height of the bounding box used in the resizing method defined by resize_style.
Examples
In this example, we have configured the height of the bounding box for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines whether you can upscale an image to fit the bounding box while resizing an image prior to upload.
Has no effect if files are not resized.
Examples
In this example, we have configured an Image Input to allow upscaling images to fit the bounding box while resizing.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
expandable: true
This key toggles whether CloudCannon will instruct a rich text editor to save width and height attributes on image elements.
Setting this key to true will instruct the rich text editor to save width and height attributes on image elements. This can prevent pop-in as a page loads.
By default, this key is false (i.e., width and height attributes are not saved on image elements). This defaults to true if the Image Size Attributes site flag is enabled (this is enabled for sites created before June 23 2023, in order to keep those sites working).
Examples
In this example, CloudCannon will save width and height attributes on image elements in a Rich Text Input.
_inputs:
content:
type: markdown
options:
image_size_attributes: true
This key defines which sources and DAMs you are allowed to upload to and browse.
The value can be an array of strings. Valid values include site-files and the reference key for any DAM connected to your site.
If site-files is omitted from the array, site files will not be available as an asset source for this input.
Examples
In this example, we have configured allowed sources for an Image Input.
_inputs:
image:
type: image
options:
allowed_sources:
- site-files
- my-cloudinary-dam
This key toggles whether CloudCannon will skip the image resizing process configured for this input when selecting existing images.
Setting this key to true will skip the image resizing process when selecting existing images.
Examples
In this example, CloudCannon will skip the image resizing process when selecting existing images for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
prevent_resize_existing_files: true
This key defines definitions for creating additional images of different sizes when uploading or selecting existing files.
Examples
In this example, we have configured an Image Input to create additional images of different sizes when uploading or selecting files.
_inputs:
hero_image:
type: image
options:
sizes:
- size: 2x
- size: 3x
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to bold selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to bold selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to copy formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to copy formatting from selected text. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not copy other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to italicize selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to italicize selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to redo recent edits undone with undo.
Setting this key to true will enable a tool in your WYSIWYG toolbar to redo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to remove formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to remove formatting. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not remove other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to strike through selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to strike through selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to subscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to subscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to superscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to superscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to underline selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to underline selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to undo recent edits.
Setting this key to true will enable a tool in your WYSIWYG toolbar to undo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will allow you to strip custom markup from content edited in a rich text editor, allowing you to clean files of unnecessary HTML content.
Setting this key to true will enable stripping custom markup from content. The remove_custom_markup key is disabled if allow_custom_markup is enabled.
This key toggles whether CloudCannon will allow you to edit custom markup in rich text editors and explicitly accept the risk of unintentionally deleting elements that cannot be recreated.
Setting this key to true will enable editing of custom markup. When using allow_custom_markup outside of editable regions, content that uses JavaScript will not be editable for security reasons. These inputs will appear as uneditable snippets.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to wrap selected blocks of text in a block quote.
Setting this key to true will enable a tool in your WYSIWYG toolbar to wrap selected blocks of text in a block quote.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an unordered list or convert selected text to an unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an unordered list or convert selected text to an unordered list.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to center align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to center align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a control in your WYSIWYG toolbar to create an inline code element, containing any selected text.
Setting this key to true will enable a control in your WYSIWYG toolbar to create an inline code element.
By default, this key is false (i.e., the inline code control is not displayed).
This key toggles whether CloudCannon will display a control in your WYSIWYG toolbar to insert a code block in editable regions.
Setting this key to true will enable a control in your WYSIWYG toolbar to insert a code block.
By default, this key is false (i.e., the code block control is not displayed).
This key toggles whether CloudCannon will display tools in your WYSIWYG toolbar to turn selected text into inline code and selected text into a code block.
Setting this key to true will enable two tools in your WYSIWYG toolbar to turn selected text into inline code and selected text into a code block.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a region of raw HTML for YouTube, Vimeo, social media posts, or other media.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a region of raw HTML. Embedded content is sanitized to mitigate XSS risks, which includes removing style tags. Embeds containing script tags are not loaded a rich text editor.
This key toggles whether CloudCannon will display a dropdown menu tool in your WYSIWYG toolbar for structured text.
Setting this key to true will enable a dropdown menu tool in your WYSIWYG toolbar for structured text. Valid values include for p, h1, h2, h3, h4, h5, h6, pre, address, and div. Include a space between each values, e.g. format: p h1 h2.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a horizontal line.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a horizontal line.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an image and enter alternative text and title text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an image. Select an existing image, upload an image, or use an external link.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to increase the indentation of a list item in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to increase the indentation of a list item.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to justify selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to justify selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to left align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to left align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an ordered list or convert selected text to an ordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an ordered list or convert selected text to an ordered list.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to decrease the indentation of a list item in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to decrease the indentation of a list item.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to right align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to right align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a Snippet, if any are available.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a Snippet.
This key toggles whether CloudCannon will display a dropdown menu in your WYSIWYG toolbar to apply a style to selected text.
Examples
In this example, we have enabled a dropdown menu in our WYSIWYG toolbar to apply a style to selected text. The styles are defined in the /css/styles.css file.
_editables:
content:
styles: /css/styles.css
This example file defines the styles that CloudCannon can add to your WYSIWYG toolbar.
/* Can be applied to blocks of content */
p.callout {
margin: 10px;
border: 1px solid #f5f5f5;
background-color: #eee;
}
/* Can be applied to inline content */
span.big-blue-text {
font-size: 2rem;
color: blue;
}
/* Applied to content, excluded from style dropdown */
h2 {
font-family: cursive;
}
/* Applied to content, excluded from style dropdown */
.align-left { text-align: left; }
.align-center { text-align: center; }
.align-right { text-align: right; }
.align-justify { text-align: justify; }
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a table.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a table. Further table options are available from the table context menu in the rich text editor.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to merge a list item with the item above it in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to merge a list item with the item above it.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to merge a list item with the item below it in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to merge a list item with the item below it.
This key defines input options for block Editable Regions.
44 nested properties
This key defines what format an image is converted to prior to upload.
Examples
In this example, we have configured an Image Input to convert images to WebP format prior to upload.
_inputs:
hero_image:
type: image
options:
mime_type: image/webp
This key defines how image files are resized prior to upload, using a bounding box defined by width and height options.
Valid values are cover, contain, crop, or stretch:
coverkeeps aspect ratio and ensures the image covers the bounding boxcontainkeeps aspect ratio and ensures the image fits inside the bounding boxcropprompts the user with and interface to select an aspect-ratio-respecting areastretchignores aspect ratio and resizes the image to the bounding box
This key does not apply to existing images, and does not work if width and height options are not defined.
Examples
In this example, we have configured an Image Input to resize images using the cover style to ensure images cover the bounding box while maintaining aspect ratio.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines the width of the bounding box used in the resizing method defined by resize_style.
This key defines the height of the bounding box used in the resizing method defined by resize_style.
Examples
In this example, we have configured the height of the bounding box for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines whether you can upscale an image to fit the bounding box while resizing an image prior to upload.
Has no effect if files are not resized.
Examples
In this example, we have configured an Image Input to allow upscaling images to fit the bounding box while resizing.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
expandable: true
This key toggles whether CloudCannon will instruct a rich text editor to save width and height attributes on image elements.
Setting this key to true will instruct the rich text editor to save width and height attributes on image elements. This can prevent pop-in as a page loads.
By default, this key is false (i.e., width and height attributes are not saved on image elements). This defaults to true if the Image Size Attributes site flag is enabled (this is enabled for sites created before June 23 2023, in order to keep those sites working).
Examples
In this example, CloudCannon will save width and height attributes on image elements in a Rich Text Input.
_inputs:
content:
type: markdown
options:
image_size_attributes: true
This key defines which sources and DAMs you are allowed to upload to and browse.
The value can be an array of strings. Valid values include site-files and the reference key for any DAM connected to your site.
If site-files is omitted from the array, site files will not be available as an asset source for this input.
Examples
In this example, we have configured allowed sources for an Image Input.
_inputs:
image:
type: image
options:
allowed_sources:
- site-files
- my-cloudinary-dam
This key toggles whether CloudCannon will skip the image resizing process configured for this input when selecting existing images.
Setting this key to true will skip the image resizing process when selecting existing images.
Examples
In this example, CloudCannon will skip the image resizing process when selecting existing images for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
prevent_resize_existing_files: true
This key defines definitions for creating additional images of different sizes when uploading or selecting existing files.
Examples
In this example, we have configured an Image Input to create additional images of different sizes when uploading or selecting files.
_inputs:
hero_image:
type: image
options:
sizes:
- size: 2x
- size: 3x
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to bold selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to bold selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to copy formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to copy formatting from selected text. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not copy other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to italicize selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to italicize selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to redo recent edits undone with undo.
Setting this key to true will enable a tool in your WYSIWYG toolbar to redo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to remove formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to remove formatting. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not remove other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to strike through selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to strike through selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to subscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to subscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to superscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to superscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to underline selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to underline selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to undo recent edits.
Setting this key to true will enable a tool in your WYSIWYG toolbar to undo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will allow you to strip custom markup from content edited in a rich text editor, allowing you to clean files of unnecessary HTML content.
Setting this key to true will enable stripping custom markup from content. The remove_custom_markup key is disabled if allow_custom_markup is enabled.
This key toggles whether CloudCannon will allow you to edit custom markup in rich text editors and explicitly accept the risk of unintentionally deleting elements that cannot be recreated.
Setting this key to true will enable editing of custom markup. When using allow_custom_markup outside of editable regions, content that uses JavaScript will not be editable for security reasons. These inputs will appear as uneditable snippets.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to wrap selected blocks of text in a block quote.
Setting this key to true will enable a tool in your WYSIWYG toolbar to wrap selected blocks of text in a block quote.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an unordered list or convert selected text to an unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an unordered list or convert selected text to an unordered list.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to center align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to center align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a control in your WYSIWYG toolbar to create an inline code element, containing any selected text.
Setting this key to true will enable a control in your WYSIWYG toolbar to create an inline code element.
By default, this key is false (i.e., the inline code control is not displayed).
This key toggles whether CloudCannon will display a control in your WYSIWYG toolbar to insert a code block in editable regions.
Setting this key to true will enable a control in your WYSIWYG toolbar to insert a code block.
By default, this key is false (i.e., the code block control is not displayed).
This key toggles whether CloudCannon will display tools in your WYSIWYG toolbar to turn selected text into inline code and selected text into a code block.
Setting this key to true will enable two tools in your WYSIWYG toolbar to turn selected text into inline code and selected text into a code block.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a region of raw HTML for YouTube, Vimeo, social media posts, or other media.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a region of raw HTML. Embedded content is sanitized to mitigate XSS risks, which includes removing style tags. Embeds containing script tags are not loaded a rich text editor.
This key toggles whether CloudCannon will display a dropdown menu tool in your WYSIWYG toolbar for structured text.
Setting this key to true will enable a dropdown menu tool in your WYSIWYG toolbar for structured text. Valid values include for p, h1, h2, h3, h4, h5, h6, pre, address, and div. Include a space between each values, e.g. format: p h1 h2.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a horizontal line.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a horizontal line.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an image and enter alternative text and title text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an image. Select an existing image, upload an image, or use an external link.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to increase the indentation of a list item in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to increase the indentation of a list item.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to justify selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to justify selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to left align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to left align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an ordered list or convert selected text to an ordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an ordered list or convert selected text to an ordered list.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to decrease the indentation of a list item in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to decrease the indentation of a list item.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to right align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to right align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a Snippet, if any are available.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a Snippet.
This key toggles whether CloudCannon will display a dropdown menu in your WYSIWYG toolbar to apply a style to selected text.
Examples
In this example, we have enabled a dropdown menu in our WYSIWYG toolbar to apply a style to selected text. The styles are defined in the /css/styles.css file.
_editables:
content:
styles: /css/styles.css
This example file defines the styles that CloudCannon can add to your WYSIWYG toolbar.
/* Can be applied to blocks of content */
p.callout {
margin: 10px;
border: 1px solid #f5f5f5;
background-color: #eee;
}
/* Can be applied to inline content */
span.big-blue-text {
font-size: 2rem;
color: blue;
}
/* Applied to content, excluded from style dropdown */
h2 {
font-family: cursive;
}
/* Applied to content, excluded from style dropdown */
.align-left { text-align: left; }
.align-center { text-align: center; }
.align-right { text-align: right; }
.align-justify { text-align: justify; }
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a table.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a table. Further table options are available from the table context menu in the rich text editor.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to merge a list item with the item above it in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to merge a list item with the item above it.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to merge a list item with the item below it in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to merge a list item with the item below it.
This key defines input options for link Editable Regions.
1 nested properties
This key defines input options for image Editable Regions.
10 nested properties
This key defines what format an image is converted to prior to upload.
Examples
In this example, we have configured an Image Input to convert images to WebP format prior to upload.
_inputs:
hero_image:
type: image
options:
mime_type: image/webp
This key defines how image files are resized prior to upload, using a bounding box defined by width and height options.
Valid values are cover, contain, crop, or stretch:
coverkeeps aspect ratio and ensures the image covers the bounding boxcontainkeeps aspect ratio and ensures the image fits inside the bounding boxcropprompts the user with and interface to select an aspect-ratio-respecting areastretchignores aspect ratio and resizes the image to the bounding box
This key does not apply to existing images, and does not work if width and height options are not defined.
Examples
In this example, we have configured an Image Input to resize images using the cover style to ensure images cover the bounding box while maintaining aspect ratio.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines the width of the bounding box used in the resizing method defined by resize_style.
This key defines the height of the bounding box used in the resizing method defined by resize_style.
Examples
In this example, we have configured the height of the bounding box for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines whether you can upscale an image to fit the bounding box while resizing an image prior to upload.
Has no effect if files are not resized.
Examples
In this example, we have configured an Image Input to allow upscaling images to fit the bounding box while resizing.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
expandable: true
This key toggles whether CloudCannon will instruct a rich text editor to save width and height attributes on image elements.
Setting this key to true will instruct the rich text editor to save width and height attributes on image elements. This can prevent pop-in as a page loads.
By default, this key is false (i.e., width and height attributes are not saved on image elements). This defaults to true if the Image Size Attributes site flag is enabled (this is enabled for sites created before June 23 2023, in order to keep those sites working).
Examples
In this example, CloudCannon will save width and height attributes on image elements in a Rich Text Input.
_inputs:
content:
type: markdown
options:
image_size_attributes: true
This key defines which sources and DAMs you are allowed to upload to and browse.
The value can be an array of strings. Valid values include site-files and the reference key for any DAM connected to your site.
If site-files is omitted from the array, site files will not be available as an asset source for this input.
Examples
In this example, we have configured allowed sources for an Image Input.
_inputs:
image:
type: image
options:
allowed_sources:
- site-files
- my-cloudinary-dam
This key toggles whether CloudCannon will skip the image resizing process configured for this input when selecting existing images.
Setting this key to true will skip the image resizing process when selecting existing images.
Examples
In this example, CloudCannon will skip the image resizing process when selecting existing images for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
prevent_resize_existing_files: true
This key defines definitions for creating additional images of different sizes when uploading or selecting existing files.
Examples
In this example, we have configured an Image Input to create additional images of different sizes when uploading or selecting files.
_inputs:
hero_image:
type: image
options:
sizes:
- size: 2x
- size: 3x
This key defines input options for text Editable Regions.
14 nested properties
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to bold selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to bold selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to copy formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to copy formatting from selected text. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not copy other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to italicize selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to italicize selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to redo recent edits undone with undo.
Setting this key to true will enable a tool in your WYSIWYG toolbar to redo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to remove formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to remove formatting. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not remove other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to strike through selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to strike through selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to subscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to subscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to superscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to superscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to underline selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to underline selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to undo recent edits.
Setting this key to true will enable a tool in your WYSIWYG toolbar to undo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will allow you to strip custom markup from content edited in a rich text editor, allowing you to clean files of unnecessary HTML content.
Setting this key to true will enable stripping custom markup from content. The remove_custom_markup key is disabled if allow_custom_markup is enabled.
This key toggles whether CloudCannon will allow you to edit custom markup in rich text editors and explicitly accept the risk of unintentionally deleting elements that cannot be recreated.
Setting this key to true will enable editing of custom markup. When using allow_custom_markup outside of editable regions, content that uses JavaScript will not be editable for security reasons. These inputs will appear as uneditable snippets.
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.
Examples
In this example, the files for the blog Collection are located in the content/blog folder.
collections_config:
blog:
path: content/blog
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.
Examples
In this example, the Collection browser will show all files in the data folder except for the secret.yml file.
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.
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.
collections_config:
data:
path: data
glob:
- '**/*.yml'
- '!secret.yml'
Material Symbol icon names available in CloudCannon for UI elements and content previews.
This key defines the documentation link at the top of a Collection browser.
Collection documentation is useful for assisting your team members.
Examples
In this example, the documentation link for the data Collection goes to CloudCannon Documentation.
collections_config:
data:
documentation:
url: https://cloudcannon.com/documentation/
text: CloudCannon Documentation
icon: star
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.
Examples
In this example, we have configured the blog Collection documentation link to go to example.com.
collections_config:
blog:
documentation:
url: https://example.com
This key defines the link text for the documentation link at the top of a Collection browser.
Examples
In this example, the text for the documentation link is CloudCannon Documentation.
collections_config:
data:
documentation:
url: https://cloudcannon.com/documentation/
text: CloudCannon Documentation
This key defines the icon for the documentation link at the top of a Collection browser.
Values can be from Google's Material Symbols library.
Examples
In this example, we have configured the star icon for the blog Collection documentation link.
collections_config:
blog:
documentation:
url: https://www.cloudcannon.com/documentation/
icon: star
The available editors in CloudCannon: visual, content, and data editors.
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.
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".
collections_config:
blog:
create:
extra_data:
filename: '{date|year}-{date|month}-{date|day}-{title}'
path: '[relative_base_path]/{filename|slugify}.[ext]'
This key defines the raw template to be processed when creating files. Relative to the containing collection's path.
Examples
In this example, we have configured a create path template for the blog Collection using the date and title fields.
collections_config:
blog:
create:
path: '[relative_base_path]/{date|year}-{date|month}-{date|day}-{title|slugify}.[ext]'
This key defines additional data placeholders for use in create path templates.
The value is an object where each property is a string that specifies a data placeholder. Entry values follow the same format as path, and are processed sequentially before path. These values are not saved back to your file.
For more information, please read our documentation on Create Paths.
Examples
In this example, we have configured extra data placeholders to generate a filename from date and title fields for use in the create path.
collections_config:
blog:
create:
extra_data:
filename: '{date|year}-{date|month}-{date|day}-{title}'
path: '[relative_base_path]/{filename|slugify}.[ext]'
This key defines a target collection when publishing.
When a file is published, the target collection's create definition is used instead.
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.
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
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
This key defines an input configuration at a given level of the configuration cascade.
The value is an object that can contain type, label, options, disabled, hidden, and other input-specific properties. Each input configuration defines how team members interact with data in the Data Editor.
For more information, please read our documentation on inputs.
Examples
In this example, we have configured the title key as a Text Input in the blog Collection.
collections_config:
blog:
_inputs:
title:
type: text
label: Title
This key defines a simple editing interface for plain text.
Examples
In this example, we have configured the title key as a Text Input.
_inputs:
title:
type: text
label: Blog Title
This key defines the input type, which controls how this input appears and behaves.
Examples
In this example, we have configured the title key as a Text Input type.
_inputs:
title:
type: text
This key defines the subtitle text above an Input.
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.
Examples
In this example, we want to add helpful guidance for our page_description Input.
_inputs:
page_description:
type: text
label: Page Description
comment: Enter a brief description of this page for search engines
Provides a custom link for documentation for editors shown above input.
This key defines the bold title text above an Input.
Examples
In this example, we want to customize the label for our page_title Input to be more descriptive.
_inputs:
page_title:
type: text
label: Article Title
comment: Enter the main title for this article
This key defines the visibility of an input in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Hidden inputs are useful when you want an input to exist, but not be visible or editable outside of the Source Editor.
Value can be a boolean or a string. A boolean value of true will hide the input.
A string value can hide an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key follows the input naming convention where key names beginning with an underscore are hidden true.
This key defines whether the value of an input is editable in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Disabled inputs are useful if you want CloudCannon to display the input value, but prevent team members from editing the value outside of the Source Editor.
The value of this key can be a boolean or a string. A boolean value of true will prevent team members from editing the value.
A string value can prevent team members from editing an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key is false (i.e., team members can edit input values).
Examples
In this example, we have configured the date_created Date 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
disabled: true
instance_value: NOW
options:
timezone: Etc/UTC
This key defines whether an input is automatically populated with a value when the input is created.
This occurs when creating a new file, or adding array items containing this input.
Valid values are UUID or NOW.
UUIDgenerates a uuidv4 key (extremely unlikely to generate duplicates), useful for identifying unique items (e.g.6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b)NOWgenerates the current datetime in the Site's configured timezone
Examples
In this example, we have configured an input to automatically populate with a UUID when created.
_inputs:
id:
type: text
instance_value: UUID
This key toggles whether CloudCannon will rehydrate inputs configured with an instance_value with a new value when duplicated.
Setting this key to true will prevent rehydration of instance values when inputs are duplicated.
Examples
In this example, CloudCannon will prevent rehydration of instance values when inputs are duplicated.
_inputs:
id:
type: text
instance_value: UUID
disable_instance_value_rehydration: true
This key defines whether CloudCannon should merge this input configuration with any matching, less specific configurations elsewhere in the configuration cascade.
The configuration cascade works by finding the most specific _inputs entry.
Usually, once an option is found in the cascade, there's no reason to keep looking.
When this key is true, the cascade continues looking and each entry found is merged.
This key allows you to define some options globally while using specific options for other keys at different levels of the cascade.
For example, define a comment globally, but use collection-specific label for inputs in different collections.
You can stop the cascade at any point in the configuration cascade by setting cascade to false.
Examples
In this example, we have configured cascade to merge input configurations across the configuration cascade.
_inputs:
title:
type: text
cascade: true
comment: Global comment for all title inputs
This key defines options that are specific to Text Inputs.
Examples
In this example, we have configured Text Input options including comment and icon.
_inputs:
title:
type: text
options:
comment: Enter a title
icon: title
23 nested properties
This key defines the maximum string length, in characters, that CloudCannon will allow in an Input.
When configured, CloudCannon will warn you when an Input value is too long.
If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
Value can be any non-negative integer.
If this key is set to 0, CloudCannon requires the Input to be empty.
If options.min_length is also configured, this key cannot be a smaller number.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to enter a blog description using the Rich Text seo_description Input. This Input limits you to a maximum of 125 characters.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
min_length: 25
This key defines a custom error message that explains why a value has failed the validation criteria from options.max_length.
This key requires you to define options.max_length.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to enter a valid number of characters using a custom message.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
max_length_message: You are only allowed 125 characters.
min_length: 25
min_length_message: Please write more than 25 characters.
This key defines the minimum string length, in characters, that CloudCannon will allow in an Input.
When configured, CloudCannon will warn you when an Input value is too short.
If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
Value can be any positive integer.
If options.max_length is also configured, this key cannot be a greater number.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to enter a blog description using the Rich Text seo_description Input. This Input requires a minimum of 25 characters.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
min_length: 25
This key defines a custom error message that explains why a value has failed the validation criteria from options.min_length.
This key requires you to define options.min_length.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to enter a valid number of characters using a custom message.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
max_length_message: You are only allowed 125 characters.
min_length: 25
min_length_message: Please write more than 25 characters.
This key defines the maximum string length, in words, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which maximum string length an Input will accept. This key requires you to define `options.max_words.
This key defines the minimum string length, in words, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which minimum string length an Input will accept. This key requires you to define options.min_words.
This key defines the maximum string length, in graphemes, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which maximum string length an Input will accept. This key requires you to define `options.max_graphemes.
This key defines the minimum string length, in graphemes, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which minimum string length an Input will accept. This key requires you to define options.min_graphemes.
This key defines the locale that CloudCannon uses to determine the number of words or graphemes in this Input, if you have max_words, min_words, max_graphemes, or min_graphemes configured.
This key defines a regular expression that the Input value must match.
When configured, CloudCannon will require you to enter a value that matches the REGEX pattern.
If the Input already contains an invalid value, CloudCannon will require you to enter a valid string to save your changes, or discard your unsaved changes.
Value must be a valid REGEX string.
If your REGEX string includes a \ character and CloudCannon Configuration File is a .yml file, use single quotes ' around the string to avoid a
build error.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to add an email address to the contact_email Input using the correct email format.
_inputs:
contact_email:
type: email
options:
pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
pattern_message: 'Please use the format ___@___.__'
This key defines a custom error message that explains why a value has failed the validation criteria from options.pattern.
This key requires you to define options.pattern.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to use the correct email format in the contact_email Input using a pattern message.
_inputs:
contact_email:
type: email
options:
pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
pattern_message: 'Please use the format ___@___.__'
This key defines the flags (e.g. case-insensitive searching) for the regular expression set in options.pattern.
Examples
In this example, we have configured pattern flags for a text input to enable case-insensitive searching.
_inputs:
search_term:
type: text
options:
pattern: "^[a-z]+$"
pattern_flags:
ignore_case: true
6 nested properties
This key defines the g flag - Search globally.
This key defines the i flag - Case-insensitive.
This key defines the m flag - ^ and $ match the start and end of each line rather than the entire string.
This key defines the s flag - . matches newline characters.
This key defines the u flag - Pattern is treated as a sequence of Unicode code points.
This key defines the v flag for extended unicode mode.
This key toggles whether CloudCannon requires this Input to have a value.
Setting this key to true will require you to enter a value to save your changes, or discard your unsaved changes.
By default, this key is false (i.e., CloudCannon does not require this Input to have a value).
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we want to require our team to enter an author value for markup files with this Input.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
This key defines a custom error message that explains why a value has failed the validation criteria from options.required.
This key requires you to define options.required.
This key has no default.
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to use enter an Input value using a required message.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
required_message: You are not allowed to leave this blank.
This key defines the text shown when this input has no value.
Examples
In this example, we have configured a placeholder for a Text Input.
_inputs:
title:
type: text
options:
placeholder: Enter a title
This key defines the icon shown beside the input.
Examples
In this example, we have configured an icon for the Text Input title.
_inputs:
title:
type: text
options:
icon: title
This key defines the color of the icon displayed beside a Text Input.
The value can be an array or a single value, and reference a key, template, or text string. When multiple entries are provided, CloudCannon will use them in order as fallback options.
Color values can be hex codes (e.g., #ff0000), CSS color names, or reference a data key that contains a color value.
Examples
In this example, we have configured the icon color for a text input with an array of values to provide fallback options. CloudCannon will use the value of icon_color first, then fall back to the static hex color value.
_inputs:
email_address:
type: text
label: Email
options:
icon: email
icon_color:
- key: icon_color
- text: '#2196F3'
In this example, we have configured the icon color to use a static CSS color value.
_inputs:
phone_number:
type: text
label: Phone
options:
icon: phone
icon_color:
- text: 'blue'
This key defines the background color of the icon displayed beside a Text Input.
The value can be an array or a single value, and reference a key, template, or text string. When multiple entries are provided, CloudCannon will use them in order as fallback options.
Color values can be hex codes (e.g., #ff0000), CSS color names, or reference a data key that contains a color value.
Examples
In this example, we have configured the icon background color for a text input with an array of values to provide fallback options. CloudCannon will use the value of icon_bg_color first, then fall back to the static hex color value.
_inputs:
email_address:
type: text
label: Email
options:
icon: email
icon_background_color:
- key: icon_bg_color
- text: '#e3f2fd'
In this example, we have configured the icon background color to use a static CSS color value.
_inputs:
phone_number:
type: text
label: Phone
options:
icon: phone
icon_background_color:
- text: 'lightblue'
This key defines the subtitle text above an Input.
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.
Examples
In this example, we want to add helpful guidance for our page_description Input.
_inputs:
page_description:
type: text
label: Page Description
comment: Enter a brief description of this page for search engines
This key defines a context box for extra information about an Input.
This key has no default.
Examples
In this example, we want to add a context box to our date_created Input to explain its purpose.
_inputs:
date_created:
type: datetime
label: Date of article creation
instance_value: NOW
context:
open: false
title: Help
icon: help
content: This date field will automatically populate when you create an article.
This key defines the text content inside the context box.
CloudCannon supports a limited selection of Markdown formatting for the value of this key: links, headings, bold, italic, subscript, superscript, and inline code.
This key is required for the context object to function.
This key has no default.
Examples
In this example, we want to provide detailed guidance for our blog_tags Input.
_inputs:
blog_tags:
type: multiselect
label: Blog Tags
context:
title: Tag Guidelines
icon: help
content: |
# Tag Guidelines
Choose 3-5 relevant tags that best describe this article. Tags help readers find related content and improve SEO.
**Good examples:** technology, web development, tutorials
**Avoid:** generic terms like "blog" or "article"
This key defines whether the context box is open to display text content by default.
By default, this key is false (i.e., closed).
Examples
In this example, we want the context box to be open by default so users can immediately see the help information.
_inputs:
seo_description:
type: text
label: SEO Description
context:
open: true
title: SEO Guidelines
icon: info
content: Keep descriptions between 150-160 characters for optimal search engine display.
This key defines the title of the context box.
Examples
In this example, we want to customize the context box title to be more descriptive for our author_bio Input.
_inputs:
author_bio:
type: textarea
label: Author Biography
context:
title: Writing Guidelines
icon: edit
content: Write a brief, professional biography (2-3 sentences) that highlights your expertise and experience.
This key defines which icon appears next to the context box title.
The value must match an icon name from Google's Material Symbols list.
This key has no default.
Examples
In this example, we want to use a warning icon to draw attention to important information about our file_upload Input.
_inputs:
file_upload:
type: file
label: Upload Document
context:
title: File Requirements
icon: warning
content: Maximum file size is 10MB.
options:
max_file_size: 10000
This key defines the bold title text above an Input.
Examples
In this example, we want to customize the label for our page_title Input to be more descriptive.
_inputs:
page_title:
type: text
label: Article Title
comment: Enter the main title for this article
This key defines whether the value of an input is editable in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Disabled inputs are useful if you want CloudCannon to display the input value, but prevent team members from editing the value outside of the Source Editor.
The value of this key can be a boolean or a string. A boolean value of true will prevent team members from editing the value.
A string value can prevent team members from editing an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key is false (i.e., team members can edit input values).
Examples
In this example, we have configured the date_created Date 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
disabled: true
instance_value: NOW
options:
timezone: Etc/UTC
This key defines whether an input is automatically populated with a value when the input is created.
This occurs when creating a new file, or adding array items containing this input.
Valid values are UUID or NOW.
UUIDgenerates a uuidv4 key (extremely unlikely to generate duplicates), useful for identifying unique items (e.g.6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b)NOWgenerates the current datetime in the Site's configured timezone
Examples
In this example, we have configured an input to automatically populate with a UUID when created.
_inputs:
id:
type: text
instance_value: UUID
This key toggles whether CloudCannon will rehydrate inputs configured with an instance_value with a new value when duplicated.
Setting this key to true will prevent rehydration of instance values when inputs are duplicated.
Examples
In this example, CloudCannon will prevent rehydration of instance values when inputs are duplicated.
_inputs:
id:
type: text
instance_value: UUID
disable_instance_value_rehydration: true
This key defines whether CloudCannon should merge this input configuration with any matching, less specific configurations elsewhere in the configuration cascade.
The configuration cascade works by finding the most specific _inputs entry.
Usually, once an option is found in the cascade, there's no reason to keep looking.
When this key is true, the cascade continues looking and each entry found is merged.
This key allows you to define some options globally while using specific options for other keys at different levels of the cascade.
For example, define a comment globally, but use collection-specific label for inputs in different collections.
You can stop the cascade at any point in the configuration cascade by setting cascade to false.
Examples
In this example, we have configured cascade to merge input configurations across the configuration cascade.
_inputs:
title:
type: text
cascade: true
comment: Global comment for all title inputs
This key defines the maximum string length, in characters, that CloudCannon will allow in an Input.
When configured, CloudCannon will warn you when an Input value is too long.
If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
Value can be any non-negative integer.
If this key is set to 0, CloudCannon requires the Input to be empty.
If options.min_length is also configured, this key cannot be a smaller number.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to enter a blog description using the Rich Text seo_description Input. This Input limits you to a maximum of 125 characters.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
min_length: 25
This key defines a custom error message that explains why a value has failed the validation criteria from options.max_length.
This key requires you to define options.max_length.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to enter a valid number of characters using a custom message.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
max_length_message: You are only allowed 125 characters.
min_length: 25
min_length_message: Please write more than 25 characters.
This key defines the minimum string length, in characters, that CloudCannon will allow in an Input.
When configured, CloudCannon will warn you when an Input value is too short.
If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
Value can be any positive integer.
If options.max_length is also configured, this key cannot be a greater number.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to enter a blog description using the Rich Text seo_description Input. This Input requires a minimum of 25 characters.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
min_length: 25
This key defines a custom error message that explains why a value has failed the validation criteria from options.min_length.
This key requires you to define options.min_length.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to enter a valid number of characters using a custom message.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
max_length_message: You are only allowed 125 characters.
min_length: 25
min_length_message: Please write more than 25 characters.
This key defines the maximum string length, in words, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which maximum string length an Input will accept. This key requires you to define `options.max_words.
This key defines the minimum string length, in words, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which minimum string length an Input will accept. This key requires you to define options.min_words.
This key defines the maximum string length, in graphemes, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which maximum string length an Input will accept. This key requires you to define `options.max_graphemes.
This key defines the minimum string length, in graphemes, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which minimum string length an Input will accept. This key requires you to define options.min_graphemes.
This key defines the locale that CloudCannon uses to determine the number of words or graphemes in this Input, if you have max_words, min_words, max_graphemes, or min_graphemes configured.
This key defines a regular expression that the Input value must match.
When configured, CloudCannon will require you to enter a value that matches the REGEX pattern.
If the Input already contains an invalid value, CloudCannon will require you to enter a valid string to save your changes, or discard your unsaved changes.
Value must be a valid REGEX string.
If your REGEX string includes a \ character and CloudCannon Configuration File is a .yml file, use single quotes ' around the string to avoid a
build error.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to add an email address to the contact_email Input using the correct email format.
_inputs:
contact_email:
type: email
options:
pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
pattern_message: 'Please use the format ___@___.__'
This key defines a custom error message that explains why a value has failed the validation criteria from options.pattern.
This key requires you to define options.pattern.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to use the correct email format in the contact_email Input using a pattern message.
_inputs:
contact_email:
type: email
options:
pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
pattern_message: 'Please use the format ___@___.__'
This key defines the flags (e.g. case-insensitive searching) for the regular expression set in options.pattern.
Examples
In this example, we have configured pattern flags for a text input to enable case-insensitive searching.
_inputs:
search_term:
type: text
options:
pattern: "^[a-z]+$"
pattern_flags:
ignore_case: true
This key defines the g flag - Search globally.
This key defines the i flag - Case-insensitive.
This key defines the m flag - ^ and $ match the start and end of each line rather than the entire string.
This key defines the s flag - . matches newline characters.
This key defines the u flag - Pattern is treated as a sequence of Unicode code points.
This key defines the v flag for extended unicode mode.
This key toggles whether CloudCannon requires this Input to have a value.
Setting this key to true will require you to enter a value to save your changes, or discard your unsaved changes.
By default, this key is false (i.e., CloudCannon does not require this Input to have a value).
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we want to require our team to enter an author value for markup files with this Input.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
This key defines a custom error message that explains why a value has failed the validation criteria from options.required.
This key requires you to define options.required.
This key has no default.
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to use enter an Input value using a required message.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
required_message: You are not allowed to leave this blank.
This key defines how an 'empty' value will be saved. Does not apply to existing empty values.
This key represents an array of preview entries for displaying data on Cards in the Collection browser, Structures, and Snippets.
The value is an array of preview entry objects, strings, or false values. Each preview entry object can contain a key, template, or text property. When multiple entries are provided, CloudCannon will use them in order as fallback options.
Examples
In this example, we have configured an array of preview entries with an array of values to provide fallback options. CloudCannon will use the value of title first, then the {name} template, and finally fall back to the static text value.
collections_config:
blog:
preview:
text:
- key: title
- template: '{name}'
- text: 'Untitled'
This key defines a preview entry configuration for displaying data on Cards in the Collection browser, Structures, and Snippets.
The value can be an object with a key, template, or text property, a raw text string, false, or an array of these values. When multiple entries are provided, CloudCannon will use them in order as fallback options. Preview entries are used to configure how data is displayed in card previews.
Examples
In this example, we have configured a preview entry with an array of values to provide fallback options. CloudCannon will use the value of title first, then the {name} template, and finally fall back to the static text value.
collections_config:
blog:
preview:
text:
- key: title
- template: '{name}'
- text: 'Untitled'
In this example, we have configured a preview entry to display the title key.
collections_config:
blog:
preview:
text:
- key: title
This key represents a key preview entry type for displaying data from a specific key on Cards in the Collection browser, Structures, and Snippets.
The value is an object that contains a key property with a string value. This displays the value of the specified data key in card previews.
Examples
In this example, we have configured a key preview entry to display the title key.
collections_config:
blog:
preview:
text:
- key: title
This key defines the data key name to display in a key preview entry.
The value is a string that specifies the name of a data key whose value will be displayed on Cards in the Collection browser, Structures, and Snippets.
Examples
In this example, we have configured the key value to display the title field.
collections_config:
blog:
preview:
text:
- key: title
This key represents a template preview entry type for displaying formatted text using a template on Cards in the Collection browser, Structures, and Snippets.
The value is an object that contains a template property with a string value. This displays formatted text using template syntax (e.g., {name}) in card previews.
Examples
In this example, we have configured a template preview entry to display formatted text.
collections_config:
blog:
preview:
text:
- template: '{author} - {date}'
This key defines the template string to use in a template preview entry.
The value is a string that specifies a template with placeholders (e.g., {name}, {date}) that will be replaced with data values when displayed on Cards in the Collection browser, Structures, and Snippets.
Examples
In this example, we have configured the template value to display author and date.
collections_config:
blog:
preview:
text:
- template: '{author} - {date}'
This key represents a text preview entry type for displaying static text on Cards in the Collection browser, Structures, and Snippets.
The value is an object that contains a text property with a string value. This displays static text in card previews.
Examples
In this example, we have configured a text preview entry to display static text.
collections_config:
blog:
preview:
text:
- text: 'Untitled'
This key defines the static text string to display in a text preview entry.
The value is a string that specifies static text to display on Cards in the Collection browser, Structures, and Snippets.
Examples
In this example, we have configured the text value to display a static fallback message.
collections_config:
blog:
preview:
text:
- text: 'Untitled'
This key represents a raw text preview entry type for displaying static text on Cards in the Collection browser, Structures, and Snippets.
The value is a string that specifies static text to display in card previews. This is equivalent to using { text: "..." } but in a simpler format.
Examples
In this example, we have configured a raw text preview entry to display static text.
collections_config:
blog:
preview:
text: 'Untitled'
This key represents a preview entry that disables the preview display for a specific field on Cards in the Collection browser, Structures, and Snippets.
The value must be false. Setting a preview entry to false will hide that preview element.
Examples
In this example, we have configured the preview text to be disabled.
collections_config:
blog:
preview:
text: false
This key defines an editing interface for plain text.
Examples
In this example, we have configured the description key as a Textarea Input.
_inputs:
description:
type: textarea
label: Description
This key defines the input type, which controls how this input appears and behaves.
Examples
In this example, we have configured the description key as a Textarea Input type.
_inputs:
description:
type: textarea
This key defines the subtitle text above an Input.
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.
Examples
In this example, we want to add helpful guidance for our page_description Input.
_inputs:
page_description:
type: text
label: Page Description
comment: Enter a brief description of this page for search engines
Provides a custom link for documentation for editors shown above input.
This key defines the bold title text above an Input.
Examples
In this example, we want to customize the label for our page_title Input to be more descriptive.
_inputs:
page_title:
type: text
label: Article Title
comment: Enter the main title for this article
This key defines the visibility of an input in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Hidden inputs are useful when you want an input to exist, but not be visible or editable outside of the Source Editor.
Value can be a boolean or a string. A boolean value of true will hide the input.
A string value can hide an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key follows the input naming convention where key names beginning with an underscore are hidden true.
This key defines whether the value of an input is editable in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Disabled inputs are useful if you want CloudCannon to display the input value, but prevent team members from editing the value outside of the Source Editor.
The value of this key can be a boolean or a string. A boolean value of true will prevent team members from editing the value.
A string value can prevent team members from editing an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key is false (i.e., team members can edit input values).
Examples
In this example, we have configured the date_created Date 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
disabled: true
instance_value: NOW
options:
timezone: Etc/UTC
This key defines whether an input is automatically populated with a value when the input is created.
This occurs when creating a new file, or adding array items containing this input.
Valid values are UUID or NOW.
UUIDgenerates a uuidv4 key (extremely unlikely to generate duplicates), useful for identifying unique items (e.g.6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b)NOWgenerates the current datetime in the Site's configured timezone
Examples
In this example, we have configured an input to automatically populate with a UUID when created.
_inputs:
id:
type: text
instance_value: UUID
This key toggles whether CloudCannon will rehydrate inputs configured with an instance_value with a new value when duplicated.
Setting this key to true will prevent rehydration of instance values when inputs are duplicated.
Examples
In this example, CloudCannon will prevent rehydration of instance values when inputs are duplicated.
_inputs:
id:
type: text
instance_value: UUID
disable_instance_value_rehydration: true
This key defines whether CloudCannon should merge this input configuration with any matching, less specific configurations elsewhere in the configuration cascade.
The configuration cascade works by finding the most specific _inputs entry.
Usually, once an option is found in the cascade, there's no reason to keep looking.
When this key is true, the cascade continues looking and each entry found is merged.
This key allows you to define some options globally while using specific options for other keys at different levels of the cascade.
For example, define a comment globally, but use collection-specific label for inputs in different collections.
You can stop the cascade at any point in the configuration cascade by setting cascade to false.
Examples
In this example, we have configured cascade to merge input configurations across the configuration cascade.
_inputs:
title:
type: text
cascade: true
comment: Global comment for all title inputs
This key defines options that are specific to Textarea Inputs.
Examples
In this example, we have configured Textarea Input options including comment and character count.
_inputs:
description:
type: textarea
options:
comment: Enter a description
show_count: true
21 nested properties
This key defines the maximum string length, in characters, that CloudCannon will allow in an Input.
When configured, CloudCannon will warn you when an Input value is too long.
If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
Value can be any non-negative integer.
If this key is set to 0, CloudCannon requires the Input to be empty.
If options.min_length is also configured, this key cannot be a smaller number.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to enter a blog description using the Rich Text seo_description Input. This Input limits you to a maximum of 125 characters.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
min_length: 25
This key defines a custom error message that explains why a value has failed the validation criteria from options.max_length.
This key requires you to define options.max_length.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to enter a valid number of characters using a custom message.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
max_length_message: You are only allowed 125 characters.
min_length: 25
min_length_message: Please write more than 25 characters.
This key defines the minimum string length, in characters, that CloudCannon will allow in an Input.
When configured, CloudCannon will warn you when an Input value is too short.
If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
Value can be any positive integer.
If options.max_length is also configured, this key cannot be a greater number.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to enter a blog description using the Rich Text seo_description Input. This Input requires a minimum of 25 characters.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
min_length: 25
This key defines a custom error message that explains why a value has failed the validation criteria from options.min_length.
This key requires you to define options.min_length.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to enter a valid number of characters using a custom message.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
max_length_message: You are only allowed 125 characters.
min_length: 25
min_length_message: Please write more than 25 characters.
This key defines the maximum string length, in words, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which maximum string length an Input will accept. This key requires you to define `options.max_words.
This key defines the minimum string length, in words, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which minimum string length an Input will accept. This key requires you to define options.min_words.
This key defines the maximum string length, in graphemes, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which maximum string length an Input will accept. This key requires you to define `options.max_graphemes.
This key defines the minimum string length, in graphemes, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which minimum string length an Input will accept. This key requires you to define options.min_graphemes.
This key defines the locale that CloudCannon uses to determine the number of words or graphemes in this Input, if you have max_words, min_words, max_graphemes, or min_graphemes configured.
This key defines a regular expression that the Input value must match.
When configured, CloudCannon will require you to enter a value that matches the REGEX pattern.
If the Input already contains an invalid value, CloudCannon will require you to enter a valid string to save your changes, or discard your unsaved changes.
Value must be a valid REGEX string.
If your REGEX string includes a \ character and CloudCannon Configuration File is a .yml file, use single quotes ' around the string to avoid a
build error.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to add an email address to the contact_email Input using the correct email format.
_inputs:
contact_email:
type: email
options:
pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
pattern_message: 'Please use the format ___@___.__'
This key defines a custom error message that explains why a value has failed the validation criteria from options.pattern.
This key requires you to define options.pattern.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to use the correct email format in the contact_email Input using a pattern message.
_inputs:
contact_email:
type: email
options:
pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
pattern_message: 'Please use the format ___@___.__'
This key defines the flags (e.g. case-insensitive searching) for the regular expression set in options.pattern.
Examples
In this example, we have configured pattern flags for a text input to enable case-insensitive searching.
_inputs:
search_term:
type: text
options:
pattern: "^[a-z]+$"
pattern_flags:
ignore_case: true
6 nested properties
This key defines the g flag - Search globally.
This key defines the i flag - Case-insensitive.
This key defines the m flag - ^ and $ match the start and end of each line rather than the entire string.
This key defines the s flag - . matches newline characters.
This key defines the u flag - Pattern is treated as a sequence of Unicode code points.
This key defines the v flag for extended unicode mode.
This key toggles whether CloudCannon requires this Input to have a value.
Setting this key to true will require you to enter a value to save your changes, or discard your unsaved changes.
By default, this key is false (i.e., CloudCannon does not require this Input to have a value).
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we want to require our team to enter an author value for markup files with this Input.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
This key defines a custom error message that explains why a value has failed the validation criteria from options.required.
This key requires you to define options.required.
This key has no default.
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to use enter an Input value using a required message.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
required_message: You are not allowed to leave this blank.
This key defines the text shown when this input has no value.
Examples
In this example, we have configured a placeholder for a Textarea Input.
_inputs:
description:
type: textarea
options:
placeholder: Enter a description
This key toggles whether a character counter is shown below the input.
Setting this key to true will show a character counter below the input.
Examples
In this example, CloudCannon will show a character counter below the Textarea Input.
_inputs:
description:
type: textarea
options:
show_count: true
This key defines an editing interface for code or mono-spaced plain text content.
This key defines the input type, which controls how this input appears and behaves.
This key defines the subtitle text above an Input.
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.
Examples
In this example, we want to add helpful guidance for our page_description Input.
_inputs:
page_description:
type: text
label: Page Description
comment: Enter a brief description of this page for search engines
Provides a custom link for documentation for editors shown above input.
This key defines the bold title text above an Input.
Examples
In this example, we want to customize the label for our page_title Input to be more descriptive.
_inputs:
page_title:
type: text
label: Article Title
comment: Enter the main title for this article
This key defines the visibility of an input in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Hidden inputs are useful when you want an input to exist, but not be visible or editable outside of the Source Editor.
Value can be a boolean or a string. A boolean value of true will hide the input.
A string value can hide an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key follows the input naming convention where key names beginning with an underscore are hidden true.
This key defines whether the value of an input is editable in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Disabled inputs are useful if you want CloudCannon to display the input value, but prevent team members from editing the value outside of the Source Editor.
The value of this key can be a boolean or a string. A boolean value of true will prevent team members from editing the value.
A string value can prevent team members from editing an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key is false (i.e., team members can edit input values).
Examples
In this example, we have configured the date_created Date 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
disabled: true
instance_value: NOW
options:
timezone: Etc/UTC
This key defines whether an input is automatically populated with a value when the input is created.
This occurs when creating a new file, or adding array items containing this input.
Valid values are UUID or NOW.
UUIDgenerates a uuidv4 key (extremely unlikely to generate duplicates), useful for identifying unique items (e.g.6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b)NOWgenerates the current datetime in the Site's configured timezone
Examples
In this example, we have configured an input to automatically populate with a UUID when created.
_inputs:
id:
type: text
instance_value: UUID
This key toggles whether CloudCannon will rehydrate inputs configured with an instance_value with a new value when duplicated.
Setting this key to true will prevent rehydration of instance values when inputs are duplicated.
Examples
In this example, CloudCannon will prevent rehydration of instance values when inputs are duplicated.
_inputs:
id:
type: text
instance_value: UUID
disable_instance_value_rehydration: true
This key defines whether CloudCannon should merge this input configuration with any matching, less specific configurations elsewhere in the configuration cascade.
The configuration cascade works by finding the most specific _inputs entry.
Usually, once an option is found in the cascade, there's no reason to keep looking.
When this key is true, the cascade continues looking and each entry found is merged.
This key allows you to define some options globally while using specific options for other keys at different levels of the cascade.
For example, define a comment globally, but use collection-specific label for inputs in different collections.
You can stop the cascade at any point in the configuration cascade by setting cascade to false.
Examples
In this example, we have configured cascade to merge input configurations across the configuration cascade.
_inputs:
title:
type: text
cascade: true
comment: Global comment for all title inputs
This key defines options that are specific to Code Inputs.
26 nested properties
This key defines the number of spaces inserted when the Tab key is pressed in a Code Input.
The value is a number representing the number of spaces. This affects both indentation behavior and how existing tabs are displayed.
Examples
In this example, we have configured a code input to use 4 spaces for indentation instead of the default 2.
_inputs:
python_code:
type: code
label: Python Code
options:
tab_size: 4
This key defines the color theme used for syntax highlighting in Code Inputs.
By default, this key is basic_dark.
Examples
In this example, we have configured a code input to use the dracula theme for a dark-colored editing experience.
_inputs:
javascript_code:
type: code
label: JavaScript
options:
theme: dracula
This key toggles whether CloudCannon displays line numbers in the gutter of Code Inputs.
Setting this key to false will hide line numbers in the left gutter of the code editor.
By default, this key is true (i.e., line numbers are displayed).
Examples
In this example, we have configured a code input to hide line numbers by setting show_gutter to false.
_inputs:
css_code:
type: code
label: Custom CSS
options:
show_gutter: false
This key toggles whether long lines wrap to the next line in Code Inputs.
Setting this key to true will wrap lines that exceed the width of the code area to the next line without adding a line break character.
By default, this key is false (i.e., long lines extend horizontally and require horizontal scrolling).
Examples
In this example, we have configured a code input to enable soft line wrapping for better readability of long lines.
_inputs:
markdown_content:
type: code
label: Markdown
options:
soft_wrap: true
This key defines the maximum string length, in characters, that CloudCannon will allow in an Input.
When configured, CloudCannon will warn you when an Input value is too long.
If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
Value can be any non-negative integer.
If this key is set to 0, CloudCannon requires the Input to be empty.
If options.min_length is also configured, this key cannot be a smaller number.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to enter a blog description using the Rich Text seo_description Input. This Input limits you to a maximum of 125 characters.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
min_length: 25
This key defines a custom error message that explains why a value has failed the validation criteria from options.max_length.
This key requires you to define options.max_length.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to enter a valid number of characters using a custom message.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
max_length_message: You are only allowed 125 characters.
min_length: 25
min_length_message: Please write more than 25 characters.
This key defines the minimum string length, in characters, that CloudCannon will allow in an Input.
When configured, CloudCannon will warn you when an Input value is too short.
If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
Value can be any positive integer.
If options.max_length is also configured, this key cannot be a greater number.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to enter a blog description using the Rich Text seo_description Input. This Input requires a minimum of 25 characters.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
min_length: 25
This key defines a custom error message that explains why a value has failed the validation criteria from options.min_length.
This key requires you to define options.min_length.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to enter a valid number of characters using a custom message.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
max_length_message: You are only allowed 125 characters.
min_length: 25
min_length_message: Please write more than 25 characters.
This key defines the maximum string length, in words, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which maximum string length an Input will accept. This key requires you to define `options.max_words.
This key defines the minimum string length, in words, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which minimum string length an Input will accept. This key requires you to define options.min_words.
This key defines the maximum string length, in graphemes, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which maximum string length an Input will accept. This key requires you to define `options.max_graphemes.
This key defines the minimum string length, in graphemes, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which minimum string length an Input will accept. This key requires you to define options.min_graphemes.
This key defines the locale that CloudCannon uses to determine the number of words or graphemes in this Input, if you have max_words, min_words, max_graphemes, or min_graphemes configured.
This key defines a regular expression that the Input value must match.
When configured, CloudCannon will require you to enter a value that matches the REGEX pattern.
If the Input already contains an invalid value, CloudCannon will require you to enter a valid string to save your changes, or discard your unsaved changes.
Value must be a valid REGEX string.
If your REGEX string includes a \ character and CloudCannon Configuration File is a .yml file, use single quotes ' around the string to avoid a
build error.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to add an email address to the contact_email Input using the correct email format.
_inputs:
contact_email:
type: email
options:
pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
pattern_message: 'Please use the format ___@___.__'
This key defines a custom error message that explains why a value has failed the validation criteria from options.pattern.
This key requires you to define options.pattern.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to use the correct email format in the contact_email Input using a pattern message.
_inputs:
contact_email:
type: email
options:
pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
pattern_message: 'Please use the format ___@___.__'
This key defines the flags (e.g. case-insensitive searching) for the regular expression set in options.pattern.
Examples
In this example, we have configured pattern flags for a text input to enable case-insensitive searching.
_inputs:
search_term:
type: text
options:
pattern: "^[a-z]+$"
pattern_flags:
ignore_case: true
6 nested properties
This key defines the g flag - Search globally.
This key defines the i flag - Case-insensitive.
This key defines the m flag - ^ and $ match the start and end of each line rather than the entire string.
This key defines the s flag - . matches newline characters.
This key defines the u flag - Pattern is treated as a sequence of Unicode code points.
This key defines the v flag for extended unicode mode.
This key toggles whether CloudCannon requires this Input to have a value.
Setting this key to true will require you to enter a value to save your changes, or discard your unsaved changes.
By default, this key is false (i.e., CloudCannon does not require this Input to have a value).
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we want to require our team to enter an author value for markup files with this Input.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
This key defines a custom error message that explains why a value has failed the validation criteria from options.required.
This key requires you to define options.required.
This key has no default.
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to use enter an Input value using a required message.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
required_message: You are not allowed to leave this blank.
This key defines the maximum number of visible lines for this input, effectively controlling maximum height.
When the containing text exceeds this number, the input becomes a scroll area.
This key defines the minimum number of visible lines for this input, effectively controlling initial height.
When the containing text exceeds this number, the input grows line by line to the lines defined by max_visible_lines.
This key defines how the editor parses your content for syntax highlighting.
Should be set to the language of the code going into the input.
Available syntax highlighting languages for code editors in CloudCannon.
This key defines an editing interface for color values.
This key defines the input type, which controls how this input appears and behaves.
This key defines the subtitle text above an Input.
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.
Examples
In this example, we want to add helpful guidance for our page_description Input.
_inputs:
page_description:
type: text
label: Page Description
comment: Enter a brief description of this page for search engines
Provides a custom link for documentation for editors shown above input.
This key defines the bold title text above an Input.
Examples
In this example, we want to customize the label for our page_title Input to be more descriptive.
_inputs:
page_title:
type: text
label: Article Title
comment: Enter the main title for this article
This key defines the visibility of an input in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Hidden inputs are useful when you want an input to exist, but not be visible or editable outside of the Source Editor.
Value can be a boolean or a string. A boolean value of true will hide the input.
A string value can hide an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key follows the input naming convention where key names beginning with an underscore are hidden true.
This key defines whether the value of an input is editable in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Disabled inputs are useful if you want CloudCannon to display the input value, but prevent team members from editing the value outside of the Source Editor.
The value of this key can be a boolean or a string. A boolean value of true will prevent team members from editing the value.
A string value can prevent team members from editing an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key is false (i.e., team members can edit input values).
Examples
In this example, we have configured the date_created Date 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
disabled: true
instance_value: NOW
options:
timezone: Etc/UTC
This key defines whether an input is automatically populated with a value when the input is created.
This occurs when creating a new file, or adding array items containing this input.
Valid values are UUID or NOW.
UUIDgenerates a uuidv4 key (extremely unlikely to generate duplicates), useful for identifying unique items (e.g.6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b)NOWgenerates the current datetime in the Site's configured timezone
Examples
In this example, we have configured an input to automatically populate with a UUID when created.
_inputs:
id:
type: text
instance_value: UUID
This key toggles whether CloudCannon will rehydrate inputs configured with an instance_value with a new value when duplicated.
Setting this key to true will prevent rehydration of instance values when inputs are duplicated.
Examples
In this example, CloudCannon will prevent rehydration of instance values when inputs are duplicated.
_inputs:
id:
type: text
instance_value: UUID
disable_instance_value_rehydration: true
This key defines whether CloudCannon should merge this input configuration with any matching, less specific configurations elsewhere in the configuration cascade.
The configuration cascade works by finding the most specific _inputs entry.
Usually, once an option is found in the cascade, there's no reason to keep looking.
When this key is true, the cascade continues looking and each entry found is merged.
This key allows you to define some options globally while using specific options for other keys at different levels of the cascade.
For example, define a comment globally, but use collection-specific label for inputs in different collections.
You can stop the cascade at any point in the configuration cascade by setting cascade to false.
Examples
In this example, we have configured cascade to merge input configurations across the configuration cascade.
_inputs:
title:
type: text
cascade: true
comment: Global comment for all title inputs
This key defines options that are specific to Color Inputs.
23 nested properties
This key defines the maximum string length, in characters, that CloudCannon will allow in an Input.
When configured, CloudCannon will warn you when an Input value is too long.
If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
Value can be any non-negative integer.
If this key is set to 0, CloudCannon requires the Input to be empty.
If options.min_length is also configured, this key cannot be a smaller number.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to enter a blog description using the Rich Text seo_description Input. This Input limits you to a maximum of 125 characters.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
min_length: 25
This key defines a custom error message that explains why a value has failed the validation criteria from options.max_length.
This key requires you to define options.max_length.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to enter a valid number of characters using a custom message.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
max_length_message: You are only allowed 125 characters.
min_length: 25
min_length_message: Please write more than 25 characters.
This key defines the minimum string length, in characters, that CloudCannon will allow in an Input.
When configured, CloudCannon will warn you when an Input value is too short.
If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
Value can be any positive integer.
If options.max_length is also configured, this key cannot be a greater number.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to enter a blog description using the Rich Text seo_description Input. This Input requires a minimum of 25 characters.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
min_length: 25
This key defines a custom error message that explains why a value has failed the validation criteria from options.min_length.
This key requires you to define options.min_length.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to enter a valid number of characters using a custom message.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
max_length_message: You are only allowed 125 characters.
min_length: 25
min_length_message: Please write more than 25 characters.
This key defines the maximum string length, in words, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which maximum string length an Input will accept. This key requires you to define `options.max_words.
This key defines the minimum string length, in words, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which minimum string length an Input will accept. This key requires you to define options.min_words.
This key defines the maximum string length, in graphemes, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which maximum string length an Input will accept. This key requires you to define `options.max_graphemes.
This key defines the minimum string length, in graphemes, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which minimum string length an Input will accept. This key requires you to define options.min_graphemes.
This key defines the locale that CloudCannon uses to determine the number of words or graphemes in this Input, if you have max_words, min_words, max_graphemes, or min_graphemes configured.
This key defines a regular expression that the Input value must match.
When configured, CloudCannon will require you to enter a value that matches the REGEX pattern.
If the Input already contains an invalid value, CloudCannon will require you to enter a valid string to save your changes, or discard your unsaved changes.
Value must be a valid REGEX string.
If your REGEX string includes a \ character and CloudCannon Configuration File is a .yml file, use single quotes ' around the string to avoid a
build error.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to add an email address to the contact_email Input using the correct email format.
_inputs:
contact_email:
type: email
options:
pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
pattern_message: 'Please use the format ___@___.__'
This key defines a custom error message that explains why a value has failed the validation criteria from options.pattern.
This key requires you to define options.pattern.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to use the correct email format in the contact_email Input using a pattern message.
_inputs:
contact_email:
type: email
options:
pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
pattern_message: 'Please use the format ___@___.__'
This key defines the flags (e.g. case-insensitive searching) for the regular expression set in options.pattern.
Examples
In this example, we have configured pattern flags for a text input to enable case-insensitive searching.
_inputs:
search_term:
type: text
options:
pattern: "^[a-z]+$"
pattern_flags:
ignore_case: true
6 nested properties
This key defines the g flag - Search globally.
This key defines the i flag - Case-insensitive.
This key defines the m flag - ^ and $ match the start and end of each line rather than the entire string.
This key defines the s flag - . matches newline characters.
This key defines the u flag - Pattern is treated as a sequence of Unicode code points.
This key defines the v flag for extended unicode mode.
This key toggles whether CloudCannon requires this Input to have a value.
Setting this key to true will require you to enter a value to save your changes, or discard your unsaved changes.
By default, this key is false (i.e., CloudCannon does not require this Input to have a value).
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we want to require our team to enter an author value for markup files with this Input.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
This key defines a custom error message that explains why a value has failed the validation criteria from options.required.
This key requires you to define options.required.
This key has no default.
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to use enter an Input value using a required message.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
required_message: You are not allowed to leave this blank.
This key defines what format the color value is saved as.
Defaults to the naming convention, or "hex" if that is unset.
This key toggles whether CloudCannon will show a control for adjusting the transparency of the selected color.
Setting this key to true will show a control for adjusting the transparency of the selected color.
By default, this key uses the naming convention (i.e., enabled if the input key ends with "a").
This key defines a predefined color palette for Color Inputs.
The value is an array of color strings. Each string can be a hex code (e.g., #ff0000), CSS color name, or other valid color format.
When a palette is configured, users can select colors from the palette in addition to using the color picker (unless hide_picker is set to true).
Examples
In this example, we have configured a color input with a palette of brand colors for quick selection.
_inputs:
primary_color:
type: color
label: Primary Color
options:
palette:
- '#ff0000'
- '#00ff00'
- '#0000ff'
- '#ffff00'
In this example, we have configured a color input with a palette using CSS color names.
_inputs:
accent_color:
type: color
label: Accent Color
options:
palette:
- red
- blue
- green
- yellow
This key toggles whether CloudCannon hides the color picker UI in Color Inputs.
Setting this key to true will hide the color picker interface, requiring users to enter color values manually or select from a palette if one is configured.
By default, this key is false (i.e., the color picker is displayed).
Examples
In this example, we have configured a color input to hide the picker UI, requiring users to select from the predefined palette or enter values manually.
_inputs:
brand_color:
type: color
label: Brand Color
options:
palette:
- '#ff0000'
- '#00ff00'
- '#0000ff'
hide_picker: true
This key defines an editing interface for true or false values.
Examples
In this example, we have configured the featured key as a Boolean Input.
_inputs:
featured:
type: switch
label: Featured
This key defines the input type, which controls how this input appears and behaves.
Examples
In this example, we have configured the featured key as a Boolean Input type.
_inputs:
featured:
type: switch
This key defines the subtitle text above an Input.
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.
Examples
In this example, we want to add helpful guidance for our page_description Input.
_inputs:
page_description:
type: text
label: Page Description
comment: Enter a brief description of this page for search engines
Provides a custom link for documentation for editors shown above input.
This key defines the bold title text above an Input.
Examples
In this example, we want to customize the label for our page_title Input to be more descriptive.
_inputs:
page_title:
type: text
label: Article Title
comment: Enter the main title for this article
This key defines the visibility of an input in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Hidden inputs are useful when you want an input to exist, but not be visible or editable outside of the Source Editor.
Value can be a boolean or a string. A boolean value of true will hide the input.
A string value can hide an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key follows the input naming convention where key names beginning with an underscore are hidden true.
This key defines whether the value of an input is editable in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Disabled inputs are useful if you want CloudCannon to display the input value, but prevent team members from editing the value outside of the Source Editor.
The value of this key can be a boolean or a string. A boolean value of true will prevent team members from editing the value.
A string value can prevent team members from editing an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key is false (i.e., team members can edit input values).
Examples
In this example, we have configured the date_created Date 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
disabled: true
instance_value: NOW
options:
timezone: Etc/UTC
This key defines whether an input is automatically populated with a value when the input is created.
This occurs when creating a new file, or adding array items containing this input.
Valid values are UUID or NOW.
UUIDgenerates a uuidv4 key (extremely unlikely to generate duplicates), useful for identifying unique items (e.g.6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b)NOWgenerates the current datetime in the Site's configured timezone
Examples
In this example, we have configured an input to automatically populate with a UUID when created.
_inputs:
id:
type: text
instance_value: UUID
This key toggles whether CloudCannon will rehydrate inputs configured with an instance_value with a new value when duplicated.
Setting this key to true will prevent rehydration of instance values when inputs are duplicated.
Examples
In this example, CloudCannon will prevent rehydration of instance values when inputs are duplicated.
_inputs:
id:
type: text
instance_value: UUID
disable_instance_value_rehydration: true
This key defines whether CloudCannon should merge this input configuration with any matching, less specific configurations elsewhere in the configuration cascade.
The configuration cascade works by finding the most specific _inputs entry.
Usually, once an option is found in the cascade, there's no reason to keep looking.
When this key is true, the cascade continues looking and each entry found is merged.
This key allows you to define some options globally while using specific options for other keys at different levels of the cascade.
For example, define a comment globally, but use collection-specific label for inputs in different collections.
You can stop the cascade at any point in the configuration cascade by setting cascade to false.
Examples
In this example, we have configured cascade to merge input configurations across the configuration cascade.
_inputs:
title:
type: text
cascade: true
comment: Global comment for all title inputs
This key defines an editing interface for numeric values.
Examples
In this example, we have configured the quantity key as a Number Input.
_inputs:
quantity:
type: number
label: Quantity
This key defines the input type, which controls how this input appears and behaves.
Examples
In this example, we have configured the quantity key as a Number Input type.
_inputs:
quantity:
type: number
This key defines the subtitle text above an Input.
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.
Examples
In this example, we want to add helpful guidance for our page_description Input.
_inputs:
page_description:
type: text
label: Page Description
comment: Enter a brief description of this page for search engines
Provides a custom link for documentation for editors shown above input.
This key defines the bold title text above an Input.
Examples
In this example, we want to customize the label for our page_title Input to be more descriptive.
_inputs:
page_title:
type: text
label: Article Title
comment: Enter the main title for this article
This key defines the visibility of an input in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Hidden inputs are useful when you want an input to exist, but not be visible or editable outside of the Source Editor.
Value can be a boolean or a string. A boolean value of true will hide the input.
A string value can hide an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key follows the input naming convention where key names beginning with an underscore are hidden true.
This key defines whether the value of an input is editable in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Disabled inputs are useful if you want CloudCannon to display the input value, but prevent team members from editing the value outside of the Source Editor.
The value of this key can be a boolean or a string. A boolean value of true will prevent team members from editing the value.
A string value can prevent team members from editing an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key is false (i.e., team members can edit input values).
Examples
In this example, we have configured the date_created Date 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
disabled: true
instance_value: NOW
options:
timezone: Etc/UTC
This key defines whether an input is automatically populated with a value when the input is created.
This occurs when creating a new file, or adding array items containing this input.
Valid values are UUID or NOW.
UUIDgenerates a uuidv4 key (extremely unlikely to generate duplicates), useful for identifying unique items (e.g.6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b)NOWgenerates the current datetime in the Site's configured timezone
Examples
In this example, we have configured an input to automatically populate with a UUID when created.
_inputs:
id:
type: text
instance_value: UUID
This key toggles whether CloudCannon will rehydrate inputs configured with an instance_value with a new value when duplicated.
Setting this key to true will prevent rehydration of instance values when inputs are duplicated.
Examples
In this example, CloudCannon will prevent rehydration of instance values when inputs are duplicated.
_inputs:
id:
type: text
instance_value: UUID
disable_instance_value_rehydration: true
This key defines whether CloudCannon should merge this input configuration with any matching, less specific configurations elsewhere in the configuration cascade.
The configuration cascade works by finding the most specific _inputs entry.
Usually, once an option is found in the cascade, there's no reason to keep looking.
When this key is true, the cascade continues looking and each entry found is merged.
This key allows you to define some options globally while using specific options for other keys at different levels of the cascade.
For example, define a comment globally, but use collection-specific label for inputs in different collections.
You can stop the cascade at any point in the configuration cascade by setting cascade to false.
Examples
In this example, we have configured cascade to merge input configurations across the configuration cascade.
_inputs:
title:
type: text
cascade: true
comment: Global comment for all title inputs
This key defines options that are specific to Number Inputs.
Examples
In this example, we have configured Number Input options including min and max values.
_inputs:
quantity:
type: number
options:
min: 1
max: 100
8 nested properties
This key toggles whether CloudCannon requires this Input to have a value.
Setting this key to true will require you to enter a value to save your changes, or discard your unsaved changes.
By default, this key is false (i.e., CloudCannon does not require this Input to have a value).
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we want to require our team to enter an author value for markup files with this Input.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
This key defines a custom error message that explains why a value has failed the validation criteria from options.required.
This key requires you to define options.required.
This key has no default.
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to use enter an Input value using a required message.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
required_message: You are not allowed to leave this blank.
This key defines a number that specifies the granularity that the value must adhere to, or the special value any, which allows any decimal value between max and min.
Examples
In this example, we have configured a Range Input to use a step value of 5.
_inputs:
rating:
type: range
options:
min: 0
max: 100
step: 5
This key defines a custom error message that explains why a value has failed the validation criteria from options.min.
This key requires you to define options.min.
This key has no default.
This key is available for Number Inputs.
Examples
In this example, we prompt our team to enter a valid number using a custom message.
_inputs:
rating:
type: number
comment: How highly did you rate this experience?
options:
max: 5
max_message: Cannot be more than 5
min: 1
min_message: Cannot be less than 1
This key defines a custom error message that explains why a value has failed the validation criteria from options.max.
This key requires you to define options.max.
This key has no default.
This key is available for Number Inputs.
Examples
In this example, we prompt our team to enter a valid number using a custom message.
_inputs:
rating:
type: number
comment: How highly did you rate this experience?
options:
max: 5
max_message: Cannot be more than 5
min: 1
min_message: Cannot be less than 1
This key defines how an 'empty' value will be saved. Does not apply to existing empty values.
Examples
In this example, we have configured how empty number values will be saved.
_inputs:
quantity:
type: number
options:
empty_type: number
This key defines the minimum numerical value CloudCannon will allow in an Input.
When configured, CloudCannon will prevent you from entering a lesser numerical value.
If the Input already contains a lesser numerical value, CloudCannon will require you to enter a valid value to save your changes, or discard your unsaved changes.
This key is required for range inputs.
Value can be any number.
If options.max is also configured, this key cannot be a greater number.
This key has no default.
This key is available for Number Inputs.
Examples
In this example, we want to add a rating out of five for each article in our travel blog using the rating Input. This Input limits you to a minimum rating of one.
_inputs:
rating:
type: number
comment: How highly did you rate this experience?
options:
max: 5
min: 1
This key defines the maximum numerical value CloudCannon will allow in an Input.
When configured, CloudCannon will prevent you from entering a greater numerical value.
If the Input already contains a greater numerical value, CloudCannon will require you to enter a valid value to save your changes, or discard your unsaved changes.
This key is required for range inputs.
Value can be any integer.
If options.min is also configured, this key cannot be a lesser number.
This key has no default.
This key is available for Number Inputs.
Examples
In this example, we want to add a rating out of five for each article in our travel blog using the rating Input. This Input limits you to a maximum rating of five.
_inputs:
rating:
type: number
comment: How highly did you rate this experience?
options:
max: 5
min: 1
This key defines a number that specifies the granularity that the value must adhere to, or the special value any, which allows any decimal value between max and min.
Examples
In this example, we have configured a Range Input to use a step value of 5.
_inputs:
rating:
type: range
options:
min: 0
max: 100
step: 5
This key defines a custom error message that explains why a value has failed the validation criteria from options.min.
This key requires you to define options.min.
This key has no default.
This key is available for Number Inputs.
Examples
In this example, we prompt our team to enter a valid number using a custom message.
_inputs:
rating:
type: number
comment: How highly did you rate this experience?
options:
max: 5
max_message: Cannot be more than 5
min: 1
min_message: Cannot be less than 1
This key defines a custom error message that explains why a value has failed the validation criteria from options.max.
This key requires you to define options.max.
This key has no default.
This key is available for Number Inputs.
Examples
In this example, we prompt our team to enter a valid number using a custom message.
_inputs:
rating:
type: number
comment: How highly did you rate this experience?
options:
max: 5
max_message: Cannot be more than 5
min: 1
min_message: Cannot be less than 1
This key defines a slider interface for selecting a numeric value.
This key defines the input type, which controls how this input appears and behaves.
This key defines the subtitle text above an Input.
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.
Examples
In this example, we want to add helpful guidance for our page_description Input.
_inputs:
page_description:
type: text
label: Page Description
comment: Enter a brief description of this page for search engines
Provides a custom link for documentation for editors shown above input.
This key defines the bold title text above an Input.
Examples
In this example, we want to customize the label for our page_title Input to be more descriptive.
_inputs:
page_title:
type: text
label: Article Title
comment: Enter the main title for this article
This key defines the visibility of an input in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Hidden inputs are useful when you want an input to exist, but not be visible or editable outside of the Source Editor.
Value can be a boolean or a string. A boolean value of true will hide the input.
A string value can hide an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key follows the input naming convention where key names beginning with an underscore are hidden true.
This key defines whether the value of an input is editable in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Disabled inputs are useful if you want CloudCannon to display the input value, but prevent team members from editing the value outside of the Source Editor.
The value of this key can be a boolean or a string. A boolean value of true will prevent team members from editing the value.
A string value can prevent team members from editing an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key is false (i.e., team members can edit input values).
Examples
In this example, we have configured the date_created Date 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
disabled: true
instance_value: NOW
options:
timezone: Etc/UTC
This key defines whether an input is automatically populated with a value when the input is created.
This occurs when creating a new file, or adding array items containing this input.
Valid values are UUID or NOW.
UUIDgenerates a uuidv4 key (extremely unlikely to generate duplicates), useful for identifying unique items (e.g.6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b)NOWgenerates the current datetime in the Site's configured timezone
Examples
In this example, we have configured an input to automatically populate with a UUID when created.
_inputs:
id:
type: text
instance_value: UUID
This key toggles whether CloudCannon will rehydrate inputs configured with an instance_value with a new value when duplicated.
Setting this key to true will prevent rehydration of instance values when inputs are duplicated.
Examples
In this example, CloudCannon will prevent rehydration of instance values when inputs are duplicated.
_inputs:
id:
type: text
instance_value: UUID
disable_instance_value_rehydration: true
This key defines whether CloudCannon should merge this input configuration with any matching, less specific configurations elsewhere in the configuration cascade.
The configuration cascade works by finding the most specific _inputs entry.
Usually, once an option is found in the cascade, there's no reason to keep looking.
When this key is true, the cascade continues looking and each entry found is merged.
This key allows you to define some options globally while using specific options for other keys at different levels of the cascade.
For example, define a comment globally, but use collection-specific label for inputs in different collections.
You can stop the cascade at any point in the configuration cascade by setting cascade to false.
Examples
In this example, we have configured cascade to merge input configurations across the configuration cascade.
_inputs:
title:
type: text
cascade: true
comment: Global comment for all title inputs
This key defines options that are specific to Range Inputs.
8 nested properties
This key defines the minimum numerical value CloudCannon will allow in an Input.
When configured, CloudCannon will prevent you from entering a lesser numerical value.
If the Input already contains a lesser numerical value, CloudCannon will require you to enter a valid value to save your changes, or discard your unsaved changes.
This key is required for range inputs.
Value can be any number.
If options.max is also configured, this key cannot be a greater number.
This key has no default.
This key is available for Number Inputs.
Examples
In this example, we want to add a rating out of five for each article in our travel blog using the rating Input. This Input limits you to a minimum rating of one.
_inputs:
rating:
type: number
comment: How highly did you rate this experience?
options:
max: 5
min: 1
This key defines the maximum numerical value CloudCannon will allow in an Input.
When configured, CloudCannon will prevent you from entering a greater numerical value.
If the Input already contains a greater numerical value, CloudCannon will require you to enter a valid value to save your changes, or discard your unsaved changes.
This key is required for range inputs.
Value can be any integer.
If options.min is also configured, this key cannot be a lesser number.
This key has no default.
This key is available for Number Inputs.
Examples
In this example, we want to add a rating out of five for each article in our travel blog using the rating Input. This Input limits you to a maximum rating of five.
_inputs:
rating:
type: number
comment: How highly did you rate this experience?
options:
max: 5
min: 1
This key toggles whether CloudCannon requires this Input to have a value.
Setting this key to true will require you to enter a value to save your changes, or discard your unsaved changes.
By default, this key is false (i.e., CloudCannon does not require this Input to have a value).
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we want to require our team to enter an author value for markup files with this Input.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
This key defines a custom error message that explains why a value has failed the validation criteria from options.required.
This key requires you to define options.required.
This key has no default.
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to use enter an Input value using a required message.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
required_message: You are not allowed to leave this blank.
This key defines a number that specifies the granularity that the value must adhere to, or the special value any, which allows any decimal value between max and min.
Examples
In this example, we have configured a Range Input to use a step value of 5.
_inputs:
rating:
type: range
options:
min: 0
max: 100
step: 5
This key defines a custom error message that explains why a value has failed the validation criteria from options.min.
This key requires you to define options.min.
This key has no default.
This key is available for Number Inputs.
Examples
In this example, we prompt our team to enter a valid number using a custom message.
_inputs:
rating:
type: number
comment: How highly did you rate this experience?
options:
max: 5
max_message: Cannot be more than 5
min: 1
min_message: Cannot be less than 1
This key defines a custom error message that explains why a value has failed the validation criteria from options.max.
This key requires you to define options.max.
This key has no default.
This key is available for Number Inputs.
Examples
In this example, we prompt our team to enter a valid number using a custom message.
_inputs:
rating:
type: number
comment: How highly did you rate this experience?
options:
max: 5
max_message: Cannot be more than 5
min: 1
min_message: Cannot be less than 1
This key defines an editing interface for HTML markup content.
This key defines the input type, which controls how this input appears and behaves.
This key defines the subtitle text above an Input.
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.
Examples
In this example, we want to add helpful guidance for our page_description Input.
_inputs:
page_description:
type: text
label: Page Description
comment: Enter a brief description of this page for search engines
Provides a custom link for documentation for editors shown above input.
This key defines the bold title text above an Input.
Examples
In this example, we want to customize the label for our page_title Input to be more descriptive.
_inputs:
page_title:
type: text
label: Article Title
comment: Enter the main title for this article
This key defines the visibility of an input in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Hidden inputs are useful when you want an input to exist, but not be visible or editable outside of the Source Editor.
Value can be a boolean or a string. A boolean value of true will hide the input.
A string value can hide an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key follows the input naming convention where key names beginning with an underscore are hidden true.
This key defines whether the value of an input is editable in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Disabled inputs are useful if you want CloudCannon to display the input value, but prevent team members from editing the value outside of the Source Editor.
The value of this key can be a boolean or a string. A boolean value of true will prevent team members from editing the value.
A string value can prevent team members from editing an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key is false (i.e., team members can edit input values).
Examples
In this example, we have configured the date_created Date 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
disabled: true
instance_value: NOW
options:
timezone: Etc/UTC
This key defines whether an input is automatically populated with a value when the input is created.
This occurs when creating a new file, or adding array items containing this input.
Valid values are UUID or NOW.
UUIDgenerates a uuidv4 key (extremely unlikely to generate duplicates), useful for identifying unique items (e.g.6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b)NOWgenerates the current datetime in the Site's configured timezone
Examples
In this example, we have configured an input to automatically populate with a UUID when created.
_inputs:
id:
type: text
instance_value: UUID
This key toggles whether CloudCannon will rehydrate inputs configured with an instance_value with a new value when duplicated.
Setting this key to true will prevent rehydration of instance values when inputs are duplicated.
Examples
In this example, CloudCannon will prevent rehydration of instance values when inputs are duplicated.
_inputs:
id:
type: text
instance_value: UUID
disable_instance_value_rehydration: true
This key defines whether CloudCannon should merge this input configuration with any matching, less specific configurations elsewhere in the configuration cascade.
The configuration cascade works by finding the most specific _inputs entry.
Usually, once an option is found in the cascade, there's no reason to keep looking.
When this key is true, the cascade continues looking and each entry found is merged.
This key allows you to define some options globally while using specific options for other keys at different levels of the cascade.
For example, define a comment globally, but use collection-specific label for inputs in different collections.
You can stop the cascade at any point in the configuration cascade by setting cascade to false.
Examples
In this example, we have configured cascade to merge input configurations across the configuration cascade.
_inputs:
title:
type: text
cascade: true
comment: Global comment for all title inputs
This key defines options that are specific to Rich Text Inputs.
66 nested properties
This key defines what format an image is converted to prior to upload.
Examples
In this example, we have configured an Image Input to convert images to WebP format prior to upload.
_inputs:
hero_image:
type: image
options:
mime_type: image/webp
This key defines how image files are resized prior to upload, using a bounding box defined by width and height options.
Valid values are cover, contain, crop, or stretch:
coverkeeps aspect ratio and ensures the image covers the bounding boxcontainkeeps aspect ratio and ensures the image fits inside the bounding boxcropprompts the user with and interface to select an aspect-ratio-respecting areastretchignores aspect ratio and resizes the image to the bounding box
This key does not apply to existing images, and does not work if width and height options are not defined.
Examples
In this example, we have configured an Image Input to resize images using the cover style to ensure images cover the bounding box while maintaining aspect ratio.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines the width of the bounding box used in the resizing method defined by resize_style.
This key defines the height of the bounding box used in the resizing method defined by resize_style.
Examples
In this example, we have configured the height of the bounding box for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines whether you can upscale an image to fit the bounding box while resizing an image prior to upload.
Has no effect if files are not resized.
Examples
In this example, we have configured an Image Input to allow upscaling images to fit the bounding box while resizing.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
expandable: true
This key toggles whether CloudCannon will instruct a rich text editor to save width and height attributes on image elements.
Setting this key to true will instruct the rich text editor to save width and height attributes on image elements. This can prevent pop-in as a page loads.
By default, this key is false (i.e., width and height attributes are not saved on image elements). This defaults to true if the Image Size Attributes site flag is enabled (this is enabled for sites created before June 23 2023, in order to keep those sites working).
Examples
In this example, CloudCannon will save width and height attributes on image elements in a Rich Text Input.
_inputs:
content:
type: markdown
options:
image_size_attributes: true
This key defines which sources and DAMs you are allowed to upload to and browse.
The value can be an array of strings. Valid values include site-files and the reference key for any DAM connected to your site.
If site-files is omitted from the array, site files will not be available as an asset source for this input.
Examples
In this example, we have configured allowed sources for an Image Input.
_inputs:
image:
type: image
options:
allowed_sources:
- site-files
- my-cloudinary-dam
This key toggles whether CloudCannon will skip the image resizing process configured for this input when selecting existing images.
Setting this key to true will skip the image resizing process when selecting existing images.
Examples
In this example, CloudCannon will skip the image resizing process when selecting existing images for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
prevent_resize_existing_files: true
This key defines definitions for creating additional images of different sizes when uploading or selecting existing files.
Examples
In this example, we have configured an Image Input to create additional images of different sizes when uploading or selecting files.
_inputs:
hero_image:
type: image
options:
sizes:
- size: 2x
- size: 3x
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to bold selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to bold selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to copy formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to copy formatting from selected text. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not copy other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to italicize selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to italicize selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to redo recent edits undone with undo.
Setting this key to true will enable a tool in your WYSIWYG toolbar to redo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to remove formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to remove formatting. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not remove other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to strike through selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to strike through selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to subscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to subscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to superscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to superscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to underline selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to underline selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to undo recent edits.
Setting this key to true will enable a tool in your WYSIWYG toolbar to undo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will allow you to strip custom markup from content edited in a rich text editor, allowing you to clean files of unnecessary HTML content.
Setting this key to true will enable stripping custom markup from content. The remove_custom_markup key is disabled if allow_custom_markup is enabled.
This key toggles whether CloudCannon will allow you to edit custom markup in rich text editors and explicitly accept the risk of unintentionally deleting elements that cannot be recreated.
Setting this key to true will enable editing of custom markup. When using allow_custom_markup outside of editable regions, content that uses JavaScript will not be editable for security reasons. These inputs will appear as uneditable snippets.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to wrap selected blocks of text in a block quote.
Setting this key to true will enable a tool in your WYSIWYG toolbar to wrap selected blocks of text in a block quote.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an unordered list or convert selected text to an unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an unordered list or convert selected text to an unordered list.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to center align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to center align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a control in your WYSIWYG toolbar to create an inline code element, containing any selected text.
Setting this key to true will enable a control in your WYSIWYG toolbar to create an inline code element.
By default, this key is false (i.e., the inline code control is not displayed).
This key toggles whether CloudCannon will display a control in your WYSIWYG toolbar to insert a code block in editable regions.
Setting this key to true will enable a control in your WYSIWYG toolbar to insert a code block.
By default, this key is false (i.e., the code block control is not displayed).
This key toggles whether CloudCannon will display tools in your WYSIWYG toolbar to turn selected text into inline code and selected text into a code block.
Setting this key to true will enable two tools in your WYSIWYG toolbar to turn selected text into inline code and selected text into a code block.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a region of raw HTML for YouTube, Vimeo, social media posts, or other media.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a region of raw HTML. Embedded content is sanitized to mitigate XSS risks, which includes removing style tags. Embeds containing script tags are not loaded a rich text editor.
This key toggles whether CloudCannon will display a dropdown menu tool in your WYSIWYG toolbar for structured text.
Setting this key to true will enable a dropdown menu tool in your WYSIWYG toolbar for structured text. Valid values include for p, h1, h2, h3, h4, h5, h6, pre, address, and div. Include a space between each values, e.g. format: p h1 h2.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a horizontal line.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a horizontal line.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an image and enter alternative text and title text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an image. Select an existing image, upload an image, or use an external link.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to increase the indentation of a list item in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to increase the indentation of a list item.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to justify selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to justify selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to left align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to left align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an ordered list or convert selected text to an ordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an ordered list or convert selected text to an ordered list.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to decrease the indentation of a list item in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to decrease the indentation of a list item.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to right align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to right align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a Snippet, if any are available.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a Snippet.
This key toggles whether CloudCannon will display a dropdown menu in your WYSIWYG toolbar to apply a style to selected text.
Examples
In this example, we have enabled a dropdown menu in our WYSIWYG toolbar to apply a style to selected text. The styles are defined in the /css/styles.css file.
_editables:
content:
styles: /css/styles.css
This example file defines the styles that CloudCannon can add to your WYSIWYG toolbar.
/* Can be applied to blocks of content */
p.callout {
margin: 10px;
border: 1px solid #f5f5f5;
background-color: #eee;
}
/* Can be applied to inline content */
span.big-blue-text {
font-size: 2rem;
color: blue;
}
/* Applied to content, excluded from style dropdown */
h2 {
font-family: cursive;
}
/* Applied to content, excluded from style dropdown */
.align-left { text-align: left; }
.align-center { text-align: center; }
.align-right { text-align: right; }
.align-justify { text-align: justify; }
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a table.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a table. Further table options are available from the table context menu in the rich text editor.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to merge a list item with the item above it in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to merge a list item with the item above it.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to merge a list item with the item below it in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to merge a list item with the item below it.
This key defines the maximum string length, in characters, that CloudCannon will allow in an Input.
When configured, CloudCannon will warn you when an Input value is too long.
If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
Value can be any non-negative integer.
If this key is set to 0, CloudCannon requires the Input to be empty.
If options.min_length is also configured, this key cannot be a smaller number.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to enter a blog description using the Rich Text seo_description Input. This Input limits you to a maximum of 125 characters.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
min_length: 25
This key defines a custom error message that explains why a value has failed the validation criteria from options.max_length.
This key requires you to define options.max_length.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to enter a valid number of characters using a custom message.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
max_length_message: You are only allowed 125 characters.
min_length: 25
min_length_message: Please write more than 25 characters.
This key defines the minimum string length, in characters, that CloudCannon will allow in an Input.
When configured, CloudCannon will warn you when an Input value is too short.
If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
Value can be any positive integer.
If options.max_length is also configured, this key cannot be a greater number.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to enter a blog description using the Rich Text seo_description Input. This Input requires a minimum of 25 characters.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
min_length: 25
This key defines a custom error message that explains why a value has failed the validation criteria from options.min_length.
This key requires you to define options.min_length.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to enter a valid number of characters using a custom message.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
max_length_message: You are only allowed 125 characters.
min_length: 25
min_length_message: Please write more than 25 characters.
This key defines the maximum string length, in words, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which maximum string length an Input will accept. This key requires you to define `options.max_words.
This key defines the minimum string length, in words, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which minimum string length an Input will accept. This key requires you to define options.min_words.
This key defines the maximum string length, in graphemes, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which maximum string length an Input will accept. This key requires you to define `options.max_graphemes.
This key defines the minimum string length, in graphemes, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which minimum string length an Input will accept. This key requires you to define options.min_graphemes.
This key defines the locale that CloudCannon uses to determine the number of words or graphemes in this Input, if you have max_words, min_words, max_graphemes, or min_graphemes configured.
This key defines a regular expression that the Input value must match.
When configured, CloudCannon will require you to enter a value that matches the REGEX pattern.
If the Input already contains an invalid value, CloudCannon will require you to enter a valid string to save your changes, or discard your unsaved changes.
Value must be a valid REGEX string.
If your REGEX string includes a \ character and CloudCannon Configuration File is a .yml file, use single quotes ' around the string to avoid a
build error.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to add an email address to the contact_email Input using the correct email format.
_inputs:
contact_email:
type: email
options:
pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
pattern_message: 'Please use the format ___@___.__'
This key defines a custom error message that explains why a value has failed the validation criteria from options.pattern.
This key requires you to define options.pattern.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to use the correct email format in the contact_email Input using a pattern message.
_inputs:
contact_email:
type: email
options:
pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
pattern_message: 'Please use the format ___@___.__'
This key defines the flags (e.g. case-insensitive searching) for the regular expression set in options.pattern.
Examples
In this example, we have configured pattern flags for a text input to enable case-insensitive searching.
_inputs:
search_term:
type: text
options:
pattern: "^[a-z]+$"
pattern_flags:
ignore_case: true
6 nested properties
This key defines the g flag - Search globally.
This key defines the i flag - Case-insensitive.
This key defines the m flag - ^ and $ match the start and end of each line rather than the entire string.
This key defines the s flag - . matches newline characters.
This key defines the u flag - Pattern is treated as a sequence of Unicode code points.
This key defines the v flag for extended unicode mode.
This key toggles whether CloudCannon requires this Input to have a value.
Setting this key to true will require you to enter a value to save your changes, or discard your unsaved changes.
By default, this key is false (i.e., CloudCannon does not require this Input to have a value).
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we want to require our team to enter an author value for markup files with this Input.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
This key defines a custom error message that explains why a value has failed the validation criteria from options.required.
This key requires you to define options.required.
This key has no default.
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to use enter an Input value using a required message.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
required_message: You are not allowed to leave this blank.
This key is deprecated. Use preview_resize instead.
This key toggles whether CloudCannon will show the resize handler to vertically resize the input.
Setting this key to false will hide the resize handler.
By default, this key is true (i.e., the resize handler is shown).
Shows or hides the resize handler to vertically resize the input.
This key defines the initial height of this input in pixels (px).
This key defines what format an image is converted to prior to upload.
Examples
In this example, we have configured an Image Input to convert images to WebP format prior to upload.
_inputs:
hero_image:
type: image
options:
mime_type: image/webp
This key defines how image files are resized prior to upload, using a bounding box defined by width and height options.
Valid values are cover, contain, crop, or stretch:
coverkeeps aspect ratio and ensures the image covers the bounding boxcontainkeeps aspect ratio and ensures the image fits inside the bounding boxcropprompts the user with and interface to select an aspect-ratio-respecting areastretchignores aspect ratio and resizes the image to the bounding box
This key does not apply to existing images, and does not work if width and height options are not defined.
Examples
In this example, we have configured an Image Input to resize images using the cover style to ensure images cover the bounding box while maintaining aspect ratio.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines the width of the bounding box used in the resizing method defined by resize_style.
This key defines the height of the bounding box used in the resizing method defined by resize_style.
Examples
In this example, we have configured the height of the bounding box for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines whether you can upscale an image to fit the bounding box while resizing an image prior to upload.
Has no effect if files are not resized.
Examples
In this example, we have configured an Image Input to allow upscaling images to fit the bounding box while resizing.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
expandable: true
This key toggles whether CloudCannon will instruct a rich text editor to save width and height attributes on image elements.
Setting this key to true will instruct the rich text editor to save width and height attributes on image elements. This can prevent pop-in as a page loads.
By default, this key is false (i.e., width and height attributes are not saved on image elements). This defaults to true if the Image Size Attributes site flag is enabled (this is enabled for sites created before June 23 2023, in order to keep those sites working).
Examples
In this example, CloudCannon will save width and height attributes on image elements in a Rich Text Input.
_inputs:
content:
type: markdown
options:
image_size_attributes: true
This key defines which sources and DAMs you are allowed to upload to and browse.
The value can be an array of strings. Valid values include site-files and the reference key for any DAM connected to your site.
If site-files is omitted from the array, site files will not be available as an asset source for this input.
Examples
In this example, we have configured allowed sources for an Image Input.
_inputs:
image:
type: image
options:
allowed_sources:
- site-files
- my-cloudinary-dam
This key toggles whether CloudCannon will skip the image resizing process configured for this input when selecting existing images.
Setting this key to true will skip the image resizing process when selecting existing images.
Examples
In this example, CloudCannon will skip the image resizing process when selecting existing images for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
prevent_resize_existing_files: true
This key defines definitions for creating additional images of different sizes when uploading or selecting existing files.
Examples
In this example, we have configured an Image Input to create additional images of different sizes when uploading or selecting files.
_inputs:
hero_image:
type: image
options:
sizes:
- size: 2x
- size: 3x
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to bold selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to bold selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to copy formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to copy formatting from selected text. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not copy other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to italicize selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to italicize selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to redo recent edits undone with undo.
Setting this key to true will enable a tool in your WYSIWYG toolbar to redo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to remove formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to remove formatting. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not remove other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to strike through selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to strike through selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to subscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to subscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to superscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to superscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to underline selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to underline selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to undo recent edits.
Setting this key to true will enable a tool in your WYSIWYG toolbar to undo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will allow you to strip custom markup from content edited in a rich text editor, allowing you to clean files of unnecessary HTML content.
Setting this key to true will enable stripping custom markup from content. The remove_custom_markup key is disabled if allow_custom_markup is enabled.
This key toggles whether CloudCannon will allow you to edit custom markup in rich text editors and explicitly accept the risk of unintentionally deleting elements that cannot be recreated.
Setting this key to true will enable editing of custom markup. When using allow_custom_markup outside of editable regions, content that uses JavaScript will not be editable for security reasons. These inputs will appear as uneditable snippets.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to wrap selected blocks of text in a block quote.
Setting this key to true will enable a tool in your WYSIWYG toolbar to wrap selected blocks of text in a block quote.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an unordered list or convert selected text to an unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an unordered list or convert selected text to an unordered list.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to center align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to center align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a control in your WYSIWYG toolbar to create an inline code element, containing any selected text.
Setting this key to true will enable a control in your WYSIWYG toolbar to create an inline code element.
By default, this key is false (i.e., the inline code control is not displayed).
This key toggles whether CloudCannon will display a control in your WYSIWYG toolbar to insert a code block in editable regions.
Setting this key to true will enable a control in your WYSIWYG toolbar to insert a code block.
By default, this key is false (i.e., the code block control is not displayed).
This key toggles whether CloudCannon will display tools in your WYSIWYG toolbar to turn selected text into inline code and selected text into a code block.
Setting this key to true will enable two tools in your WYSIWYG toolbar to turn selected text into inline code and selected text into a code block.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a region of raw HTML for YouTube, Vimeo, social media posts, or other media.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a region of raw HTML. Embedded content is sanitized to mitigate XSS risks, which includes removing style tags. Embeds containing script tags are not loaded a rich text editor.
This key toggles whether CloudCannon will display a dropdown menu tool in your WYSIWYG toolbar for structured text.
Setting this key to true will enable a dropdown menu tool in your WYSIWYG toolbar for structured text. Valid values include for p, h1, h2, h3, h4, h5, h6, pre, address, and div. Include a space between each values, e.g. format: p h1 h2.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a horizontal line.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a horizontal line.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an image and enter alternative text and title text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an image. Select an existing image, upload an image, or use an external link.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to increase the indentation of a list item in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to increase the indentation of a list item.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to justify selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to justify selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to left align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to left align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an ordered list or convert selected text to an ordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an ordered list or convert selected text to an ordered list.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to decrease the indentation of a list item in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to decrease the indentation of a list item.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to right align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to right align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a Snippet, if any are available.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a Snippet.
This key toggles whether CloudCannon will display a dropdown menu in your WYSIWYG toolbar to apply a style to selected text.
Examples
In this example, we have enabled a dropdown menu in our WYSIWYG toolbar to apply a style to selected text. The styles are defined in the /css/styles.css file.
_editables:
content:
styles: /css/styles.css
This example file defines the styles that CloudCannon can add to your WYSIWYG toolbar.
/* Can be applied to blocks of content */
p.callout {
margin: 10px;
border: 1px solid #f5f5f5;
background-color: #eee;
}
/* Can be applied to inline content */
span.big-blue-text {
font-size: 2rem;
color: blue;
}
/* Applied to content, excluded from style dropdown */
h2 {
font-family: cursive;
}
/* Applied to content, excluded from style dropdown */
.align-left { text-align: left; }
.align-center { text-align: center; }
.align-right { text-align: right; }
.align-justify { text-align: justify; }
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a table.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a table. Further table options are available from the table context menu in the rich text editor.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to merge a list item with the item above it in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to merge a list item with the item above it.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to merge a list item with the item below it in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to merge a list item with the item below it.
This key defines an editing interface for date and/or time values.
This key defines the input type, which controls how this input appears and behaves.
This key defines the subtitle text above an Input.
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.
Examples
In this example, we want to add helpful guidance for our page_description Input.
_inputs:
page_description:
type: text
label: Page Description
comment: Enter a brief description of this page for search engines
Provides a custom link for documentation for editors shown above input.
This key defines the bold title text above an Input.
Examples
In this example, we want to customize the label for our page_title Input to be more descriptive.
_inputs:
page_title:
type: text
label: Article Title
comment: Enter the main title for this article
This key defines the visibility of an input in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Hidden inputs are useful when you want an input to exist, but not be visible or editable outside of the Source Editor.
Value can be a boolean or a string. A boolean value of true will hide the input.
A string value can hide an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key follows the input naming convention where key names beginning with an underscore are hidden true.
This key defines whether the value of an input is editable in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Disabled inputs are useful if you want CloudCannon to display the input value, but prevent team members from editing the value outside of the Source Editor.
The value of this key can be a boolean or a string. A boolean value of true will prevent team members from editing the value.
A string value can prevent team members from editing an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key is false (i.e., team members can edit input values).
Examples
In this example, we have configured the date_created Date 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
disabled: true
instance_value: NOW
options:
timezone: Etc/UTC
This key defines whether an input is automatically populated with a value when the input is created.
This occurs when creating a new file, or adding array items containing this input.
Valid values are UUID or NOW.
UUIDgenerates a uuidv4 key (extremely unlikely to generate duplicates), useful for identifying unique items (e.g.6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b)NOWgenerates the current datetime in the Site's configured timezone
Examples
In this example, we have configured an input to automatically populate with a UUID when created.
_inputs:
id:
type: text
instance_value: UUID
This key toggles whether CloudCannon will rehydrate inputs configured with an instance_value with a new value when duplicated.
Setting this key to true will prevent rehydration of instance values when inputs are duplicated.
Examples
In this example, CloudCannon will prevent rehydration of instance values when inputs are duplicated.
_inputs:
id:
type: text
instance_value: UUID
disable_instance_value_rehydration: true
This key defines whether CloudCannon should merge this input configuration with any matching, less specific configurations elsewhere in the configuration cascade.
The configuration cascade works by finding the most specific _inputs entry.
Usually, once an option is found in the cascade, there's no reason to keep looking.
When this key is true, the cascade continues looking and each entry found is merged.
This key allows you to define some options globally while using specific options for other keys at different levels of the cascade.
For example, define a comment globally, but use collection-specific label for inputs in different collections.
You can stop the cascade at any point in the configuration cascade by setting cascade to false.
Examples
In this example, we have configured cascade to merge input configurations across the configuration cascade.
_inputs:
title:
type: text
cascade: true
comment: Global comment for all title inputs
This key defines options that are specific to Date Inputs.
8 nested properties
This key toggles whether CloudCannon requires this Input to have a value.
Setting this key to true will require you to enter a value to save your changes, or discard your unsaved changes.
By default, this key is false (i.e., CloudCannon does not require this Input to have a value).
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we want to require our team to enter an author value for markup files with this Input.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
This key defines a custom error message that explains why a value has failed the validation criteria from options.required.
This key requires you to define options.required.
This key has no default.
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to use enter an Input value using a required message.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
required_message: You are not allowed to leave this blank.
Specifies the time zone that dates are displayed and edited in. Also changes the suffix the date is persisted to the file with. Defaults to the global timezone.
This key defines the earliest date and time, inclusive, that CloudCannon will allow in an Input.
When configured, CloudCannon will prevent you from selecting an earlier date and time.
If the Input already contains an earlier date and time, CloudCannon will require you to change it to a valid value to save your changes, or discard your unsaved changes.
Value must be in ISO8601 format.
The value can have quotation marks or no quotation marks.
If options.end_before is also configured, this key cannot be a later date and time.
This key has no default.
This key is available for Date and Time Inputs.
Examples
In this example, we want our team to enter the date and time of an event in the 2022_event Input. This Input will only allow dates on or after January 1st, 2022.
_inputs:
2022_event:
type: datetime
options:
start_from: 2022-01-01T00:00:00Z
end_before: 2023-01-01T00:00:00Z
This key defines a custom error message that explains why a value has failed the validation criteria from options.start_from.
This key requires you to define options.start_from.
This key has no default.
This key is available for Date and Time Inputs.
Examples
In this example, we prompt our team to enter a valid date using a custom message.
_inputs:
2022_event:
type: datetime
options:
start_from: 2022-01-01T00:00:00Z
start_from_message: Date is too early. Must be during 2022.
end_before: 2023-01-01T00:00:00Z
end_before_message: Date is too late. Must be during 2022.
This key defines the date and time, exclusive, that CloudCannon will allow in an Input.
When configured, CloudCannon will prevent you from selecting a later date and time.
If the Input already contains a later date and time, CloudCannon will require you to change it to a valid value to save your changes, or discard your unsaved changes.
Value must be in ISO8601 format.
The value can have quotation marks or no quotation marks.
If options.start_from is also configured, this key cannot be an earlier date and time.
This key has no default.
This key is available for Date and Time Inputs.
Examples
In this example, we want our team to enter the date and time of an event in the 2022_event Input. This Input will only allow dates before January 1st, 2023.
_inputs:
2022_event:
type: datetime
options:
start_from: 2022-01-01T00:00:00Z
end_before: 2023-01-01T00:00:00Z
This key defines a custom error message that explains why a value has failed the validation criteria from options.end_before.
This key requires you to define options.end_before.
This key has no default.
This key is available for Date and Time Inputs.
Examples
In this example, we prompt our team to enter a valid date using a custom message.
_inputs:
2022_event:
type: datetime
options:
start_from: 2022-01-01T00:00:00Z
start_from_message: Date is too early. Must be during 2022.
end_before: 2023-01-01T00:00:00Z
end_before_message: Date is too late. Must be during 2022.
This key defines the timezone for your Site.
Value must be in IANA timezone format.
For more information, please read our documentation on Date and Time inputs.
This key defines an editing interface for time values only.
This key defines the input type, which controls how this input appears and behaves.
This key defines the subtitle text above an Input.
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.
Examples
In this example, we want to add helpful guidance for our page_description Input.
_inputs:
page_description:
type: text
label: Page Description
comment: Enter a brief description of this page for search engines
Provides a custom link for documentation for editors shown above input.
This key defines the bold title text above an Input.
Examples
In this example, we want to customize the label for our page_title Input to be more descriptive.
_inputs:
page_title:
type: text
label: Article Title
comment: Enter the main title for this article
This key defines the visibility of an input in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Hidden inputs are useful when you want an input to exist, but not be visible or editable outside of the Source Editor.
Value can be a boolean or a string. A boolean value of true will hide the input.
A string value can hide an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key follows the input naming convention where key names beginning with an underscore are hidden true.
This key defines whether the value of an input is editable in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Disabled inputs are useful if you want CloudCannon to display the input value, but prevent team members from editing the value outside of the Source Editor.
The value of this key can be a boolean or a string. A boolean value of true will prevent team members from editing the value.
A string value can prevent team members from editing an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key is false (i.e., team members can edit input values).
Examples
In this example, we have configured the date_created Date 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
disabled: true
instance_value: NOW
options:
timezone: Etc/UTC
This key defines whether an input is automatically populated with a value when the input is created.
This occurs when creating a new file, or adding array items containing this input.
Valid values are UUID or NOW.
UUIDgenerates a uuidv4 key (extremely unlikely to generate duplicates), useful for identifying unique items (e.g.6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b)NOWgenerates the current datetime in the Site's configured timezone
Examples
In this example, we have configured an input to automatically populate with a UUID when created.
_inputs:
id:
type: text
instance_value: UUID
This key toggles whether CloudCannon will rehydrate inputs configured with an instance_value with a new value when duplicated.
Setting this key to true will prevent rehydration of instance values when inputs are duplicated.
Examples
In this example, CloudCannon will prevent rehydration of instance values when inputs are duplicated.
_inputs:
id:
type: text
instance_value: UUID
disable_instance_value_rehydration: true
This key defines whether CloudCannon should merge this input configuration with any matching, less specific configurations elsewhere in the configuration cascade.
The configuration cascade works by finding the most specific _inputs entry.
Usually, once an option is found in the cascade, there's no reason to keep looking.
When this key is true, the cascade continues looking and each entry found is merged.
This key allows you to define some options globally while using specific options for other keys at different levels of the cascade.
For example, define a comment globally, but use collection-specific label for inputs in different collections.
You can stop the cascade at any point in the configuration cascade by setting cascade to false.
Examples
In this example, we have configured cascade to merge input configurations across the configuration cascade.
_inputs:
title:
type: text
cascade: true
comment: Global comment for all title inputs
This key defines options that are specific to Time Inputs.
3 nested properties
This key toggles whether CloudCannon requires this Input to have a value.
Setting this key to true will require you to enter a value to save your changes, or discard your unsaved changes.
By default, this key is false (i.e., CloudCannon does not require this Input to have a value).
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we want to require our team to enter an author value for markup files with this Input.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
This key defines a custom error message that explains why a value has failed the validation criteria from options.required.
This key requires you to define options.required.
This key has no default.
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to use enter an Input value using a required message.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
required_message: You are not allowed to leave this blank.
This key defines an editing interface for uploading files to your repository or DAM and browsing existing assets.
This key defines the input type, which controls how this input appears and behaves.
This key defines the subtitle text above an Input.
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.
Examples
In this example, we want to add helpful guidance for our page_description Input.
_inputs:
page_description:
type: text
label: Page Description
comment: Enter a brief description of this page for search engines
Provides a custom link for documentation for editors shown above input.
This key defines the bold title text above an Input.
Examples
In this example, we want to customize the label for our page_title Input to be more descriptive.
_inputs:
page_title:
type: text
label: Article Title
comment: Enter the main title for this article
This key defines the visibility of an input in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Hidden inputs are useful when you want an input to exist, but not be visible or editable outside of the Source Editor.
Value can be a boolean or a string. A boolean value of true will hide the input.
A string value can hide an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key follows the input naming convention where key names beginning with an underscore are hidden true.
This key defines whether the value of an input is editable in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Disabled inputs are useful if you want CloudCannon to display the input value, but prevent team members from editing the value outside of the Source Editor.
The value of this key can be a boolean or a string. A boolean value of true will prevent team members from editing the value.
A string value can prevent team members from editing an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key is false (i.e., team members can edit input values).
Examples
In this example, we have configured the date_created Date 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
disabled: true
instance_value: NOW
options:
timezone: Etc/UTC
This key defines whether an input is automatically populated with a value when the input is created.
This occurs when creating a new file, or adding array items containing this input.
Valid values are UUID or NOW.
UUIDgenerates a uuidv4 key (extremely unlikely to generate duplicates), useful for identifying unique items (e.g.6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b)NOWgenerates the current datetime in the Site's configured timezone
Examples
In this example, we have configured an input to automatically populate with a UUID when created.
_inputs:
id:
type: text
instance_value: UUID
This key toggles whether CloudCannon will rehydrate inputs configured with an instance_value with a new value when duplicated.
Setting this key to true will prevent rehydration of instance values when inputs are duplicated.
Examples
In this example, CloudCannon will prevent rehydration of instance values when inputs are duplicated.
_inputs:
id:
type: text
instance_value: UUID
disable_instance_value_rehydration: true
This key defines whether CloudCannon should merge this input configuration with any matching, less specific configurations elsewhere in the configuration cascade.
The configuration cascade works by finding the most specific _inputs entry.
Usually, once an option is found in the cascade, there's no reason to keep looking.
When this key is true, the cascade continues looking and each entry found is merged.
This key allows you to define some options globally while using specific options for other keys at different levels of the cascade.
For example, define a comment globally, but use collection-specific label for inputs in different collections.
You can stop the cascade at any point in the configuration cascade by setting cascade to false.
Examples
In this example, we have configured cascade to merge input configurations across the configuration cascade.
_inputs:
title:
type: text
cascade: true
comment: Global comment for all title inputs
This key defines options that are specific to File Inputs.
35 nested properties
This key defines what format an image is converted to prior to upload.
Examples
In this example, we have configured an Image Input to convert images to WebP format prior to upload.
_inputs:
hero_image:
type: image
options:
mime_type: image/webp
This key defines how image files are resized prior to upload, using a bounding box defined by width and height options.
Valid values are cover, contain, crop, or stretch:
coverkeeps aspect ratio and ensures the image covers the bounding boxcontainkeeps aspect ratio and ensures the image fits inside the bounding boxcropprompts the user with and interface to select an aspect-ratio-respecting areastretchignores aspect ratio and resizes the image to the bounding box
This key does not apply to existing images, and does not work if width and height options are not defined.
Examples
In this example, we have configured an Image Input to resize images using the cover style to ensure images cover the bounding box while maintaining aspect ratio.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines the width of the bounding box used in the resizing method defined by resize_style.
This key defines the height of the bounding box used in the resizing method defined by resize_style.
Examples
In this example, we have configured the height of the bounding box for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines whether you can upscale an image to fit the bounding box while resizing an image prior to upload.
Has no effect if files are not resized.
Examples
In this example, we have configured an Image Input to allow upscaling images to fit the bounding box while resizing.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
expandable: true
This key toggles whether CloudCannon will instruct a rich text editor to save width and height attributes on image elements.
Setting this key to true will instruct the rich text editor to save width and height attributes on image elements. This can prevent pop-in as a page loads.
By default, this key is false (i.e., width and height attributes are not saved on image elements). This defaults to true if the Image Size Attributes site flag is enabled (this is enabled for sites created before June 23 2023, in order to keep those sites working).
Examples
In this example, CloudCannon will save width and height attributes on image elements in a Rich Text Input.
_inputs:
content:
type: markdown
options:
image_size_attributes: true
This key defines which sources and DAMs you are allowed to upload to and browse.
The value can be an array of strings. Valid values include site-files and the reference key for any DAM connected to your site.
If site-files is omitted from the array, site files will not be available as an asset source for this input.
Examples
In this example, we have configured allowed sources for an Image Input.
_inputs:
image:
type: image
options:
allowed_sources:
- site-files
- my-cloudinary-dam
This key toggles whether CloudCannon will skip the image resizing process configured for this input when selecting existing images.
Setting this key to true will skip the image resizing process when selecting existing images.
Examples
In this example, CloudCannon will skip the image resizing process when selecting existing images for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
prevent_resize_existing_files: true
This key defines definitions for creating additional images of different sizes when uploading or selecting existing files.
Examples
In this example, we have configured an Image Input to create additional images of different sizes when uploading or selecting files.
_inputs:
hero_image:
type: image
options:
sizes:
- size: 2x
- size: 3x
This key defines the maximum string length, in characters, that CloudCannon will allow in an Input.
When configured, CloudCannon will warn you when an Input value is too long.
If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
Value can be any non-negative integer.
If this key is set to 0, CloudCannon requires the Input to be empty.
If options.min_length is also configured, this key cannot be a smaller number.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to enter a blog description using the Rich Text seo_description Input. This Input limits you to a maximum of 125 characters.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
min_length: 25
This key defines a custom error message that explains why a value has failed the validation criteria from options.max_length.
This key requires you to define options.max_length.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to enter a valid number of characters using a custom message.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
max_length_message: You are only allowed 125 characters.
min_length: 25
min_length_message: Please write more than 25 characters.
This key defines the minimum string length, in characters, that CloudCannon will allow in an Input.
When configured, CloudCannon will warn you when an Input value is too short.
If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
Value can be any positive integer.
If options.max_length is also configured, this key cannot be a greater number.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to enter a blog description using the Rich Text seo_description Input. This Input requires a minimum of 25 characters.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
min_length: 25
This key defines a custom error message that explains why a value has failed the validation criteria from options.min_length.
This key requires you to define options.min_length.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to enter a valid number of characters using a custom message.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
max_length_message: You are only allowed 125 characters.
min_length: 25
min_length_message: Please write more than 25 characters.
This key defines the maximum string length, in words, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which maximum string length an Input will accept. This key requires you to define `options.max_words.
This key defines the minimum string length, in words, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which minimum string length an Input will accept. This key requires you to define options.min_words.
This key defines the maximum string length, in graphemes, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which maximum string length an Input will accept. This key requires you to define `options.max_graphemes.
This key defines the minimum string length, in graphemes, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which minimum string length an Input will accept. This key requires you to define options.min_graphemes.
This key defines the locale that CloudCannon uses to determine the number of words or graphemes in this Input, if you have max_words, min_words, max_graphemes, or min_graphemes configured.
This key defines a regular expression that the Input value must match.
When configured, CloudCannon will require you to enter a value that matches the REGEX pattern.
If the Input already contains an invalid value, CloudCannon will require you to enter a valid string to save your changes, or discard your unsaved changes.
Value must be a valid REGEX string.
If your REGEX string includes a \ character and CloudCannon Configuration File is a .yml file, use single quotes ' around the string to avoid a
build error.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to add an email address to the contact_email Input using the correct email format.
_inputs:
contact_email:
type: email
options:
pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
pattern_message: 'Please use the format ___@___.__'
This key defines a custom error message that explains why a value has failed the validation criteria from options.pattern.
This key requires you to define options.pattern.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to use the correct email format in the contact_email Input using a pattern message.
_inputs:
contact_email:
type: email
options:
pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
pattern_message: 'Please use the format ___@___.__'
This key defines the flags (e.g. case-insensitive searching) for the regular expression set in options.pattern.
Examples
In this example, we have configured pattern flags for a text input to enable case-insensitive searching.
_inputs:
search_term:
type: text
options:
pattern: "^[a-z]+$"
pattern_flags:
ignore_case: true
6 nested properties
This key defines the g flag - Search globally.
This key defines the i flag - Case-insensitive.
This key defines the m flag - ^ and $ match the start and end of each line rather than the entire string.
This key defines the s flag - . matches newline characters.
This key defines the u flag - Pattern is treated as a sequence of Unicode code points.
This key defines the v flag for extended unicode mode.
This key toggles whether CloudCannon requires this Input to have a value.
Setting this key to true will require you to enter a value to save your changes, or discard your unsaved changes.
By default, this key is false (i.e., CloudCannon does not require this Input to have a value).
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we want to require our team to enter an author value for markup files with this Input.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
This key defines a custom error message that explains why a value has failed the validation criteria from options.required.
This key requires you to define options.required.
This key has no default.
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to use enter an Input value using a required message.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
required_message: You are not allowed to leave this blank.
This key defines which file types are available to select or upload to this input.
Accepted format is an array or comma-separated string of MIME types.
The special value "*" means any type is accepted.
Examples
In this example, we have configured a Image Input to accept only JPEG or PNG files.
_inputs:
featured_image:
type: image
options:
accepts_mime_types:
- image/jpeg
- image/png
This key defines the maximum file size in kB that CloudCannon will allow you to upload.
When configured, CloudCannon will prevent you from saving your changes until you select a valid file size, or discard your unsaved changes.
Value can be any positive integer.
This key has no default.
This key is available for File and URL Inputs.
Examples
In this example, we want our team to upload an image using the feature_image Input. This Input limits you to a maximum file size of 750 kB.
_inputs:
feature_image:
type: image
comment: Select the feature image for the banner.
options:
max_file_size: 140
This key defines a custom error message that explains why a value has failed the validation criteria from options.max_file_size.
This key requires you to define options.max_file_size.
This key has no default.
This key is available for File and URL Inputs.
Examples
In this example, we want our team to upload an image using the feature_image Input. This Input limits you to a maximum file size of 750 kB.
_inputs:
feature_image:
type: image
comment: Select the feature image for the banner.
options:
max_file_size: 140
max_file_size_message: For SEO, keep this under 140kB
This key toggles whether CloudCannon will disable the context menu option and the drop area for uploading files.
Setting this key to true will disable the context menu option and prevent uploading file through drag-and-drop in a File Input.
Examples
In this example, CloudCannon will disable the option to upload a file in the context menu and prevent uploading file through drag-and-drop in a File Input.
_inputs:
image:
type: image
options:
disable_upload_file: true
This key toggles whether CloudCannon will prevent typing into the Text Input, while still allowing context menu options to change the value.
Setting this key to true will prevent typing into the Text Input.
Examples
In this example, CloudCannon will prevent typing into the Text Input url.
_inputs:
url:
type: url
options:
disable_direct_input: true
This key toggles whether CloudCannon will prevent file uploads inside the "Select existing file/image" file browser modal window.
Setting this key to true will prevent file uploads inside the file browser modal window.
Examples
In this example, CloudCannon will disable the option to upload files inside the file browser modal window.
_inputs:
image:
type: file
options:
disable_upload_file_in_file_browser: true
This key defines which file types are available to select or upload to this input.
Accepted format is an array or comma-separated string of MIME types.
The special value "*" means any type is accepted.
Examples
In this example, we have configured a Image Input to accept only JPEG or PNG files.
_inputs:
featured_image:
type: image
options:
accepts_mime_types:
- image/jpeg
- image/png
This key represents an array format for the accepts_mime_types key that restricts which file types are available to select or upload in File Inputs.
The value is an array of MIME type strings. Each string specifies a file type that CloudCannon will allow for this input.
Available MIME types include image formats (image/x-icon, image/gif, image/jpeg, image/png, image/webp, image/bmp, image/svg+xml) and document formats (application/pdf, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-powerpoint, application/vnd.openxmlformats-officedocument.presentationml.presentation).
Use the array format when you want to explicitly list multiple MIME types, making it easier to read and maintain in your configuration.
Examples
In this example, we have configured a File Input to accept only image files using an array of image MIME types.
_inputs:
hero_image:
type: file
label: Hero Image
options:
accepts_mime_types:
- image/jpeg
- image/png
- image/webp
In this example, we have configured a File Input to accept only document files using an array of document MIME types.
_inputs:
document:
type: file
label: Document
options:
accepts_mime_types:
- application/pdf
- application/msword
- application/vnd.openxmlformats-officedocument.wordprocessingml.document
This key defines the maximum file size in kB that CloudCannon will allow you to upload.
When configured, CloudCannon will prevent you from saving your changes until you select a valid file size, or discard your unsaved changes.
Value can be any positive integer.
This key has no default.
This key is available for File and URL Inputs.
Examples
In this example, we want our team to upload an image using the feature_image Input. This Input limits you to a maximum file size of 750 kB.
_inputs:
feature_image:
type: image
comment: Select the feature image for the banner.
options:
max_file_size: 140
This key defines a custom error message that explains why a value has failed the validation criteria from options.max_file_size.
This key requires you to define options.max_file_size.
This key has no default.
This key is available for File and URL Inputs.
Examples
In this example, we want our team to upload an image using the feature_image Input. This Input limits you to a maximum file size of 750 kB.
_inputs:
feature_image:
type: image
comment: Select the feature image for the banner.
options:
max_file_size: 140
max_file_size_message: For SEO, keep this under 140kB
This key toggles whether CloudCannon will disable the context menu option and the drop area for uploading files.
Setting this key to true will disable the context menu option and prevent uploading file through drag-and-drop in a File Input.
Examples
In this example, CloudCannon will disable the option to upload a file in the context menu and prevent uploading file through drag-and-drop in a File Input.
_inputs:
image:
type: image
options:
disable_upload_file: true
This key toggles whether CloudCannon will prevent typing into the Text Input, while still allowing context menu options to change the value.
Setting this key to true will prevent typing into the Text Input.
Examples
In this example, CloudCannon will prevent typing into the Text Input url.
_inputs:
url:
type: url
options:
disable_direct_input: true
This key toggles whether CloudCannon will prevent file uploads inside the "Select existing file/image" file browser modal window.
Setting this key to true will prevent file uploads inside the file browser modal window.
Examples
In this example, CloudCannon will disable the option to upload files inside the file browser modal window.
_inputs:
image:
type: file
options:
disable_upload_file_in_file_browser: true
This key defines an editing interface for relative, absolute, and fully qualified URLs.
This key defines the input type, which controls how this input appears and behaves.
This key defines the subtitle text above an Input.
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.
Examples
In this example, we want to add helpful guidance for our page_description Input.
_inputs:
page_description:
type: text
label: Page Description
comment: Enter a brief description of this page for search engines
Provides a custom link for documentation for editors shown above input.
This key defines the bold title text above an Input.
Examples
In this example, we want to customize the label for our page_title Input to be more descriptive.
_inputs:
page_title:
type: text
label: Article Title
comment: Enter the main title for this article
This key defines the visibility of an input in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Hidden inputs are useful when you want an input to exist, but not be visible or editable outside of the Source Editor.
Value can be a boolean or a string. A boolean value of true will hide the input.
A string value can hide an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key follows the input naming convention where key names beginning with an underscore are hidden true.
This key defines whether the value of an input is editable in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Disabled inputs are useful if you want CloudCannon to display the input value, but prevent team members from editing the value outside of the Source Editor.
The value of this key can be a boolean or a string. A boolean value of true will prevent team members from editing the value.
A string value can prevent team members from editing an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key is false (i.e., team members can edit input values).
Examples
In this example, we have configured the date_created Date 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
disabled: true
instance_value: NOW
options:
timezone: Etc/UTC
This key defines whether an input is automatically populated with a value when the input is created.
This occurs when creating a new file, or adding array items containing this input.
Valid values are UUID or NOW.
UUIDgenerates a uuidv4 key (extremely unlikely to generate duplicates), useful for identifying unique items (e.g.6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b)NOWgenerates the current datetime in the Site's configured timezone
Examples
In this example, we have configured an input to automatically populate with a UUID when created.
_inputs:
id:
type: text
instance_value: UUID
This key toggles whether CloudCannon will rehydrate inputs configured with an instance_value with a new value when duplicated.
Setting this key to true will prevent rehydration of instance values when inputs are duplicated.
Examples
In this example, CloudCannon will prevent rehydration of instance values when inputs are duplicated.
_inputs:
id:
type: text
instance_value: UUID
disable_instance_value_rehydration: true
This key defines whether CloudCannon should merge this input configuration with any matching, less specific configurations elsewhere in the configuration cascade.
The configuration cascade works by finding the most specific _inputs entry.
Usually, once an option is found in the cascade, there's no reason to keep looking.
When this key is true, the cascade continues looking and each entry found is merged.
This key allows you to define some options globally while using specific options for other keys at different levels of the cascade.
For example, define a comment globally, but use collection-specific label for inputs in different collections.
You can stop the cascade at any point in the configuration cascade by setting cascade to false.
Examples
In this example, we have configured cascade to merge input configurations across the configuration cascade.
_inputs:
title:
type: text
cascade: true
comment: Global comment for all title inputs
This key defines options that are specific to URL Inputs.
39 nested properties
This key defines what format an image is converted to prior to upload.
Examples
In this example, we have configured an Image Input to convert images to WebP format prior to upload.
_inputs:
hero_image:
type: image
options:
mime_type: image/webp
This key defines how image files are resized prior to upload, using a bounding box defined by width and height options.
Valid values are cover, contain, crop, or stretch:
coverkeeps aspect ratio and ensures the image covers the bounding boxcontainkeeps aspect ratio and ensures the image fits inside the bounding boxcropprompts the user with and interface to select an aspect-ratio-respecting areastretchignores aspect ratio and resizes the image to the bounding box
This key does not apply to existing images, and does not work if width and height options are not defined.
Examples
In this example, we have configured an Image Input to resize images using the cover style to ensure images cover the bounding box while maintaining aspect ratio.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines the width of the bounding box used in the resizing method defined by resize_style.
This key defines the height of the bounding box used in the resizing method defined by resize_style.
Examples
In this example, we have configured the height of the bounding box for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines whether you can upscale an image to fit the bounding box while resizing an image prior to upload.
Has no effect if files are not resized.
Examples
In this example, we have configured an Image Input to allow upscaling images to fit the bounding box while resizing.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
expandable: true
This key toggles whether CloudCannon will instruct a rich text editor to save width and height attributes on image elements.
Setting this key to true will instruct the rich text editor to save width and height attributes on image elements. This can prevent pop-in as a page loads.
By default, this key is false (i.e., width and height attributes are not saved on image elements). This defaults to true if the Image Size Attributes site flag is enabled (this is enabled for sites created before June 23 2023, in order to keep those sites working).
Examples
In this example, CloudCannon will save width and height attributes on image elements in a Rich Text Input.
_inputs:
content:
type: markdown
options:
image_size_attributes: true
This key defines which sources and DAMs you are allowed to upload to and browse.
The value can be an array of strings. Valid values include site-files and the reference key for any DAM connected to your site.
If site-files is omitted from the array, site files will not be available as an asset source for this input.
Examples
In this example, we have configured allowed sources for an Image Input.
_inputs:
image:
type: image
options:
allowed_sources:
- site-files
- my-cloudinary-dam
This key toggles whether CloudCannon will skip the image resizing process configured for this input when selecting existing images.
Setting this key to true will skip the image resizing process when selecting existing images.
Examples
In this example, CloudCannon will skip the image resizing process when selecting existing images for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
prevent_resize_existing_files: true
This key defines definitions for creating additional images of different sizes when uploading or selecting existing files.
Examples
In this example, we have configured an Image Input to create additional images of different sizes when uploading or selecting files.
_inputs:
hero_image:
type: image
options:
sizes:
- size: 2x
- size: 3x
This key defines the maximum string length, in characters, that CloudCannon will allow in an Input.
When configured, CloudCannon will warn you when an Input value is too long.
If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
Value can be any non-negative integer.
If this key is set to 0, CloudCannon requires the Input to be empty.
If options.min_length is also configured, this key cannot be a smaller number.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to enter a blog description using the Rich Text seo_description Input. This Input limits you to a maximum of 125 characters.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
min_length: 25
This key defines a custom error message that explains why a value has failed the validation criteria from options.max_length.
This key requires you to define options.max_length.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to enter a valid number of characters using a custom message.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
max_length_message: You are only allowed 125 characters.
min_length: 25
min_length_message: Please write more than 25 characters.
This key defines the minimum string length, in characters, that CloudCannon will allow in an Input.
When configured, CloudCannon will warn you when an Input value is too short.
If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
Value can be any positive integer.
If options.max_length is also configured, this key cannot be a greater number.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to enter a blog description using the Rich Text seo_description Input. This Input requires a minimum of 25 characters.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
min_length: 25
This key defines a custom error message that explains why a value has failed the validation criteria from options.min_length.
This key requires you to define options.min_length.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to enter a valid number of characters using a custom message.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
max_length_message: You are only allowed 125 characters.
min_length: 25
min_length_message: Please write more than 25 characters.
This key defines the maximum string length, in words, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which maximum string length an Input will accept. This key requires you to define `options.max_words.
This key defines the minimum string length, in words, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which minimum string length an Input will accept. This key requires you to define options.min_words.
This key defines the maximum string length, in graphemes, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which maximum string length an Input will accept. This key requires you to define `options.max_graphemes.
This key defines the minimum string length, in graphemes, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which minimum string length an Input will accept. This key requires you to define options.min_graphemes.
This key defines the locale that CloudCannon uses to determine the number of words or graphemes in this Input, if you have max_words, min_words, max_graphemes, or min_graphemes configured.
This key defines a regular expression that the Input value must match.
When configured, CloudCannon will require you to enter a value that matches the REGEX pattern.
If the Input already contains an invalid value, CloudCannon will require you to enter a valid string to save your changes, or discard your unsaved changes.
Value must be a valid REGEX string.
If your REGEX string includes a \ character and CloudCannon Configuration File is a .yml file, use single quotes ' around the string to avoid a
build error.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to add an email address to the contact_email Input using the correct email format.
_inputs:
contact_email:
type: email
options:
pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
pattern_message: 'Please use the format ___@___.__'
This key defines a custom error message that explains why a value has failed the validation criteria from options.pattern.
This key requires you to define options.pattern.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to use the correct email format in the contact_email Input using a pattern message.
_inputs:
contact_email:
type: email
options:
pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
pattern_message: 'Please use the format ___@___.__'
This key defines the flags (e.g. case-insensitive searching) for the regular expression set in options.pattern.
Examples
In this example, we have configured pattern flags for a text input to enable case-insensitive searching.
_inputs:
search_term:
type: text
options:
pattern: "^[a-z]+$"
pattern_flags:
ignore_case: true
6 nested properties
This key defines the g flag - Search globally.
This key defines the i flag - Case-insensitive.
This key defines the m flag - ^ and $ match the start and end of each line rather than the entire string.
This key defines the s flag - . matches newline characters.
This key defines the u flag - Pattern is treated as a sequence of Unicode code points.
This key defines the v flag for extended unicode mode.
This key toggles whether CloudCannon requires this Input to have a value.
Setting this key to true will require you to enter a value to save your changes, or discard your unsaved changes.
By default, this key is false (i.e., CloudCannon does not require this Input to have a value).
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we want to require our team to enter an author value for markup files with this Input.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
This key defines a custom error message that explains why a value has failed the validation criteria from options.required.
This key requires you to define options.required.
This key has no default.
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to use enter an Input value using a required message.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
required_message: You are not allowed to leave this blank.
This key defines which file types are available to select or upload to this input.
Accepted format is an array or comma-separated string of MIME types.
The special value "*" means any type is accepted.
Examples
In this example, we have configured a Image Input to accept only JPEG or PNG files.
_inputs:
featured_image:
type: image
options:
accepts_mime_types:
- image/jpeg
- image/png
This key defines the maximum file size in kB that CloudCannon will allow you to upload.
When configured, CloudCannon will prevent you from saving your changes until you select a valid file size, or discard your unsaved changes.
Value can be any positive integer.
This key has no default.
This key is available for File and URL Inputs.
Examples
In this example, we want our team to upload an image using the feature_image Input. This Input limits you to a maximum file size of 750 kB.
_inputs:
feature_image:
type: image
comment: Select the feature image for the banner.
options:
max_file_size: 140
This key defines a custom error message that explains why a value has failed the validation criteria from options.max_file_size.
This key requires you to define options.max_file_size.
This key has no default.
This key is available for File and URL Inputs.
Examples
In this example, we want our team to upload an image using the feature_image Input. This Input limits you to a maximum file size of 750 kB.
_inputs:
feature_image:
type: image
comment: Select the feature image for the banner.
options:
max_file_size: 140
max_file_size_message: For SEO, keep this under 140kB
This key toggles whether CloudCannon will disable the context menu option and the drop area for uploading files.
Setting this key to true will disable the context menu option and prevent uploading file through drag-and-drop in a File Input.
Examples
In this example, CloudCannon will disable the option to upload a file in the context menu and prevent uploading file through drag-and-drop in a File Input.
_inputs:
image:
type: image
options:
disable_upload_file: true
This key toggles whether CloudCannon will prevent typing into the Text Input, while still allowing context menu options to change the value.
Setting this key to true will prevent typing into the Text Input.
Examples
In this example, CloudCannon will prevent typing into the Text Input url.
_inputs:
url:
type: url
options:
disable_direct_input: true
This key toggles whether CloudCannon will prevent file uploads inside the "Select existing file/image" file browser modal window.
Setting this key to true will prevent file uploads inside the file browser modal window.
Examples
In this example, CloudCannon will disable the option to upload files inside the file browser modal window.
_inputs:
image:
type: file
options:
disable_upload_file_in_file_browser: true
This key toggles whether CloudCannon will hide the options to link to an existing file, and upload a new file.
Setting this key to true will hide the options to link to an existing file and upload a new file. This does not prevent typing a file path in the input.
By default, this key is false (i.e., the options to link to an existing file and upload a new file are shown).
This key toggles whether CloudCannon will hide the option to link to a page.
Setting this key to true will hide the option to link to a page. This does not prevent typing a file's output URL in the input.
By default, this key is false (i.e., the option to link to a page is shown).
This key toggles whether CloudCannon will hide the option to link to an email address.
Setting this key to true will hide the option to link to an email address. This does not prevent typing a mailto: link in the input.
By default, this key is false (i.e., the option to link to an email address is shown).
This key toggles whether CloudCannon will hide the option to link to a telephone number.
Setting this key to true will hide the option to link to a telephone number. This does not prevent typing a tel: link in the input.
By default, this key is false (i.e., the option to link to a telephone number is shown).
This key defines an editing interface for data with multiple predefined options.
Select inputs only allow one value.
Examples
In this example, we have configured the category key as a Select Input.
_inputs:
category:
type: select
label: Category
options:
values:
- Blog
- News
- Events
This key defines the input type, which controls how this input appears and behaves.
Examples
In this example, we have configured the category key as a Select Input type.
_inputs:
category:
type: select
options:
values:
- Blog
- News
- Events
This key defines the subtitle text above an Input.
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.
Examples
In this example, we want to add helpful guidance for our page_description Input.
_inputs:
page_description:
type: text
label: Page Description
comment: Enter a brief description of this page for search engines
Provides a custom link for documentation for editors shown above input.
This key defines the bold title text above an Input.
Examples
In this example, we want to customize the label for our page_title Input to be more descriptive.
_inputs:
page_title:
type: text
label: Article Title
comment: Enter the main title for this article
This key defines the visibility of an input in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Hidden inputs are useful when you want an input to exist, but not be visible or editable outside of the Source Editor.
Value can be a boolean or a string. A boolean value of true will hide the input.
A string value can hide an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key follows the input naming convention where key names beginning with an underscore are hidden true.
This key defines whether the value of an input is editable in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Disabled inputs are useful if you want CloudCannon to display the input value, but prevent team members from editing the value outside of the Source Editor.
The value of this key can be a boolean or a string. A boolean value of true will prevent team members from editing the value.
A string value can prevent team members from editing an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key is false (i.e., team members can edit input values).
Examples
In this example, we have configured the date_created Date 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
disabled: true
instance_value: NOW
options:
timezone: Etc/UTC
This key defines whether an input is automatically populated with a value when the input is created.
This occurs when creating a new file, or adding array items containing this input.
Valid values are UUID or NOW.
UUIDgenerates a uuidv4 key (extremely unlikely to generate duplicates), useful for identifying unique items (e.g.6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b)NOWgenerates the current datetime in the Site's configured timezone
Examples
In this example, we have configured an input to automatically populate with a UUID when created.
_inputs:
id:
type: text
instance_value: UUID
This key toggles whether CloudCannon will rehydrate inputs configured with an instance_value with a new value when duplicated.
Setting this key to true will prevent rehydration of instance values when inputs are duplicated.
Examples
In this example, CloudCannon will prevent rehydration of instance values when inputs are duplicated.
_inputs:
id:
type: text
instance_value: UUID
disable_instance_value_rehydration: true
This key defines whether CloudCannon should merge this input configuration with any matching, less specific configurations elsewhere in the configuration cascade.
The configuration cascade works by finding the most specific _inputs entry.
Usually, once an option is found in the cascade, there's no reason to keep looking.
When this key is true, the cascade continues looking and each entry found is merged.
This key allows you to define some options globally while using specific options for other keys at different levels of the cascade.
For example, define a comment globally, but use collection-specific label for inputs in different collections.
You can stop the cascade at any point in the configuration cascade by setting cascade to false.
Examples
In this example, we have configured cascade to merge input configurations across the configuration cascade.
_inputs:
title:
type: text
cascade: true
comment: Global comment for all title inputs
This key defines options that are specific to Select Inputs.
Examples
In this example, we have configured Select Input options including values.
_inputs:
category:
type: select
options:
values:
- Blog
- News
- Events
27 nested properties
This key toggles whether CloudCannon requires this Input to have a value.
Setting this key to true will require you to enter a value to save your changes, or discard your unsaved changes.
By default, this key is false (i.e., CloudCannon does not require this Input to have a value).
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we want to require our team to enter an author value for markup files with this Input.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
This key defines a custom error message that explains why a value has failed the validation criteria from options.required.
This key requires you to define options.required.
This key has no default.
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to use enter an Input value using a required message.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
required_message: You are not allowed to leave this blank.
This key toggles whether CloudCannon will allow new text values to be created at edit time.
Setting this key to true will allow new text values to be created at edit time.
Examples
In this example, CloudCannon will allow users to add new values to a Select Input.
_inputs:
category:
type: select
options:
values:
- Blog
- News
allow_create: true
This key is deprecated. If you want to prevent empty values, we recommend setting _inputs.*.options.required to true instead.
This key toggles whether CloudCannon will accept empty values, and pre-select the first option if opened with an empty value.
Setting this key to true will allow CloudCannon to accept empty values.
Examples
In this example, CloudCannon will accept empty values for a Select Input.
_inputs:
category:
type: select
options:
values:
- Blog
- News
- Events
allow_empty: true
This key defines the values available to choose from.
Optional, defaults to fetching values from the naming convention (e.g. colors or my_colors for data set colors).
Examples
In this example, we have configured a Select Input with custom values to choose from.
_inputs:
category:
type: select
options:
values:
- Blog
- News
- Events
This key defines the key used for mapping between saved values and objects in values.
This changes how the input saves selected values to match.
Defaults to checking for "id", "uuid", "path", "title", then "name".
Has no effect unless values is an array of objects, the key is used instead for objects, and the value itself is used for primitive types.
This key defines how selected items are rendered.
This key defines how CloudCannon should render selectable options in the dropdown of a Select Input.
Examples
In this example, we have configured a Select Input to display options using the card view.
_inputs:
category:
type: select
options:
values:
- Blog
- News
- Events
picker_view: card
This key defines the maximum string length, in characters, that CloudCannon will allow in an Input.
When configured, CloudCannon will warn you when an Input value is too long.
If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
Value can be any non-negative integer.
If this key is set to 0, CloudCannon requires the Input to be empty.
If options.min_length is also configured, this key cannot be a smaller number.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to enter a blog description using the Rich Text seo_description Input. This Input limits you to a maximum of 125 characters.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
min_length: 25
This key defines a custom error message that explains why a value has failed the validation criteria from options.max_length.
This key requires you to define options.max_length.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to enter a valid number of characters using a custom message.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
max_length_message: You are only allowed 125 characters.
min_length: 25
min_length_message: Please write more than 25 characters.
This key defines the minimum string length, in characters, that CloudCannon will allow in an Input.
When configured, CloudCannon will warn you when an Input value is too short.
If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
Value can be any positive integer.
If options.max_length is also configured, this key cannot be a greater number.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to enter a blog description using the Rich Text seo_description Input. This Input requires a minimum of 25 characters.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
min_length: 25
This key defines a custom error message that explains why a value has failed the validation criteria from options.min_length.
This key requires you to define options.min_length.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to enter a valid number of characters using a custom message.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
max_length_message: You are only allowed 125 characters.
min_length: 25
min_length_message: Please write more than 25 characters.
This key defines the maximum string length, in words, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which maximum string length an Input will accept. This key requires you to define `options.max_words.
This key defines the minimum string length, in words, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which minimum string length an Input will accept. This key requires you to define options.min_words.
This key defines the maximum string length, in graphemes, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which maximum string length an Input will accept. This key requires you to define `options.max_graphemes.
This key defines the minimum string length, in graphemes, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which minimum string length an Input will accept. This key requires you to define options.min_graphemes.
This key defines the locale that CloudCannon uses to determine the number of words or graphemes in this Input, if you have max_words, min_words, max_graphemes, or min_graphemes configured.
This key defines a regular expression that the Input value must match.
When configured, CloudCannon will require you to enter a value that matches the REGEX pattern.
If the Input already contains an invalid value, CloudCannon will require you to enter a valid string to save your changes, or discard your unsaved changes.
Value must be a valid REGEX string.
If your REGEX string includes a \ character and CloudCannon Configuration File is a .yml file, use single quotes ' around the string to avoid a
build error.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to add an email address to the contact_email Input using the correct email format.
_inputs:
contact_email:
type: email
options:
pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
pattern_message: 'Please use the format ___@___.__'
This key defines a custom error message that explains why a value has failed the validation criteria from options.pattern.
This key requires you to define options.pattern.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to use the correct email format in the contact_email Input using a pattern message.
_inputs:
contact_email:
type: email
options:
pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
pattern_message: 'Please use the format ___@___.__'
This key defines the flags (e.g. case-insensitive searching) for the regular expression set in options.pattern.
Examples
In this example, we have configured pattern flags for a text input to enable case-insensitive searching.
_inputs:
search_term:
type: text
options:
pattern: "^[a-z]+$"
pattern_flags:
ignore_case: true
6 nested properties
This key defines the g flag - Search globally.
This key defines the i flag - Case-insensitive.
This key defines the m flag - ^ and $ match the start and end of each line rather than the entire string.
This key defines the s flag - . matches newline characters.
This key defines the u flag - Pattern is treated as a sequence of Unicode code points.
This key defines the v flag for extended unicode mode.
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.
Examples
In this example, we have configured the appearance of file Cards in the Collection browser.
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.
_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
This key defines the main text displayed on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, or text string. When multiple entries are provided, CloudCannon will use them in order as fallback options.
Examples
In this example, we have configured the main text for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of title first, then the {name} template, and finally fall back to the static text value.
collections_config:
blog:
preview:
text:
- key: title
- template: '{name}'
- text: 'Untitled'
In this example, we have configured the main text for Cards in the blog Collection to display the title key.
collections_config:
blog:
preview:
text:
- key: title
This key defines the secondary text displayed below the main text on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, or text string. When multiple entries are provided, CloudCannon will use them in order as fallback options.
Examples
In this example, we have configured the subtext for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of author first, then the {writer} template, and finally fall back to the static text value.
collections_config:
blog:
preview:
subtext:
- key: author
- template: '{writer}'
- text: 'Unknown author'
In this example, we have configured the subtext for Cards in the blog Collection to display the author key.
collections_config:
blog:
preview:
subtext:
- key: author
This key defines the image displayed on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, or text string that results in a file path or URL to an image file. When multiple entries are provided, CloudCannon will use them in order as fallback options.
Examples
In this example, we have configured the image for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of featured_image first, then the {thumbnail} template, and finally fall back to the static text value.
collections_config:
blog:
preview:
image:
- key: featured_image
- template: '{thumbnail}'
- text: 'default-image.jpg'
In this example, we have configured the image for Structure Cards to display the profile_picture key.
_structures:
staff:
values:
- value:
_type: Employee
name:
profile_picture:
preview:
image:
- key: profile_picture
This key defines the icon displayed on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, text string, that results in one of Google's Material Symbols. When multiple entries are provided, CloudCannon will use them in order as fallback options.
For Cards in the Collection Browser, this key defaults to the value of collections_config.*.icon. Otherwise, this key has no default.
Examples
In this example, we have configured the icon for Cards in the blog Collection to use the edit_note icon.
collections_config:
blog:
preview:
icon: edit_note
In this example, we have configured the icon for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of logo first, then fall back to the edit_note icon.
collections_config:
blog:
preview:
icon:
- key: logo
- edit_note
This key defines the color of the icon displayed on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, or text string. When multiple entries are provided, CloudCannon will use them in order as fallback options.
Color values can be hex codes (e.g., #ff0000), CSS color names, or reference a data key that contains a color value.
Examples
In this example, we have configured the icon color for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of color first, then fall back to the static hex color value.
collections_config:
blog:
preview:
icon_color:
- key: color
- text: '#ff0000'
This key defines the background color of the icon displayed on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, or text string. When multiple entries are provided, CloudCannon will use them in order as fallback options.
Color values can be hex codes (e.g., #ff0000), CSS color names, or reference a data key that contains a color value.
Examples
In this example, we have configured the icon background color for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of bg_color first, then fall back to the static hex color value.
collections_config:
blog:
preview:
icon_background_color:
- key: bg_color
- text: '#f0f0f0'
This key defines tags displayed on Cards in the Collection browser, Structures, and Snippets.
Examples
In this example, we have configured tags for Cards in the blog Collection to display category tags.
collections_config:
blog:
preview:
tags:
- featured
- tutorial
This key defines metadata entries displayed on Cards in the Collection browser, Structures, and Snippets.
The value is an array of metadata entry objects. Each metadata entry can contain text, image, icon, icon_color, and icon_background_color properties.
Metadata entries are typically used to display additional information about a card, such as publication dates, URLs, or other contextual data.
Examples
In this example, we have configured two metadata entries for Cards in the blog Collection to display the URL and publication date.
collections_config:
blog:
preview:
metadata:
- text:
- key: url
- icon: event
icon_color: light-blue
text:
- template: 'Published on {date|date_long}'
This key defines the appearance of the gallery section on Cards in the Collection browser, Structures, and Snippets.
Examples
In this example, we have configured the gallery section for Cards in the blog Collection to display the image stored under the featured_image key with a padded fit.
collections_config:
blog:
preview:
gallery:
image:
- key: featured_image
fit: padded
7 nested properties
This key defines the main text displayed on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, or text string. When multiple entries are provided, CloudCannon will use them in order as fallback options.
Examples
In this example, we have configured the main text for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of title first, then the {name} template, and finally fall back to the static text value.
collections_config:
blog:
preview:
text:
- key: title
- template: '{name}'
- text: 'Untitled'
In this example, we have configured the main text for Cards in the blog Collection to display the title key.
collections_config:
blog:
preview:
text:
- key: title
This key defines the image displayed on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, or text string that results in a file path or URL to an image file. When multiple entries are provided, CloudCannon will use them in order as fallback options.
Examples
In this example, we have configured the image for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of featured_image first, then the {thumbnail} template, and finally fall back to the static text value.
collections_config:
blog:
preview:
image:
- key: featured_image
- template: '{thumbnail}'
- text: 'default-image.jpg'
In this example, we have configured the image for Structure Cards to display the profile_picture key.
_structures:
staff:
values:
- value:
_type: Employee
name:
profile_picture:
preview:
image:
- key: profile_picture
This key defines the icon displayed on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, text string, that results in one of Google's Material Symbols. When multiple entries are provided, CloudCannon will use them in order as fallback options.
For Cards in the Collection Browser, this key defaults to the value of collections_config.*.icon. Otherwise, this key has no default.
Examples
In this example, we have configured the icon for Cards in the blog Collection to use the edit_note icon.
collections_config:
blog:
preview:
icon: edit_note
In this example, we have configured the icon for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of logo first, then fall back to the edit_note icon.
collections_config:
blog:
preview:
icon:
- key: logo
- edit_note
This key defines the color of the icon displayed on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, or text string. When multiple entries are provided, CloudCannon will use them in order as fallback options.
Color values can be hex codes (e.g., #ff0000), CSS color names, or reference a data key that contains a color value.
Examples
In this example, we have configured the icon color for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of color first, then fall back to the static hex color value.
collections_config:
blog:
preview:
icon_color:
- key: color
- text: '#ff0000'
This key defines the background color of the icon displayed on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, or text string. When multiple entries are provided, CloudCannon will use them in order as fallback options.
Color values can be hex codes (e.g., #ff0000), CSS color names, or reference a data key that contains a color value.
Examples
In this example, we have configured the icon background color for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of bg_color first, then fall back to the static hex color value.
collections_config:
blog:
preview:
icon_background_color:
- key: bg_color
- text: '#f0f0f0'
This key defines how images fit within their containers in the gallery section of a Card.
Valid values are padded (default), contain, cover, or cover-top.
- The
paddedvalue adds padding around images to maintain aspect ratio. - The
containvalue ensures images fit entirely within the container by setting the largest dimension of the image to the largest dimension of the container, while maintaining aspect ratio. - The
covervalue ensures images cover the entire container while maintaining aspect ratio, aligning the center of the image with the center of the container. - The
cover-topvalue ensures images cover the entire container while maintaining aspect ratio, aligning the top of the image with the top of the container.
This key defaults to contain.
Examples
In this example, we have configured the gallery fit to use cover so images cover the entire container while maintaining aspect ratio, aligning the center of the image with the center of the container.
collections_config:
blog:
preview:
gallery:
image:
- key: featured_image
fit: cover
This key defines the background color of the gallery area on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, or text string. When multiple entries are provided, CloudCannon will use them in order as fallback options.
Color values can be hex codes (e.g., #ff0000), CSS color names, or reference a data key that contains a color value.
Examples
In this example, we have configured the gallery background color with an array of values to provide fallback options. CloudCannon will use the value of gallery_bg_color first, then the {bg_color} template, and finally fall back to the static hex color value.
collections_config:
blog:
preview:
gallery:
image:
- key: featured_image
background_color:
- key: gallery_bg_color
- template: '{bg_color}'
- text: '#ffffff'
In this example, we have configured the gallery background color to use a static CSS color value.
collections_config:
blog:
preview:
gallery:
image:
- key: featured_image
background_color:
- 'red'
This key defines the main text displayed on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, or text string. When multiple entries are provided, CloudCannon will use them in order as fallback options.
Examples
In this example, we have configured the main text for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of title first, then the {name} template, and finally fall back to the static text value.
collections_config:
blog:
preview:
text:
- key: title
- template: '{name}'
- text: 'Untitled'
In this example, we have configured the main text for Cards in the blog Collection to display the title key.
collections_config:
blog:
preview:
text:
- key: title
This key defines the secondary text displayed below the main text on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, or text string. When multiple entries are provided, CloudCannon will use them in order as fallback options.
Examples
In this example, we have configured the subtext for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of author first, then the {writer} template, and finally fall back to the static text value.
collections_config:
blog:
preview:
subtext:
- key: author
- template: '{writer}'
- text: 'Unknown author'
In this example, we have configured the subtext for Cards in the blog Collection to display the author key.
collections_config:
blog:
preview:
subtext:
- key: author
This key defines the image displayed on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, or text string that results in a file path or URL to an image file. When multiple entries are provided, CloudCannon will use them in order as fallback options.
Examples
In this example, we have configured the image for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of featured_image first, then the {thumbnail} template, and finally fall back to the static text value.
collections_config:
blog:
preview:
image:
- key: featured_image
- template: '{thumbnail}'
- text: 'default-image.jpg'
In this example, we have configured the image for Structure Cards to display the profile_picture key.
_structures:
staff:
values:
- value:
_type: Employee
name:
profile_picture:
preview:
image:
- key: profile_picture
This key defines the icon displayed on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, text string, that results in one of Google's Material Symbols. When multiple entries are provided, CloudCannon will use them in order as fallback options.
For Cards in the Collection Browser, this key defaults to the value of collections_config.*.icon. Otherwise, this key has no default.
Examples
In this example, we have configured the icon for Cards in the blog Collection to use the edit_note icon.
collections_config:
blog:
preview:
icon: edit_note
In this example, we have configured the icon for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of logo first, then fall back to the edit_note icon.
collections_config:
blog:
preview:
icon:
- key: logo
- edit_note
This key defines the color of the icon displayed on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, or text string. When multiple entries are provided, CloudCannon will use them in order as fallback options.
Color values can be hex codes (e.g., #ff0000), CSS color names, or reference a data key that contains a color value.
Examples
In this example, we have configured the icon color for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of color first, then fall back to the static hex color value.
collections_config:
blog:
preview:
icon_color:
- key: color
- text: '#ff0000'
This key defines the background color of the icon displayed on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, or text string. When multiple entries are provided, CloudCannon will use them in order as fallback options.
Color values can be hex codes (e.g., #ff0000), CSS color names, or reference a data key that contains a color value.
Examples
In this example, we have configured the icon background color for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of bg_color first, then fall back to the static hex color value.
collections_config:
blog:
preview:
icon_background_color:
- key: bg_color
- text: '#f0f0f0'
This key defines tags displayed on Cards in the Collection browser, Structures, and Snippets.
Examples
In this example, we have configured tags for Cards in the blog Collection to display category tags.
collections_config:
blog:
preview:
tags:
- featured
- tutorial
This key defines metadata entries displayed on Cards in the Collection browser, Structures, and Snippets.
The value is an array of metadata entry objects. Each metadata entry can contain text, image, icon, icon_color, and icon_background_color properties.
Metadata entries are typically used to display additional information about a card, such as publication dates, URLs, or other contextual data.
Examples
In this example, we have configured two metadata entries for Cards in the blog Collection to display the URL and publication date.
collections_config:
blog:
preview:
metadata:
- text:
- key: url
- icon: event
icon_color: light-blue
text:
- template: 'Published on {date|date_long}'
This key represents an individual metadata entry object in the preview.metadata array.
The value is an object that can contain text, image, icon, icon_color, and icon_background_color properties. Each metadata entry is displayed on Cards in the Collection browser, Structures, and Snippets.
Examples
In this example, we have configured a metadata entry for Cards in the blog Collection to display the URL using a template.
collections_config:
blog:
preview:
metadata:
- template: '[url]'
This key defines the main text displayed on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, or text string. When multiple entries are provided, CloudCannon will use them in order as fallback options.
Examples
In this example, we have configured the main text for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of title first, then the {name} template, and finally fall back to the static text value.
collections_config:
blog:
preview:
text:
- key: title
- template: '{name}'
- text: 'Untitled'
In this example, we have configured the main text for Cards in the blog Collection to display the title key.
collections_config:
blog:
preview:
text:
- key: title
This key defines the image displayed on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, or text string that results in a file path or URL to an image file. When multiple entries are provided, CloudCannon will use them in order as fallback options.
Examples
In this example, we have configured the image for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of featured_image first, then the {thumbnail} template, and finally fall back to the static text value.
collections_config:
blog:
preview:
image:
- key: featured_image
- template: '{thumbnail}'
- text: 'default-image.jpg'
In this example, we have configured the image for Structure Cards to display the profile_picture key.
_structures:
staff:
values:
- value:
_type: Employee
name:
profile_picture:
preview:
image:
- key: profile_picture
This key defines the icon displayed on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, text string, that results in one of Google's Material Symbols. When multiple entries are provided, CloudCannon will use them in order as fallback options.
For Cards in the Collection Browser, this key defaults to the value of collections_config.*.icon. Otherwise, this key has no default.
Examples
In this example, we have configured the icon for Cards in the blog Collection to use the edit_note icon.
collections_config:
blog:
preview:
icon: edit_note
In this example, we have configured the icon for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of logo first, then fall back to the edit_note icon.
collections_config:
blog:
preview:
icon:
- key: logo
- edit_note
This key defines the color of the icon displayed on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, or text string. When multiple entries are provided, CloudCannon will use them in order as fallback options.
Color values can be hex codes (e.g., #ff0000), CSS color names, or reference a data key that contains a color value.
Examples
In this example, we have configured the icon color for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of color first, then fall back to the static hex color value.
collections_config:
blog:
preview:
icon_color:
- key: color
- text: '#ff0000'
This key defines the background color of the icon displayed on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, or text string. When multiple entries are provided, CloudCannon will use them in order as fallback options.
Color values can be hex codes (e.g., #ff0000), CSS color names, or reference a data key that contains a color value.
Examples
In this example, we have configured the icon background color for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of bg_color first, then fall back to the static hex color value.
collections_config:
blog:
preview:
icon_background_color:
- key: bg_color
- text: '#f0f0f0'
This key defines the appearance of the gallery section on Cards in the Collection browser, Structures, and Snippets.
Examples
In this example, we have configured the gallery section for Cards in the blog Collection to display the image stored under the featured_image key with a padded fit.
collections_config:
blog:
preview:
gallery:
image:
- key: featured_image
fit: padded
This key defines the main text displayed on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, or text string. When multiple entries are provided, CloudCannon will use them in order as fallback options.
Examples
In this example, we have configured the main text for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of title first, then the {name} template, and finally fall back to the static text value.
collections_config:
blog:
preview:
text:
- key: title
- template: '{name}'
- text: 'Untitled'
In this example, we have configured the main text for Cards in the blog Collection to display the title key.
collections_config:
blog:
preview:
text:
- key: title
This key defines the image displayed on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, or text string that results in a file path or URL to an image file. When multiple entries are provided, CloudCannon will use them in order as fallback options.
Examples
In this example, we have configured the image for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of featured_image first, then the {thumbnail} template, and finally fall back to the static text value.
collections_config:
blog:
preview:
image:
- key: featured_image
- template: '{thumbnail}'
- text: 'default-image.jpg'
In this example, we have configured the image for Structure Cards to display the profile_picture key.
_structures:
staff:
values:
- value:
_type: Employee
name:
profile_picture:
preview:
image:
- key: profile_picture
This key defines the icon displayed on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, text string, that results in one of Google's Material Symbols. When multiple entries are provided, CloudCannon will use them in order as fallback options.
For Cards in the Collection Browser, this key defaults to the value of collections_config.*.icon. Otherwise, this key has no default.
Examples
In this example, we have configured the icon for Cards in the blog Collection to use the edit_note icon.
collections_config:
blog:
preview:
icon: edit_note
In this example, we have configured the icon for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of logo first, then fall back to the edit_note icon.
collections_config:
blog:
preview:
icon:
- key: logo
- edit_note
This key defines the color of the icon displayed on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, or text string. When multiple entries are provided, CloudCannon will use them in order as fallback options.
Color values can be hex codes (e.g., #ff0000), CSS color names, or reference a data key that contains a color value.
Examples
In this example, we have configured the icon color for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of color first, then fall back to the static hex color value.
collections_config:
blog:
preview:
icon_color:
- key: color
- text: '#ff0000'
This key defines the background color of the icon displayed on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, or text string. When multiple entries are provided, CloudCannon will use them in order as fallback options.
Color values can be hex codes (e.g., #ff0000), CSS color names, or reference a data key that contains a color value.
Examples
In this example, we have configured the icon background color for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of bg_color first, then fall back to the static hex color value.
collections_config:
blog:
preview:
icon_background_color:
- key: bg_color
- text: '#f0f0f0'
This key defines how images fit within their containers in the gallery section of a Card.
Valid values are padded (default), contain, cover, or cover-top.
- The
paddedvalue adds padding around images to maintain aspect ratio. - The
containvalue ensures images fit entirely within the container by setting the largest dimension of the image to the largest dimension of the container, while maintaining aspect ratio. - The
covervalue ensures images cover the entire container while maintaining aspect ratio, aligning the center of the image with the center of the container. - The
cover-topvalue ensures images cover the entire container while maintaining aspect ratio, aligning the top of the image with the top of the container.
This key defaults to contain.
Examples
In this example, we have configured the gallery fit to use cover so images cover the entire container while maintaining aspect ratio, aligning the center of the image with the center of the container.
collections_config:
blog:
preview:
gallery:
image:
- key: featured_image
fit: cover
This key defines the background color of the gallery area on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, or text string. When multiple entries are provided, CloudCannon will use them in order as fallback options.
Color values can be hex codes (e.g., #ff0000), CSS color names, or reference a data key that contains a color value.
Examples
In this example, we have configured the gallery background color with an array of values to provide fallback options. CloudCannon will use the value of gallery_bg_color first, then the {bg_color} template, and finally fall back to the static hex color value.
collections_config:
blog:
preview:
gallery:
image:
- key: featured_image
background_color:
- key: gallery_bg_color
- template: '{bg_color}'
- text: '#ffffff'
In this example, we have configured the gallery background color to use a static CSS color value.
collections_config:
blog:
preview:
gallery:
image:
- key: featured_image
background_color:
- 'red'
This key defines how images fit within their containers in the gallery section of a Card.
Valid values are padded (default), contain, cover, or cover-top.
- The
paddedvalue adds padding around images to maintain aspect ratio. - The
containvalue ensures images fit entirely within the container by setting the largest dimension of the image to the largest dimension of the container, while maintaining aspect ratio. - The
covervalue ensures images cover the entire container while maintaining aspect ratio, aligning the center of the image with the center of the container. - The
cover-topvalue ensures images cover the entire container while maintaining aspect ratio, aligning the top of the image with the top of the container.
This key defaults to contain.
Examples
In this example, we have configured the gallery fit to use cover so images cover the entire container while maintaining aspect ratio, aligning the center of the image with the center of the container.
collections_config:
blog:
preview:
gallery:
image:
- key: featured_image
fit: cover
This key defines the background color of the gallery area on Cards in the Collection browser, Structures, and Snippets.
The value can be an array or a single value, and reference a key, template, or text string. When multiple entries are provided, CloudCannon will use them in order as fallback options.
Color values can be hex codes (e.g., #ff0000), CSS color names, or reference a data key that contains a color value.
Examples
In this example, we have configured the gallery background color with an array of values to provide fallback options. CloudCannon will use the value of gallery_bg_color first, then the {bg_color} template, and finally fall back to the static hex color value.
collections_config:
blog:
preview:
gallery:
image:
- key: featured_image
background_color:
- key: gallery_bg_color
- template: '{bg_color}'
- text: '#ffffff'
In this example, we have configured the gallery background color to use a static CSS color value.
collections_config:
blog:
preview:
gallery:
image:
- key: featured_image
background_color:
- 'red'
This key defines the appearance of a Card when choosing an item to create. This uses preview as a base, and keys inside this object are overrides.
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.
Examples
In this example, we have configured the appearance of Cards in inputs using the Structure staff when adding items.
_structures:
staff:
values:
- value:
_type: Employee
name:
job_description:
profile_picture:
picker_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:
picker_preview:
text:
- key: name
- Manager
subtext:
- key: job_description
- Description of position
image:
- key: profile_picture
icon: face
This key toggles whether CloudCannon will allow new text values to be created at edit time.
Setting this key to true will allow new text values to be created at edit time.
Examples
In this example, CloudCannon will allow users to add new values to a Select Input.
_inputs:
category:
type: select
options:
values:
- Blog
- News
allow_create: true
This key is deprecated. If you want to prevent empty values, we recommend setting _inputs.*.options.required to true instead.
This key toggles whether CloudCannon will accept empty values, and pre-select the first option if opened with an empty value.
Setting this key to true will allow CloudCannon to accept empty values.
Examples
In this example, CloudCannon will accept empty values for a Select Input.
_inputs:
category:
type: select
options:
values:
- Blog
- News
- Events
allow_empty: true
This key defines the values available to choose from.
Optional, defaults to fetching values from the naming convention (e.g. colors or my_colors for data set colors).
Examples
In this example, we have configured a Select Input with custom values to choose from.
_inputs:
category:
type: select
options:
values:
- Blog
- News
- Events
This key defines the key used for mapping between saved values and objects in values.
This changes how the input saves selected values to match.
Defaults to checking for "id", "uuid", "path", "title", then "name".
Has no effect unless values is an array of objects, the key is used instead for objects, and the value itself is used for primitive types.
This key defines how selected items are rendered.
This key defines how CloudCannon should render selectable options in the dropdown of a Select Input.
Examples
In this example, we have configured a Select Input to display options using the card view.
_inputs:
category:
type: select
options:
values:
- Blog
- News
- Events
picker_view: card
This key defines an editing interface for data with multiple predefined options.
Multiselect inputs allow several values.
Examples
In this example, we have configured the tags key as a Multiselect Input.
_inputs:
tags:
type: multiselect
label: Tags
options:
values:
- featured
- news
- events
This key defines the input type, which controls how this input appears and behaves.
Examples
In this example, we have configured the tags key as a Multiselect Input type.
_inputs:
tags:
type: multiselect
This key defines the subtitle text above an Input.
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.
Examples
In this example, we want to add helpful guidance for our page_description Input.
_inputs:
page_description:
type: text
label: Page Description
comment: Enter a brief description of this page for search engines
Provides a custom link for documentation for editors shown above input.
This key defines the bold title text above an Input.
Examples
In this example, we want to customize the label for our page_title Input to be more descriptive.
_inputs:
page_title:
type: text
label: Article Title
comment: Enter the main title for this article
This key defines the visibility of an input in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Hidden inputs are useful when you want an input to exist, but not be visible or editable outside of the Source Editor.
Value can be a boolean or a string. A boolean value of true will hide the input.
A string value can hide an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key follows the input naming convention where key names beginning with an underscore are hidden true.
This key defines whether the value of an input is editable in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Disabled inputs are useful if you want CloudCannon to display the input value, but prevent team members from editing the value outside of the Source Editor.
The value of this key can be a boolean or a string. A boolean value of true will prevent team members from editing the value.
A string value can prevent team members from editing an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key is false (i.e., team members can edit input values).
Examples
In this example, we have configured the date_created Date 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
disabled: true
instance_value: NOW
options:
timezone: Etc/UTC
This key defines whether an input is automatically populated with a value when the input is created.
This occurs when creating a new file, or adding array items containing this input.
Valid values are UUID or NOW.
UUIDgenerates a uuidv4 key (extremely unlikely to generate duplicates), useful for identifying unique items (e.g.6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b)NOWgenerates the current datetime in the Site's configured timezone
Examples
In this example, we have configured an input to automatically populate with a UUID when created.
_inputs:
id:
type: text
instance_value: UUID
This key toggles whether CloudCannon will rehydrate inputs configured with an instance_value with a new value when duplicated.
Setting this key to true will prevent rehydration of instance values when inputs are duplicated.
Examples
In this example, CloudCannon will prevent rehydration of instance values when inputs are duplicated.
_inputs:
id:
type: text
instance_value: UUID
disable_instance_value_rehydration: true
This key defines whether CloudCannon should merge this input configuration with any matching, less specific configurations elsewhere in the configuration cascade.
The configuration cascade works by finding the most specific _inputs entry.
Usually, once an option is found in the cascade, there's no reason to keep looking.
When this key is true, the cascade continues looking and each entry found is merged.
This key allows you to define some options globally while using specific options for other keys at different levels of the cascade.
For example, define a comment globally, but use collection-specific label for inputs in different collections.
You can stop the cascade at any point in the configuration cascade by setting cascade to false.
Examples
In this example, we have configured cascade to merge input configurations across the configuration cascade.
_inputs:
title:
type: text
cascade: true
comment: Global comment for all title inputs
This key defines options that are specific to Multiselect Inputs.
Examples
In this example, we have configured Multiselect Input options including values.
_inputs:
tags:
type: multiselect
options:
values:
- featured
- news
- events
17 nested properties
This key toggles whether CloudCannon requires this Input to have a value.
Setting this key to true will require you to enter a value to save your changes, or discard your unsaved changes.
By default, this key is false (i.e., CloudCannon does not require this Input to have a value).
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we want to require our team to enter an author value for markup files with this Input.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
This key defines a custom error message that explains why a value has failed the validation criteria from options.required.
This key requires you to define options.required.
This key has no default.
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to use enter an Input value using a required message.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
required_message: You are not allowed to leave this blank.
This key toggles whether CloudCannon will allow new text values to be created at edit time.
Setting this key to true will allow new text values to be created at edit time.
Examples
In this example, CloudCannon will allow users to add new values to a Select Input.
_inputs:
category:
type: select
options:
values:
- Blog
- News
allow_create: true
This key is deprecated. If you want to prevent empty values, we recommend setting _inputs.*.options.required to true instead.
This key toggles whether CloudCannon will accept empty values, and pre-select the first option if opened with an empty value.
Setting this key to true will allow CloudCannon to accept empty values.
Examples
In this example, CloudCannon will accept empty values for a Select Input.
_inputs:
category:
type: select
options:
values:
- Blog
- News
- Events
allow_empty: true
This key defines the values available to choose from.
Optional, defaults to fetching values from the naming convention (e.g. colors or my_colors for data set colors).
Examples
In this example, we have configured a Select Input with custom values to choose from.
_inputs:
category:
type: select
options:
values:
- Blog
- News
- Events
This key defines the key used for mapping between saved values and objects in values.
This changes how the input saves selected values to match.
Defaults to checking for "id", "uuid", "path", "title", then "name".
Has no effect unless values is an array of objects, the key is used instead for objects, and the value itself is used for primitive types.
This key defines how selected items are rendered.
This key defines how CloudCannon should render selectable options in the dropdown of a Select Input.
Examples
In this example, we have configured a Select Input to display options using the card view.
_inputs:
category:
type: select
options:
values:
- Blog
- News
- Events
picker_view: card
This key defines the maximum number of items CloudCannon will allow in an Input.
When configured, CloudCannon will prevent you from adding more items to this Input.
If the Input already contains more items, CloudCannon will require you to remove items until the Input contains a valid number to save your changes, or discard your unsaved changes.
Value can be any positive integer.
If options.min_items is also configured, this key cannot be a lesser number.
This key has no default.
This key is available for Array and Multiselect or Multichoice Inputs.
Examples
In this example, we want to add an array of filepaths to our homepage's featured_posts Input. This Input limits you to a maximum of five array items.
_inputs:
featured_posts:
type: array
options:
max_items: 5
max_items_message: Cannot be more than 5
min_items: 2
min_items_message: Cannot be less than 2
This key defines a custom error message that explains why a value has failed the validation criteria from options.max_items.
This key requires you to define options.max_items.
This key has no default.
This key is available for Array and Multiselect or Multichoice Inputs.
Examples
In this example, we prompt our team to enter a valid number of items using a custom message.
_inputs:
featured_posts:
type: array
options:
max_items: 5
max_items_message: Cannot be more than 5
min_items: 2
min_items_message: Cannot be less than 2
This key defines the minimum number of items CloudCannon will allow in an Input.
When configured, CloudCannon will prevent you from removing items from this Input below this value.
If the Input already contains fewer items, CloudCannon will require you to add items until the Input contains a valid number to save your changes, or discard your unsaved changes.
Value can be any positive integer.
If options.min_items is also configured, this key cannot be a greater number.
This key has no default.
This key is available for Array and Multiselect or Multichoice Inputs.
Examples
In this example, we want to add an array of filepaths to our homepage's featured_posts Input. This Input limits you to a maximum of two array items.
_inputs:
featured_posts:
type: array
options:
max_items: 5
max_items_message: Cannot be more than 5
min_items: 2
min_items_message: Cannot be less than 2
This key defines a custom error message that explains why a value has failed the validation criteria from options.min_items.
This key requires you to define options.min_items.
This key has no default.
This key is available for Array and Multiselect or Multichoice Inputs.
Examples
In this example, we prompt our team to enter a valid number of items using a custom message.
_inputs:
featured_posts:
type: array
options:
max_items: 5
max_items_message: Cannot be more than 5
min_items: 2
min_items_message: Cannot be less than 2
This key defines the JSON Path selector that CloudCannon should use to determine if the value of an Input is unique.
When configured, CloudCannon will require the value of the Input to be unique compared to the value defined on the JSON Path.
If the Input already contains a non-unique value, CloudCannon will require you to change it to a valid value to save your changes, or discard your unsaved changes.
Value must be a valid JSON Path.
This key has no default.
This key is available for Array inputs.
Examples
In this example, we want our team to add article filepaths to the related_articles Input. This Input requires all the filepaths to be unique.
_inputs:
related_articles:
type: array
options:
unique_on: '$.path'
related_articles:
- path: /articles/first-article.md
featured: true
- path: /articles/second-article.md
featured: false
This key defines a custom error message that explains why a value has failed the validation criteria from options.unique_on.
This key requires you to define options.unique_on.
This key has no default.
This key is available for Array inputs.
Examples
In this example, we want our team to add article filepaths to the related_articles Input. This Input requires all the filepaths to be unique.
_inputs:
related_articles:
type: array
options:
unique_on: '$.path'
unique_on_message: The value for path must be different for all items.
related_articles:
- path: /articles/first-article.md
featured: true
- path: /articles/first-article.md
featured: false
This key defines the maximum number of items CloudCannon will allow in an Input.
When configured, CloudCannon will prevent you from adding more items to this Input.
If the Input already contains more items, CloudCannon will require you to remove items until the Input contains a valid number to save your changes, or discard your unsaved changes.
Value can be any positive integer.
If options.min_items is also configured, this key cannot be a lesser number.
This key has no default.
This key is available for Array and Multiselect or Multichoice Inputs.
Examples
In this example, we want to add an array of filepaths to our homepage's featured_posts Input. This Input limits you to a maximum of five array items.
_inputs:
featured_posts:
type: array
options:
max_items: 5
max_items_message: Cannot be more than 5
min_items: 2
min_items_message: Cannot be less than 2
This key defines a custom error message that explains why a value has failed the validation criteria from options.max_items.
This key requires you to define options.max_items.
This key has no default.
This key is available for Array and Multiselect or Multichoice Inputs.
Examples
In this example, we prompt our team to enter a valid number of items using a custom message.
_inputs:
featured_posts:
type: array
options:
max_items: 5
max_items_message: Cannot be more than 5
min_items: 2
min_items_message: Cannot be less than 2
This key defines the minimum number of items CloudCannon will allow in an Input.
When configured, CloudCannon will prevent you from removing items from this Input below this value.
If the Input already contains fewer items, CloudCannon will require you to add items until the Input contains a valid number to save your changes, or discard your unsaved changes.
Value can be any positive integer.
If options.min_items is also configured, this key cannot be a greater number.
This key has no default.
This key is available for Array and Multiselect or Multichoice Inputs.
Examples
In this example, we want to add an array of filepaths to our homepage's featured_posts Input. This Input limits you to a maximum of two array items.
_inputs:
featured_posts:
type: array
options:
max_items: 5
max_items_message: Cannot be more than 5
min_items: 2
min_items_message: Cannot be less than 2
This key defines a custom error message that explains why a value has failed the validation criteria from options.min_items.
This key requires you to define options.min_items.
This key has no default.
This key is available for Array and Multiselect or Multichoice Inputs.
Examples
In this example, we prompt our team to enter a valid number of items using a custom message.
_inputs:
featured_posts:
type: array
options:
max_items: 5
max_items_message: Cannot be more than 5
min_items: 2
min_items_message: Cannot be less than 2
This key defines the JSON Path selector that CloudCannon should use to determine if the value of an Input is unique.
When configured, CloudCannon will require the value of the Input to be unique compared to the value defined on the JSON Path.
If the Input already contains a non-unique value, CloudCannon will require you to change it to a valid value to save your changes, or discard your unsaved changes.
Value must be a valid JSON Path.
This key has no default.
This key is available for Array inputs.
Examples
In this example, we want our team to add article filepaths to the related_articles Input. This Input requires all the filepaths to be unique.
_inputs:
related_articles:
type: array
options:
unique_on: '$.path'
related_articles:
- path: /articles/first-article.md
featured: true
- path: /articles/second-article.md
featured: false
This key defines a custom error message that explains why a value has failed the validation criteria from options.unique_on.
This key requires you to define options.unique_on.
This key has no default.
This key is available for Array inputs.
Examples
In this example, we want our team to add article filepaths to the related_articles Input. This Input requires all the filepaths to be unique.
_inputs:
related_articles:
type: array
options:
unique_on: '$.path'
unique_on_message: The value for path must be different for all items.
related_articles:
- path: /articles/first-article.md
featured: true
- path: /articles/first-article.md
featured: false
This key defines how an 'empty' value will be saved. Does not apply to existing empty values.
Examples
In this example, we have configured how empty array values will be saved.
_inputs:
tags:
type: array
options:
empty_type: array
This key defines an editing interface for data with multiple predefined options.
Choice inputs only allow one value.
Examples
In this example, we have configured the status key as a Choice Input.
_inputs:
status:
type: choice
label: Status
options:
values:
- draft
- published
- archived
This key defines the input type, which controls how this input appears and behaves.
Examples
In this example, we have configured the status key as a Choice Input type.
_inputs:
status:
type: choice
This key defines the subtitle text above an Input.
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.
Examples
In this example, we want to add helpful guidance for our page_description Input.
_inputs:
page_description:
type: text
label: Page Description
comment: Enter a brief description of this page for search engines
Provides a custom link for documentation for editors shown above input.
This key defines the bold title text above an Input.
Examples
In this example, we want to customize the label for our page_title Input to be more descriptive.
_inputs:
page_title:
type: text
label: Article Title
comment: Enter the main title for this article
This key defines the visibility of an input in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Hidden inputs are useful when you want an input to exist, but not be visible or editable outside of the Source Editor.
Value can be a boolean or a string. A boolean value of true will hide the input.
A string value can hide an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key follows the input naming convention where key names beginning with an underscore are hidden true.
This key defines whether the value of an input is editable in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Disabled inputs are useful if you want CloudCannon to display the input value, but prevent team members from editing the value outside of the Source Editor.
The value of this key can be a boolean or a string. A boolean value of true will prevent team members from editing the value.
A string value can prevent team members from editing an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key is false (i.e., team members can edit input values).
Examples
In this example, we have configured the date_created Date 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
disabled: true
instance_value: NOW
options:
timezone: Etc/UTC
This key defines whether an input is automatically populated with a value when the input is created.
This occurs when creating a new file, or adding array items containing this input.
Valid values are UUID or NOW.
UUIDgenerates a uuidv4 key (extremely unlikely to generate duplicates), useful for identifying unique items (e.g.6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b)NOWgenerates the current datetime in the Site's configured timezone
Examples
In this example, we have configured an input to automatically populate with a UUID when created.
_inputs:
id:
type: text
instance_value: UUID
This key toggles whether CloudCannon will rehydrate inputs configured with an instance_value with a new value when duplicated.
Setting this key to true will prevent rehydration of instance values when inputs are duplicated.
Examples
In this example, CloudCannon will prevent rehydration of instance values when inputs are duplicated.
_inputs:
id:
type: text
instance_value: UUID
disable_instance_value_rehydration: true
This key defines whether CloudCannon should merge this input configuration with any matching, less specific configurations elsewhere in the configuration cascade.
The configuration cascade works by finding the most specific _inputs entry.
Usually, once an option is found in the cascade, there's no reason to keep looking.
When this key is true, the cascade continues looking and each entry found is merged.
This key allows you to define some options globally while using specific options for other keys at different levels of the cascade.
For example, define a comment globally, but use collection-specific label for inputs in different collections.
You can stop the cascade at any point in the configuration cascade by setting cascade to false.
Examples
In this example, we have configured cascade to merge input configurations across the configuration cascade.
_inputs:
title:
type: text
cascade: true
comment: Global comment for all title inputs
This key defines options that are specific to Choice Inputs.
Examples
In this example, we have configured Choice Input options including values.
_inputs:
status:
type: choice
options:
values:
- draft
- published
- archived
26 nested properties
This key toggles whether CloudCannon requires this Input to have a value.
Setting this key to true will require you to enter a value to save your changes, or discard your unsaved changes.
By default, this key is false (i.e., CloudCannon does not require this Input to have a value).
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we want to require our team to enter an author value for markup files with this Input.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
This key defines a custom error message that explains why a value has failed the validation criteria from options.required.
This key requires you to define options.required.
This key has no default.
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to use enter an Input value using a required message.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
required_message: You are not allowed to leave this blank.
This key is deprecated. If you want to prevent empty values, we recommend setting _inputs.*.options.required to true instead.
This key toggles whether CloudCannon will accept empty values, and pre-select the first option if opened with an empty value.
Setting this key to true will allow CloudCannon to accept empty values.
Examples
In this example, CloudCannon will accept empty values for a Select Input.
_inputs:
category:
type: select
options:
values:
- Blog
- News
- Events
allow_empty: true
This key defines the values available to choose from.
Optional, defaults to fetching values from the naming convention (e.g. colors or my_colors for data set colors).
Examples
In this example, we have configured a Select Input with custom values to choose from.
_inputs:
category:
type: select
options:
values:
- Blog
- News
- Events
This key defines the key used for mapping between saved values and objects in values.
This changes how the input saves selected values to match.
Defaults to checking for "id", "uuid", "path", "title", then "name".
Has no effect unless values is an array of objects, the key is used instead for objects, and the value itself is used for primitive types.
This key defines how selected items are rendered.
This key defines how CloudCannon should render selectable options in the dropdown of a Select Input.
Examples
In this example, we have configured a Select Input to display options using the card view.
_inputs:
category:
type: select
options:
values:
- Blog
- News
- Events
picker_view: card
This key defines the maximum string length, in characters, that CloudCannon will allow in an Input.
When configured, CloudCannon will warn you when an Input value is too long.
If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
Value can be any non-negative integer.
If this key is set to 0, CloudCannon requires the Input to be empty.
If options.min_length is also configured, this key cannot be a smaller number.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to enter a blog description using the Rich Text seo_description Input. This Input limits you to a maximum of 125 characters.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
min_length: 25
This key defines a custom error message that explains why a value has failed the validation criteria from options.max_length.
This key requires you to define options.max_length.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to enter a valid number of characters using a custom message.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
max_length_message: You are only allowed 125 characters.
min_length: 25
min_length_message: Please write more than 25 characters.
This key defines the minimum string length, in characters, that CloudCannon will allow in an Input.
When configured, CloudCannon will warn you when an Input value is too short.
If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
Value can be any positive integer.
If options.max_length is also configured, this key cannot be a greater number.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to enter a blog description using the Rich Text seo_description Input. This Input requires a minimum of 25 characters.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
min_length: 25
This key defines a custom error message that explains why a value has failed the validation criteria from options.min_length.
This key requires you to define options.min_length.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to enter a valid number of characters using a custom message.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
max_length_message: You are only allowed 125 characters.
min_length: 25
min_length_message: Please write more than 25 characters.
This key defines the maximum string length, in words, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which maximum string length an Input will accept. This key requires you to define `options.max_words.
This key defines the minimum string length, in words, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which minimum string length an Input will accept. This key requires you to define options.min_words.
This key defines the maximum string length, in graphemes, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which maximum string length an Input will accept. This key requires you to define `options.max_graphemes.
This key defines the minimum string length, in graphemes, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
This key defines the message that explains which minimum string length an Input will accept. This key requires you to define options.min_graphemes.
This key defines the locale that CloudCannon uses to determine the number of words or graphemes in this Input, if you have max_words, min_words, max_graphemes, or min_graphemes configured.
This key defines a regular expression that the Input value must match.
When configured, CloudCannon will require you to enter a value that matches the REGEX pattern.
If the Input already contains an invalid value, CloudCannon will require you to enter a valid string to save your changes, or discard your unsaved changes.
Value must be a valid REGEX string.
If your REGEX string includes a \ character and CloudCannon Configuration File is a .yml file, use single quotes ' around the string to avoid a
build error.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
To use this key in a Select Input, allow_create must be set to true.
Examples
In this example, we want our team to add an email address to the contact_email Input using the correct email format.
_inputs:
contact_email:
type: email
options:
pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
pattern_message: 'Please use the format ___@___.__'
This key defines a custom error message that explains why a value has failed the validation criteria from options.pattern.
This key requires you to define options.pattern.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to use the correct email format in the contact_email Input using a pattern message.
_inputs:
contact_email:
type: email
options:
pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
pattern_message: 'Please use the format ___@___.__'
This key defines the flags (e.g. case-insensitive searching) for the regular expression set in options.pattern.
Examples
In this example, we have configured pattern flags for a text input to enable case-insensitive searching.
_inputs:
search_term:
type: text
options:
pattern: "^[a-z]+$"
pattern_flags:
ignore_case: true
6 nested properties
This key defines the g flag - Search globally.
This key defines the i flag - Case-insensitive.
This key defines the m flag - ^ and $ match the start and end of each line rather than the entire string.
This key defines the s flag - . matches newline characters.
This key defines the u flag - Pattern is treated as a sequence of Unicode code points.
This key defines the v flag for extended unicode mode.
This key defines an editing interface for data with multiple predefined options.
Multichoice inputs allow several values.
Examples
In this example, we have configured the categories key as a Multichoice Input.
_inputs:
categories:
type: multichoice
label: Categories
options:
values:
- technology
- design
- business
This key defines the type of editing interface used for an Input.
Each Input type has a different appearance and functionality, processes and accepts different types of values, and has different configuration options.
Value can be one of the following: auto, checkbox, switch, code, color, datetime, date, time, file, document, image, number,
range, object, array, select, multiselect, choice, multichoice, text, textarea, email, html, markdown, or url.
If the type or value of an Input is misconfigured, CloudCannon will display an orange warning instead of an Input.
If type is not configured for an Input, CloudCannon will attempt to determine Input type based on value or key name conventions.
Examples
In this example, we have configured the categories key as a Multichoice Input type.
_inputs:
categories:
type: multichoice
This key defines the subtitle text above an Input.
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.
Examples
In this example, we want to add helpful guidance for our page_description Input.
_inputs:
page_description:
type: text
label: Page Description
comment: Enter a brief description of this page for search engines
Provides a custom link for documentation for editors shown above input.
This key defines the bold title text above an Input.
Examples
In this example, we want to customize the label for our page_title Input to be more descriptive.
_inputs:
page_title:
type: text
label: Article Title
comment: Enter the main title for this article
This key defines the visibility of an input in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Hidden inputs are useful when you want an input to exist, but not be visible or editable outside of the Source Editor.
Value can be a boolean or a string. A boolean value of true will hide the input.
A string value can hide an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key follows the input naming convention where key names beginning with an underscore are hidden true.
This key defines whether the value of an input is editable in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Disabled inputs are useful if you want CloudCannon to display the input value, but prevent team members from editing the value outside of the Source Editor.
The value of this key can be a boolean or a string. A boolean value of true will prevent team members from editing the value.
A string value can prevent team members from editing an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key is false (i.e., team members can edit input values).
Examples
In this example, we have configured the date_created Date 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
disabled: true
instance_value: NOW
options:
timezone: Etc/UTC
This key defines whether an input is automatically populated with a value when the input is created.
This occurs when creating a new file, or adding array items containing this input.
Valid values are UUID or NOW.
UUIDgenerates a uuidv4 key (extremely unlikely to generate duplicates), useful for identifying unique items (e.g.6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b)NOWgenerates the current datetime in the Site's configured timezone
Examples
In this example, we have configured an input to automatically populate with a UUID when created.
_inputs:
id:
type: text
instance_value: UUID
This key toggles whether CloudCannon will rehydrate inputs configured with an instance_value with a new value when duplicated.
Setting this key to true will prevent rehydration of instance values when inputs are duplicated.
Examples
In this example, CloudCannon will prevent rehydration of instance values when inputs are duplicated.
_inputs:
id:
type: text
instance_value: UUID
disable_instance_value_rehydration: true
This key defines whether CloudCannon should merge this input configuration with any matching, less specific configurations elsewhere in the configuration cascade.
The configuration cascade works by finding the most specific _inputs entry.
Usually, once an option is found in the cascade, there's no reason to keep looking.
When this key is true, the cascade continues looking and each entry found is merged.
This key allows you to define some options globally while using specific options for other keys at different levels of the cascade.
For example, define a comment globally, but use collection-specific label for inputs in different collections.
You can stop the cascade at any point in the configuration cascade by setting cascade to false.
Examples
In this example, we have configured cascade to merge input configurations across the configuration cascade.
_inputs:
title:
type: text
cascade: true
comment: Global comment for all title inputs
This key defines options that are specific to Multichoice Inputs.
Examples
In this example, we have configured Multichoice Input options including values.
_inputs:
categories:
type: multichoice
options:
values:
- technology
- design
- business
16 nested properties
This key toggles whether CloudCannon requires this Input to have a value.
Setting this key to true will require you to enter a value to save your changes, or discard your unsaved changes.
By default, this key is false (i.e., CloudCannon does not require this Input to have a value).
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we want to require our team to enter an author value for markup files with this Input.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
This key defines a custom error message that explains why a value has failed the validation criteria from options.required.
This key requires you to define options.required.
This key has no default.
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to use enter an Input value using a required message.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
required_message: You are not allowed to leave this blank.
This key is deprecated. If you want to prevent empty values, we recommend setting _inputs.*.options.required to true instead.
This key toggles whether CloudCannon will accept empty values, and pre-select the first option if opened with an empty value.
Setting this key to true will allow CloudCannon to accept empty values.
Examples
In this example, CloudCannon will accept empty values for a Select Input.
_inputs:
category:
type: select
options:
values:
- Blog
- News
- Events
allow_empty: true
This key defines the values available to choose from.
Optional, defaults to fetching values from the naming convention (e.g. colors or my_colors for data set colors).
Examples
In this example, we have configured a Select Input with custom values to choose from.
_inputs:
category:
type: select
options:
values:
- Blog
- News
- Events
This key defines the key used for mapping between saved values and objects in values.
This changes how the input saves selected values to match.
Defaults to checking for "id", "uuid", "path", "title", then "name".
Has no effect unless values is an array of objects, the key is used instead for objects, and the value itself is used for primitive types.
This key defines how selected items are rendered.
This key defines how CloudCannon should render selectable options in the dropdown of a Select Input.
Examples
In this example, we have configured a Select Input to display options using the card view.
_inputs:
category:
type: select
options:
values:
- Blog
- News
- Events
picker_view: card
This key defines the maximum number of items CloudCannon will allow in an Input.
When configured, CloudCannon will prevent you from adding more items to this Input.
If the Input already contains more items, CloudCannon will require you to remove items until the Input contains a valid number to save your changes, or discard your unsaved changes.
Value can be any positive integer.
If options.min_items is also configured, this key cannot be a lesser number.
This key has no default.
This key is available for Array and Multiselect or Multichoice Inputs.
Examples
In this example, we want to add an array of filepaths to our homepage's featured_posts Input. This Input limits you to a maximum of five array items.
_inputs:
featured_posts:
type: array
options:
max_items: 5
max_items_message: Cannot be more than 5
min_items: 2
min_items_message: Cannot be less than 2
This key defines a custom error message that explains why a value has failed the validation criteria from options.max_items.
This key requires you to define options.max_items.
This key has no default.
This key is available for Array and Multiselect or Multichoice Inputs.
Examples
In this example, we prompt our team to enter a valid number of items using a custom message.
_inputs:
featured_posts:
type: array
options:
max_items: 5
max_items_message: Cannot be more than 5
min_items: 2
min_items_message: Cannot be less than 2
This key defines the minimum number of items CloudCannon will allow in an Input.
When configured, CloudCannon will prevent you from removing items from this Input below this value.
If the Input already contains fewer items, CloudCannon will require you to add items until the Input contains a valid number to save your changes, or discard your unsaved changes.
Value can be any positive integer.
If options.min_items is also configured, this key cannot be a greater number.
This key has no default.
This key is available for Array and Multiselect or Multichoice Inputs.
Examples
In this example, we want to add an array of filepaths to our homepage's featured_posts Input. This Input limits you to a maximum of two array items.
_inputs:
featured_posts:
type: array
options:
max_items: 5
max_items_message: Cannot be more than 5
min_items: 2
min_items_message: Cannot be less than 2
This key defines a custom error message that explains why a value has failed the validation criteria from options.min_items.
This key requires you to define options.min_items.
This key has no default.
This key is available for Array and Multiselect or Multichoice Inputs.
Examples
In this example, we prompt our team to enter a valid number of items using a custom message.
_inputs:
featured_posts:
type: array
options:
max_items: 5
max_items_message: Cannot be more than 5
min_items: 2
min_items_message: Cannot be less than 2
This key defines the JSON Path selector that CloudCannon should use to determine if the value of an Input is unique.
When configured, CloudCannon will require the value of the Input to be unique compared to the value defined on the JSON Path.
If the Input already contains a non-unique value, CloudCannon will require you to change it to a valid value to save your changes, or discard your unsaved changes.
Value must be a valid JSON Path.
This key has no default.
This key is available for Array inputs.
Examples
In this example, we want our team to add article filepaths to the related_articles Input. This Input requires all the filepaths to be unique.
_inputs:
related_articles:
type: array
options:
unique_on: '$.path'
related_articles:
- path: /articles/first-article.md
featured: true
- path: /articles/second-article.md
featured: false
This key defines a custom error message that explains why a value has failed the validation criteria from options.unique_on.
This key requires you to define options.unique_on.
This key has no default.
This key is available for Array inputs.
Examples
In this example, we want our team to add article filepaths to the related_articles Input. This Input requires all the filepaths to be unique.
_inputs:
related_articles:
type: array
options:
unique_on: '$.path'
unique_on_message: The value for path must be different for all items.
related_articles:
- path: /articles/first-article.md
featured: true
- path: /articles/first-article.md
featured: false
This key defines a user interface for a group of inputs.
This key defines the input type, which controls how this input appears and behaves.
This key defines the subtitle text above an Input.
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.
Examples
In this example, we want to add helpful guidance for our page_description Input.
_inputs:
page_description:
type: text
label: Page Description
comment: Enter a brief description of this page for search engines
Provides a custom link for documentation for editors shown above input.
This key defines the bold title text above an Input.
Examples
In this example, we want to customize the label for our page_title Input to be more descriptive.
_inputs:
page_title:
type: text
label: Article Title
comment: Enter the main title for this article
This key defines the visibility of an input in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Hidden inputs are useful when you want an input to exist, but not be visible or editable outside of the Source Editor.
Value can be a boolean or a string. A boolean value of true will hide the input.
A string value can hide an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key follows the input naming convention where key names beginning with an underscore are hidden true.
This key defines whether the value of an input is editable in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Disabled inputs are useful if you want CloudCannon to display the input value, but prevent team members from editing the value outside of the Source Editor.
The value of this key can be a boolean or a string. A boolean value of true will prevent team members from editing the value.
A string value can prevent team members from editing an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key is false (i.e., team members can edit input values).
Examples
In this example, we have configured the date_created Date 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
disabled: true
instance_value: NOW
options:
timezone: Etc/UTC
This key defines whether an input is automatically populated with a value when the input is created.
This occurs when creating a new file, or adding array items containing this input.
Valid values are UUID or NOW.
UUIDgenerates a uuidv4 key (extremely unlikely to generate duplicates), useful for identifying unique items (e.g.6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b)NOWgenerates the current datetime in the Site's configured timezone
Examples
In this example, we have configured an input to automatically populate with a UUID when created.
_inputs:
id:
type: text
instance_value: UUID
This key toggles whether CloudCannon will rehydrate inputs configured with an instance_value with a new value when duplicated.
Setting this key to true will prevent rehydration of instance values when inputs are duplicated.
Examples
In this example, CloudCannon will prevent rehydration of instance values when inputs are duplicated.
_inputs:
id:
type: text
instance_value: UUID
disable_instance_value_rehydration: true
This key defines whether CloudCannon should merge this input configuration with any matching, less specific configurations elsewhere in the configuration cascade.
The configuration cascade works by finding the most specific _inputs entry.
Usually, once an option is found in the cascade, there's no reason to keep looking.
When this key is true, the cascade continues looking and each entry found is merged.
This key allows you to define some options globally while using specific options for other keys at different levels of the cascade.
For example, define a comment globally, but use collection-specific label for inputs in different collections.
You can stop the cascade at any point in the configuration cascade by setting cascade to false.
Examples
In this example, we have configured cascade to merge input configurations across the configuration cascade.
_inputs:
title:
type: text
cascade: true
comment: Global comment for all title inputs
This key defines options that are specific to Object Inputs.
11 nested properties
This key toggles whether CloudCannon requires this Input to have a value.
Setting this key to true will require you to enter a value to save your changes, or discard your unsaved changes.
By default, this key is false (i.e., CloudCannon does not require this Input to have a value).
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we want to require our team to enter an author value for markup files with this Input.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
This key defines a custom error message that explains why a value has failed the validation criteria from options.required.
This key requires you to define options.required.
This key has no default.
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to use enter an Input value using a required message.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
required_message: You are not allowed to leave this blank.
This key defines the appearance and behavior of the input.
This key defines the appearance and function of entries in a mutable Object Input.
The value is an object that can contain optional allowed_keys, structures, assigned_structures, comment, and documentation keys.
Available for Mutable Objects only.
Examples
In this example, we have configured entries options with assigned structures for specific allowed keys.
_inputs:
metadata:
type: object
options:
allow_create: true
entries:
allowed_keys:
- title
assigned_structures:
title:
- article_metadata
- page_metadata
5 nested properties
This key defines a limited set of key names for nested keys within your Object Input.
The value is an array of key name strings. This affects entries when adding or renaming nested keys.
This set is used when entries are added and renamed with allow_create enabled. Has no effect if allow_create is not enabled.
Available for Mutable Objects only.
By default, this key is [].
Examples
In this example, we have configured an allowed key name for entries in a mutable Object Input.
_inputs:
metadata:
type: object
options:
allow_create: true
entries:
allowed_keys:
- title
This key defines how to assign structures to specific key names for entries in the Object Input.
The value is an object where each property key is an allowed key name, and each property value is an array of structure key name strings. When selecting an entry key name, CloudCannon will prompt team members to choose one of the assigned structures for that allowed key. Structure values are referred to by their id.
Available for Mutable Objects only.
This key defines which predefined templates to use for populating entries nested in the Object Input.
The value can be a string or an object. When configured, team members can select a structure to populate the Object with input/input groups.
If configured as an object, CloudCannon will use the values directly. If configured as a string, CloudCannon will use the matching structures value defined under _structures in the configuration cascade.
Available for Mutable Objects only.
Note: This key looks similar to
structures. However, thestructureskey applies to the Object input itself, whileentries.structuresapplies to the entries within the object.
This key has no default.
This key defines the subtitle text above the key input when adding or renaming entries within a mutable Object Input.
The value is a string that supports a limited selection of Markdown formatting: links, bold, italic, subscript, superscript, and inline code elements are allowed.
Available for Mutable Objects only.
Examples
In this example, we have configured a comment with Markdown formatting to provide help text above the key input.
_inputs:
metadata:
type: object
options:
allow_create: true
entries:
comment: Key names should be **lowercase** and use underscores (e.g., `article_title`)
Provides a custom link for documentation for editors shown above the key input when adding/renaming within a mutable object input.
This key defines how you can group the inputs inside this object together without changing the data structure.
This key defines which order input groups and ungrouped inputs appear in.
This key toggles whether labels on mutable object entries are formatted.
Setting this key to true will format labels on mutable object entries.
By default, this key is false (i.e., labels are not formatted).
This key defines how object previews are rendered.
This key defines data formats for value of this object.
When choosing an item, team members are prompted to choose from a number of values you have defined. structures applies to the object itself.
This key defines how an 'empty' value will be saved. Does not apply to existing empty values.
Examples
In this example, we have configured how empty object values will be saved.
_inputs:
metadata:
type: object
options:
empty_type: object
A reference to an existing structure.
This key defines data formats when adding new items to arrays and objects, with options for how editors choose from available values.
This key defines the options available for a Structure.
You must define this key for the Structure to function.
This key has no default.
Examples
In this example, we want to add the title, subtitle, author, featured_image, and url fields to Object or Array inputs that reference this Structure.
_structures:
related_articles:
values:
- label: Blog
id:
default: true
tabbed: false
tags:
- blog
value:
title:
subtitle:
author:
featured_image:
url:
_inputs:
featured_image:
type: image
options:
width: 50
height: 50
groups:
- heading: Titles
inputs:
- title
- subtitle
- heading: Details
inputs:
- author
- image
- url
preview:
text:
- template: "{title}"
subtext:
- template: "By {author}"
image:
- key: image
picker_preview:
text: Blog
subtext: Add a related blog
icon: post_add
This key toggles whether CloudCannon will reorder inputs in a file to match the order defined in a given Structure.
Setting this key to false will preserve the existing order of inputs in a file, regardless of the order defined in the Structure.
By default, this key is true (i.e., inputs are reordered to match the Structure).
You can also configure this behavior for specific values of a Structure using values[*].reorder_inputs.
Examples
In this example, we want to preserve the order of the inputs in a file over the order in the associated Structure.
_structures:
related_articles:
reorder_inputs: false
values:
- value:
name:
description:
url:
This key toggles whether CloudCannon will hide inputs that are not present in a Structure from the Data Editor.
Setting this key to true will hide inputs that are not present in a Structure from the Data Editor. Hiding these inputs does not delete the data. You can see non-structure data keys by opening a file in the Source Editor. This key has no effect if remove_extra_inputs is true.
You can also configure this behavior for specific values of a Structure using values[*].hide_extra_inputs.
Examples
In this example, we don't want inputs outside of those listed in the Structure (e.g., old inputs from deprecated versions of this Structure) to appear in the Data Editor.
_structures:
related_articles:
hide_extra_inputs: true
values:
- value:
name:
description:
url:
This key toggles whether CloudCannon will remove empty nested inputs from an Object Input or Array Input using a given Structure before persisting them to your file.
Setting this key to true will remove empty nested inputs from an Object Input or Array Input using a given Structure before persisting
them to your file. CloudCannon considers an input to be empty when its value is null, ' ', or undefined. If this key is true, empty inputs will be visible in the Data Editor but not the Source
Editor. For this key to function, you must also configure id_key for the Structure, as removing inputs prevents CloudCannon from comparing Structure values.
By default, this key is false (i.e., CloudCannon does not remove empty inputs).
You can also configure this behavior for specific values of a Structure using structure.values.[*].remove_empty_inputs.
Examples
In this example, we want to delete any unnecessary nested inputs (i.e., input we choose not to provide a value for) from Object or Array inputs referenceing the event_details Structure.
_structures:
event_details:
remove_empty_inputs: true
values:
- value:
name:
description:
url:
time:
place:
sponsor:
This key toggles whether CloudCannon will remove inputs that are not present in a Structure from a file before loading it in an Editing Interface.
Setting this key to true will remove inputs that are not present in a Structure from a file before loading it in an Editing Interface. Non-Structure inputs will not be visible in the Visual Editor, Content
Editor, or Data Editor, and saving the file
will remove them from the file before persisting the changes to your Git repository.
You can also configure this behavior for specific values of a Structure using values[*].remove_extra_inputs.
Examples
In this example, we want to delete old inputs that are not in the Structure from the associated file.
_structures:
related_articles:
remove_extra_inputs: true
values:
- value:
name:
description:
url:
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.
Examples
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:
label: Board
value:
name:
title:
profile_picture:
url:
description:
This key defines which key within values[*].value CloudCannon should use to identify the Structure option.
If CloudCannon cannot find this key in a Structure value, it will compare all other key names in the Structure value to find the correct one.
By default, this key is _type.
Examples
In this example, we have change the id_key from the default _type to component to match our existing configuration in the content_blocks Array input.
_inputs:
content_blocks___1___:
type: array
options:
structures: _structures.page_components
_structures:
page_components:
id_key___2___: component
values:
- label: Hero Component
value:
component___3___: hero
title:
description:
image_path:
link:
text:
url:
- label: Feature Component
value:
component: feature
image_path:
title:
description:
button:
link:
text:
reversed_layout: false
- label: Video Component
value:
component: video
image_path:
videoUrl:
This key defines how CloudCannon shows Structure options to populate an Object or Array input.
This can be using a select-style search bar or a pop-up modal.
Modals are useful when you have several value options for your Structure.
Values can be one of the following: select, or modal.
Examples
In this example, the related_articles Structure only has one option so a select searchbar is appropriate.
_structures:
related_articles:
style: select
values:
- value:
name:
description:
url:
This key represents a single value option within a structure, defining the data format and appearance for content editors.
This key defines which nested inputs the Structure value should add to an Object or Array input.
You must define this key for the Structure value to function.
Nested keys can be any input you require in your Object or Array.
For more information, please read our documentation on configuring an Object input and configuring and Array input.
Examples
In this example we want to populate the details Object input with the nested keys title, subtitle, and author we have defined under the values.value key.
_structures:
article_information:
values:
- label: Blog
value:
title:
subtitle:
author:
_inputs:
details:
type: object
options:
structures: _structures.article_information
This key toggles whether CloudCannon will reorder inputs in a file to match the order defined in a given value from a Structure.
Setting this key to false will preserve the existing order of inputs in a file, regardless of the order defined in the Structure value.
By default, this key is true (i.e., inputs are reordered to match the Structure value).
You can also configure this behavior for all values of a Structure using reorder_inputs inside _structures.*.
This key toggles whether CloudCannon will hide inputs that are not present in a given value from a Structure from the Data Editor.
Setting this key to true will hide inputs that are not present in a given value from a Structure from the Data Editor. Hiding these inputs does not delete the data. You can see non-structure data keys by opening a file in the Source Editor. This key has no effect if remove_extra_inputs is true.
You can also configure this behavior for all values of a Structure using hide_extra_inputs inside _structures.*.
This key toggles whether CloudCannon will remove empty nested inputs from an Object Input or Array Input using a given value from a Structure before persisting them to your file.
Setting this key to true will remove empty nested inputs from an Object Input or Array Input using a given value from a Structure before
persisting them to your file. CloudCannon considers an input to be empty when its value is null, ' ', or undefined. If this key is true, empty inputs will be visible in the Data Editor but not the Source
Editor. For this key to function, you must also configure id_key for the Structure, as removing inputs prevents CloudCannon from comparing Structure values.
You can also configure this behavior for all values of a Structure using remove_empty_inputs inside _structures.*.
This key toggles whether CloudCannon will remove inputs that are not present in a given value from a Structure from a file before loading it in an Editing Interface.
Setting this key to true will remove inputs that are not present in a given value from a Structure from a file before loading it in an Editing Interface. Non-Structure inputs will not be visible in the Visual Editor, Content
Editor, or Data Editor, and saving the file
will remove them from the file before persisting the changes to your Git repository.
You can also configure this behavior for all values of a Structure using remove_extra_inputs inside _structures.*.
This key defines the string used to identify a given Structure value when refering to it from other input configuration.
Examples
In this example, we have configured the blog_post ID for the entry labeled Blog in the article_information Structure.
_structures:
article_information:
values:
- label: Blog
id: blog_post
This key toggles whether CloudCannon should treat an entry in the values array as the default option for your Object or Array input.
Setting this key to true will mark this entry as the default option for your Object or Array input. If multiple entries in the values array are set to true, CloudCannon will use the first entry. If CloudCannon cannot determine the type of an entry within the values array based on the id_key or matching inputs across values[*].value objects,
it will fall back to the default entry.
Examples
In this example, we want the entry labelled Employee to be our default option for populating inputs configured with the staff Structure.
_structures:
staff:
style: modal
values:
- label: Employee
default: true
value:
name:
job_description:
profile_picture:
- label: Manager
value:
name:
job_description:
profile_picture:
url:
This key defines an icon used when displaying the structure (defaults to either format_list_bulleted for items in arrays, or notes otherwise).
Examples
In this example, CloudCannon will display the article icon for the entry labeled Blog in the article_information Structure.
_structures:
article_information:
values:
- label: Blog
icon: article
This key defines the path to an image in your source files used when displaying the structure value.
Can be either a source (has priority) or output path.
Examples
In this example, we have configured the /images/blog-icon.png image for the entry labeled Blog in the article_information Structure.
_structures:
article_information:
values:
- label: Blog
image: /images/blog-icon.png
This key defines the display name for a given value in a Structure.
The name will appear in the + Add button dropdown below an Object or Array input or in the Structures modal (if configured).
By default, this key falls back to unknown.
Examples
In this example, we want two value options for our staff structure: one called Manager and one called Employee.
_structures:
staff:
values:
- label: Employee
value:
name:
job_description:
profile_picture:
- label: Manager
value:
name:
job_description:
profile_picture:
url:
This key defines which tags are associated with a given value in a Structure.
You can use tags to group and filter Structure options when selecting from a modal.
This key has no default.
Examples
In this example we have three options for the page_components Structure: Hero Component, Feature Component, and Video Component. We can search the Structure modal using the image, text, button, and video tags to filter Structure values.
_structures:
page_components:
style: modal
values:
- label: Hero Component
tags:
- image
- text
value:
title:
description:
image_path:
link:
text:
url:
- label: Feature Component
tags:
- image
- text
- button
value:
image_path:
title:
description:
button:
link:
text:
reversed_layout: false
- label: Video Component
tags:
- image
- video
value:
image_path:
videoUrl:
This key defines the order and custom grouping for inputs within a Structure.
The value is an array of group objects. Each group object can contain a heading, comment, collapsed, and inputs array.
Examples
In this example, we want to separate the inputs into two groups with descriptive headings: title and subtitle under the Titles heading, and author under the Details heading.
_structures:
article_information:
values:
- label: Blog
value:
title:
subtitle:
author:
groups:
- heading: Titles
inputs:
- title
- subtitle
- heading: Details
inputs:
- author
This key defines which order input groups and ungrouped inputs appear in.
This key toggles whether CloudCannon should create tabs in the Data Editor if you have two layers of nested object within your Structure.
Setting this key to true will create tabs in the Data Editor for two layers of nested objects within your Structure.
By default, this key is false (i.e., Object and Array inputs using this Structure option are not tabbed).
Examples
In this example, we want the content and style keys in our Structure to be tabs at the top of the Data Editor, with the title and text, and color and font keys nested within those tabs respectively.
_structures:
components:
values:
- label: Component
tabbed: true
value:
content:
title:
text:
style:
color:
font:
This key defines short descriptive text for editors shown in the Data Editor for expanded values matching this Structure value.
Has no default.
Supports a limited set of Markdown: links, bold, italic, subscript, superscript, and inline code elements are allowed.
Provides a custom link for documentation for editors shown in the Data Editor for expanded values matching this Structure value. Has no default.
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.
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.
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
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.
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
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.
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:
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
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.
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.
_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:
This key defines the subtitle text above the key input when adding or renaming entries within a mutable Object Input.
The value is a string that supports a limited selection of Markdown formatting: links, bold, italic, subscript, superscript, and inline code elements are allowed.
Available for Mutable Objects only.
Examples
In this example, we have configured a comment with Markdown formatting to provide help text above the key input.
_inputs:
metadata:
type: object
options:
allow_create: true
entries:
comment: Key names should be **lowercase** and use underscores (e.g., `article_title`)
This key defines a user interface for lists of inputs or input groups.
This key defines the input type, which controls how this input appears and behaves.
This key defines the subtitle text above an Input.
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.
Examples
In this example, we want to add helpful guidance for our page_description Input.
_inputs:
page_description:
type: text
label: Page Description
comment: Enter a brief description of this page for search engines
Provides a custom link for documentation for editors shown above input.
This key defines the bold title text above an Input.
Examples
In this example, we want to customize the label for our page_title Input to be more descriptive.
_inputs:
page_title:
type: text
label: Article Title
comment: Enter the main title for this article
This key defines the visibility of an input in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Hidden inputs are useful when you want an input to exist, but not be visible or editable outside of the Source Editor.
Value can be a boolean or a string. A boolean value of true will hide the input.
A string value can hide an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key follows the input naming convention where key names beginning with an underscore are hidden true.
This key defines whether the value of an input is editable in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Disabled inputs are useful if you want CloudCannon to display the input value, but prevent team members from editing the value outside of the Source Editor.
The value of this key can be a boolean or a string. A boolean value of true will prevent team members from editing the value.
A string value can prevent team members from editing an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key is false (i.e., team members can edit input values).
Examples
In this example, we have configured the date_created Date 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
disabled: true
instance_value: NOW
options:
timezone: Etc/UTC
This key defines whether an input is automatically populated with a value when the input is created.
This occurs when creating a new file, or adding array items containing this input.
Valid values are UUID or NOW.
UUIDgenerates a uuidv4 key (extremely unlikely to generate duplicates), useful for identifying unique items (e.g.6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b)NOWgenerates the current datetime in the Site's configured timezone
Examples
In this example, we have configured an input to automatically populate with a UUID when created.
_inputs:
id:
type: text
instance_value: UUID
This key toggles whether CloudCannon will rehydrate inputs configured with an instance_value with a new value when duplicated.
Setting this key to true will prevent rehydration of instance values when inputs are duplicated.
Examples
In this example, CloudCannon will prevent rehydration of instance values when inputs are duplicated.
_inputs:
id:
type: text
instance_value: UUID
disable_instance_value_rehydration: true
This key defines whether CloudCannon should merge this input configuration with any matching, less specific configurations elsewhere in the configuration cascade.
The configuration cascade works by finding the most specific _inputs entry.
Usually, once an option is found in the cascade, there's no reason to keep looking.
When this key is true, the cascade continues looking and each entry found is merged.
This key allows you to define some options globally while using specific options for other keys at different levels of the cascade.
For example, define a comment globally, but use collection-specific label for inputs in different collections.
You can stop the cascade at any point in the configuration cascade by setting cascade to false.
Examples
In this example, we have configured cascade to merge input configurations across the configuration cascade.
_inputs:
title:
type: text
cascade: true
comment: Global comment for all title inputs
This key defines options that are specific to Array Inputs.
13 nested properties
This key toggles whether CloudCannon requires this Input to have a value.
Setting this key to true will require you to enter a value to save your changes, or discard your unsaved changes.
By default, this key is false (i.e., CloudCannon does not require this Input to have a value).
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we want to require our team to enter an author value for markup files with this Input.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
This key defines a custom error message that explains why a value has failed the validation criteria from options.required.
This key requires you to define options.required.
This key has no default.
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Examples
In this example, we prompt our team to use enter an Input value using a required message.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
required_message: You are not allowed to leave this blank.
This key defines the maximum number of items CloudCannon will allow in an Input.
When configured, CloudCannon will prevent you from adding more items to this Input.
If the Input already contains more items, CloudCannon will require you to remove items until the Input contains a valid number to save your changes, or discard your unsaved changes.
Value can be any positive integer.
If options.min_items is also configured, this key cannot be a lesser number.
This key has no default.
This key is available for Array and Multiselect or Multichoice Inputs.
Examples
In this example, we want to add an array of filepaths to our homepage's featured_posts Input. This Input limits you to a maximum of five array items.
_inputs:
featured_posts:
type: array
options:
max_items: 5
max_items_message: Cannot be more than 5
min_items: 2
min_items_message: Cannot be less than 2
This key defines a custom error message that explains why a value has failed the validation criteria from options.max_items.
This key requires you to define options.max_items.
This key has no default.
This key is available for Array and Multiselect or Multichoice Inputs.
Examples
In this example, we prompt our team to enter a valid number of items using a custom message.
_inputs:
featured_posts:
type: array
options:
max_items: 5
max_items_message: Cannot be more than 5
min_items: 2
min_items_message: Cannot be less than 2
This key defines the minimum number of items CloudCannon will allow in an Input.
When configured, CloudCannon will prevent you from removing items from this Input below this value.
If the Input already contains fewer items, CloudCannon will require you to add items until the Input contains a valid number to save your changes, or discard your unsaved changes.
Value can be any positive integer.
If options.min_items is also configured, this key cannot be a greater number.
This key has no default.
This key is available for Array and Multiselect or Multichoice Inputs.
Examples
In this example, we want to add an array of filepaths to our homepage's featured_posts Input. This Input limits you to a maximum of two array items.
_inputs:
featured_posts:
type: array
options:
max_items: 5
max_items_message: Cannot be more than 5
min_items: 2
min_items_message: Cannot be less than 2
This key defines a custom error message that explains why a value has failed the validation criteria from options.min_items.
This key requires you to define options.min_items.
This key has no default.
This key is available for Array and Multiselect or Multichoice Inputs.
Examples
In this example, we prompt our team to enter a valid number of items using a custom message.
_inputs:
featured_posts:
type: array
options:
max_items: 5
max_items_message: Cannot be more than 5
min_items: 2
min_items_message: Cannot be less than 2
This key defines the JSON Path selector that CloudCannon should use to determine if the value of an Input is unique.
When configured, CloudCannon will require the value of the Input to be unique compared to the value defined on the JSON Path.
If the Input already contains a non-unique value, CloudCannon will require you to change it to a valid value to save your changes, or discard your unsaved changes.
Value must be a valid JSON Path.
This key has no default.
This key is available for Array inputs.
Examples
In this example, we want our team to add article filepaths to the related_articles Input. This Input requires all the filepaths to be unique.
_inputs:
related_articles:
type: array
options:
unique_on: '$.path'
related_articles:
- path: /articles/first-article.md
featured: true
- path: /articles/second-article.md
featured: false
This key defines a custom error message that explains why a value has failed the validation criteria from options.unique_on.
This key requires you to define options.unique_on.
This key has no default.
This key is available for Array inputs.
Examples
In this example, we want our team to add article filepaths to the related_articles Input. This Input requires all the filepaths to be unique.
_inputs:
related_articles:
type: array
options:
unique_on: '$.path'
unique_on_message: The value for path must be different for all items.
related_articles:
- path: /articles/first-article.md
featured: true
- path: /articles/first-article.md
featured: false
This key toggles whether CloudCannon will hide the add button, and context menu actions on each item for adding new items to this Input.
Setting this key to true will hide the add button and context menu actions for adding new items.
By default, this key is false (i.e., the add button and context menu actions are displayed).
This key toggles whether CloudCannon will hide the context menu actions on each item for removing them.
Setting this key to true will hide the context menu actions for removing items.
By default, this key is false (i.e., the context menu actions for removing items are displayed).
This key toggles whether CloudCannon will hide the controls on each item for moving them.
Setting this key to true will hide the controls for moving items.
By default, this key is false (i.e., the controls for moving items are displayed).
This key defines data formats for value of this object.
When choosing an item, team members are prompted to choose from a number of values you have defined.
This key toggles whether CloudCannon will hide the add button, and context menu actions on each item for adding new items to this Input.
Setting this key to true will hide the add button and context menu actions for adding new items.
By default, this key is false (i.e., the add button and context menu actions are displayed).
This key toggles whether CloudCannon will hide the context menu actions on each item for removing them.
Setting this key to true will hide the context menu actions for removing items.
By default, this key is false (i.e., the context menu actions for removing items are displayed).
This key toggles whether CloudCannon will hide the controls on each item for moving them.
Setting this key to true will hide the controls for moving items.
By default, this key is false (i.e., the controls for moving items are displayed).
Provides a default user interface based on the data contained.
Sets an input type, which controls how this input appears and behaves.
This key defines the subtitle text above an Input.
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.
Examples
In this example, we want to add helpful guidance for our page_description Input.
_inputs:
page_description:
type: text
label: Page Description
comment: Enter a brief description of this page for search engines
Provides a custom link for documentation for editors shown above input.
This key defines the bold title text above an Input.
Examples
In this example, we want to customize the label for our page_title Input to be more descriptive.
_inputs:
page_title:
type: text
label: Article Title
comment: Enter the main title for this article
This key defines the visibility of an input in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Hidden inputs are useful when you want an input to exist, but not be visible or editable outside of the Source Editor.
Value can be a boolean or a string. A boolean value of true will hide the input.
A string value can hide an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key follows the input naming convention where key names beginning with an underscore are hidden true.
This key defines whether the value of an input is editable in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Disabled inputs are useful if you want CloudCannon to display the input value, but prevent team members from editing the value outside of the Source Editor.
The value of this key can be a boolean or a string. A boolean value of true will prevent team members from editing the value.
A string value can prevent team members from editing an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key is false (i.e., team members can edit input values).
Examples
In this example, we have configured the date_created Date 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
disabled: true
instance_value: NOW
options:
timezone: Etc/UTC
This key defines whether an input is automatically populated with a value when the input is created.
This occurs when creating a new file, or adding array items containing this input.
Valid values are UUID or NOW.
UUIDgenerates a uuidv4 key (extremely unlikely to generate duplicates), useful for identifying unique items (e.g.6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b)NOWgenerates the current datetime in the Site's configured timezone
Examples
In this example, we have configured an input to automatically populate with a UUID when created.
_inputs:
id:
type: text
instance_value: UUID
This key toggles whether CloudCannon will rehydrate inputs configured with an instance_value with a new value when duplicated.
Setting this key to true will prevent rehydration of instance values when inputs are duplicated.
Examples
In this example, CloudCannon will prevent rehydration of instance values when inputs are duplicated.
_inputs:
id:
type: text
instance_value: UUID
disable_instance_value_rehydration: true
This key defines whether CloudCannon should merge this input configuration with any matching, less specific configurations elsewhere in the configuration cascade.
The configuration cascade works by finding the most specific _inputs entry.
Usually, once an option is found in the cascade, there's no reason to keep looking.
When this key is true, the cascade continues looking and each entry found is merged.
This key allows you to define some options globally while using specific options for other keys at different levels of the cascade.
For example, define a comment globally, but use collection-specific label for inputs in different collections.
You can stop the cascade at any point in the configuration cascade by setting cascade to false.
Examples
In this example, we have configured cascade to merge input configurations across the configuration cascade.
_inputs:
title:
type: text
cascade: true
comment: Global comment for all title inputs
Options that are specific to this type of input.
Provides a default user interface based on the data contained.
This key defines the subtitle text above an Input.
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.
Examples
In this example, we want to add helpful guidance for our page_description Input.
_inputs:
page_description:
type: text
label: Page Description
comment: Enter a brief description of this page for search engines
Provides a custom link for documentation for editors shown above input.
This key defines the bold title text above an Input.
Examples
In this example, we want to customize the label for our page_title Input to be more descriptive.
_inputs:
page_title:
type: text
label: Article Title
comment: Enter the main title for this article
This key defines the visibility of an input in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Hidden inputs are useful when you want an input to exist, but not be visible or editable outside of the Source Editor.
Value can be a boolean or a string. A boolean value of true will hide the input.
A string value can hide an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key follows the input naming convention where key names beginning with an underscore are hidden true.
This key defines whether the value of an input is editable in the Data Editor or the sidebar of the Visual Editor or Content Editor.
Disabled inputs are useful if you want CloudCannon to display the input value, but prevent team members from editing the value outside of the Source Editor.
The value of this key can be a boolean or a string. A boolean value of true will prevent team members from editing the value.
A string value can prevent team members from editing an input based on the value of another input.
You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key is false (i.e., team members can edit input values).
Examples
In this example, we have configured the date_created Date 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
disabled: true
instance_value: NOW
options:
timezone: Etc/UTC
This key defines whether an input is automatically populated with a value when the input is created.
This occurs when creating a new file, or adding array items containing this input.
Valid values are UUID or NOW.
UUIDgenerates a uuidv4 key (extremely unlikely to generate duplicates), useful for identifying unique items (e.g.6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b)NOWgenerates the current datetime in the Site's configured timezone
Examples
In this example, we have configured an input to automatically populate with a UUID when created.
_inputs:
id:
type: text
instance_value: UUID
This key toggles whether CloudCannon will rehydrate inputs configured with an instance_value with a new value when duplicated.
Setting this key to true will prevent rehydration of instance values when inputs are duplicated.
Examples
In this example, CloudCannon will prevent rehydration of instance values when inputs are duplicated.
_inputs:
id:
type: text
instance_value: UUID
disable_instance_value_rehydration: true
This key defines whether CloudCannon should merge this input configuration with any matching, less specific configurations elsewhere in the configuration cascade.
The configuration cascade works by finding the most specific _inputs entry.
Usually, once an option is found in the cascade, there's no reason to keep looking.
When this key is true, the cascade continues looking and each entry found is merged.
This key allows you to define some options globally while using specific options for other keys at different levels of the cascade.
For example, define a comment globally, but use collection-specific label for inputs in different collections.
You can stop the cascade at any point in the configuration cascade by setting cascade to false.
Examples
In this example, we have configured cascade to merge input configurations across the configuration cascade.
_inputs:
title:
type: text
cascade: true
comment: Global comment for all title inputs
Options that are specific to this type of input.
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.
Examples
In this example, we have enabled only the Content Editor in the blog Collection.
collections_config:
blog:
_enabled_editors:
- content
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.
Examples
In this example, we have configured the Snippet tool for WYSIWYG toolbars in the blog Collection.
collections_config:
blog:
_editables:
content:
snippet: true
This key defines input options for the Content Editor.
44 nested properties
This key defines what format an image is converted to prior to upload.
Examples
In this example, we have configured an Image Input to convert images to WebP format prior to upload.
_inputs:
hero_image:
type: image
options:
mime_type: image/webp
This key defines how image files are resized prior to upload, using a bounding box defined by width and height options.
Valid values are cover, contain, crop, or stretch:
coverkeeps aspect ratio and ensures the image covers the bounding boxcontainkeeps aspect ratio and ensures the image fits inside the bounding boxcropprompts the user with and interface to select an aspect-ratio-respecting areastretchignores aspect ratio and resizes the image to the bounding box
This key does not apply to existing images, and does not work if width and height options are not defined.
Examples
In this example, we have configured an Image Input to resize images using the cover style to ensure images cover the bounding box while maintaining aspect ratio.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines the width of the bounding box used in the resizing method defined by resize_style.
This key defines the height of the bounding box used in the resizing method defined by resize_style.
Examples
In this example, we have configured the height of the bounding box for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines whether you can upscale an image to fit the bounding box while resizing an image prior to upload.
Has no effect if files are not resized.
Examples
In this example, we have configured an Image Input to allow upscaling images to fit the bounding box while resizing.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
expandable: true
This key toggles whether CloudCannon will instruct a rich text editor to save width and height attributes on image elements.
Setting this key to true will instruct the rich text editor to save width and height attributes on image elements. This can prevent pop-in as a page loads.
By default, this key is false (i.e., width and height attributes are not saved on image elements). This defaults to true if the Image Size Attributes site flag is enabled (this is enabled for sites created before June 23 2023, in order to keep those sites working).
Examples
In this example, CloudCannon will save width and height attributes on image elements in a Rich Text Input.
_inputs:
content:
type: markdown
options:
image_size_attributes: true
This key defines which sources and DAMs you are allowed to upload to and browse.
The value can be an array of strings. Valid values include site-files and the reference key for any DAM connected to your site.
If site-files is omitted from the array, site files will not be available as an asset source for this input.
Examples
In this example, we have configured allowed sources for an Image Input.
_inputs:
image:
type: image
options:
allowed_sources:
- site-files
- my-cloudinary-dam
This key toggles whether CloudCannon will skip the image resizing process configured for this input when selecting existing images.
Setting this key to true will skip the image resizing process when selecting existing images.
Examples
In this example, CloudCannon will skip the image resizing process when selecting existing images for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
prevent_resize_existing_files: true
This key defines definitions for creating additional images of different sizes when uploading or selecting existing files.
Examples
In this example, we have configured an Image Input to create additional images of different sizes when uploading or selecting files.
_inputs:
hero_image:
type: image
options:
sizes:
- size: 2x
- size: 3x
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to bold selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to bold selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to copy formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to copy formatting from selected text. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not copy other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to italicize selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to italicize selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to redo recent edits undone with undo.
Setting this key to true will enable a tool in your WYSIWYG toolbar to redo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to remove formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to remove formatting. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not remove other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to strike through selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to strike through selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to subscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to subscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to superscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to superscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to underline selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to underline selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to undo recent edits.
Setting this key to true will enable a tool in your WYSIWYG toolbar to undo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will allow you to strip custom markup from content edited in a rich text editor, allowing you to clean files of unnecessary HTML content.
Setting this key to true will enable stripping custom markup from content. The remove_custom_markup key is disabled if allow_custom_markup is enabled.
This key toggles whether CloudCannon will allow you to edit custom markup in rich text editors and explicitly accept the risk of unintentionally deleting elements that cannot be recreated.
Setting this key to true will enable editing of custom markup. When using allow_custom_markup outside of editable regions, content that uses JavaScript will not be editable for security reasons. These inputs will appear as uneditable snippets.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to wrap selected blocks of text in a block quote.
Setting this key to true will enable a tool in your WYSIWYG toolbar to wrap selected blocks of text in a block quote.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an unordered list or convert selected text to an unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an unordered list or convert selected text to an unordered list.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to center align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to center align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a control in your WYSIWYG toolbar to create an inline code element, containing any selected text.
Setting this key to true will enable a control in your WYSIWYG toolbar to create an inline code element.
By default, this key is false (i.e., the inline code control is not displayed).
This key toggles whether CloudCannon will display a control in your WYSIWYG toolbar to insert a code block in editable regions.
Setting this key to true will enable a control in your WYSIWYG toolbar to insert a code block.
By default, this key is false (i.e., the code block control is not displayed).
This key toggles whether CloudCannon will display tools in your WYSIWYG toolbar to turn selected text into inline code and selected text into a code block.
Setting this key to true will enable two tools in your WYSIWYG toolbar to turn selected text into inline code and selected text into a code block.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a region of raw HTML for YouTube, Vimeo, social media posts, or other media.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a region of raw HTML. Embedded content is sanitized to mitigate XSS risks, which includes removing style tags. Embeds containing script tags are not loaded a rich text editor.
This key toggles whether CloudCannon will display a dropdown menu tool in your WYSIWYG toolbar for structured text.
Setting this key to true will enable a dropdown menu tool in your WYSIWYG toolbar for structured text. Valid values include for p, h1, h2, h3, h4, h5, h6, pre, address, and div. Include a space between each values, e.g. format: p h1 h2.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a horizontal line.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a horizontal line.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an image and enter alternative text and title text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an image. Select an existing image, upload an image, or use an external link.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to increase the indentation of a list item in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to increase the indentation of a list item.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to justify selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to justify selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to left align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to left align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an ordered list or convert selected text to an ordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an ordered list or convert selected text to an ordered list.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to decrease the indentation of a list item in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to decrease the indentation of a list item.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to right align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to right align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a Snippet, if any are available.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a Snippet.
This key toggles whether CloudCannon will display a dropdown menu in your WYSIWYG toolbar to apply a style to selected text.
Examples
In this example, we have enabled a dropdown menu in our WYSIWYG toolbar to apply a style to selected text. The styles are defined in the /css/styles.css file.
_editables:
content:
styles: /css/styles.css
This example file defines the styles that CloudCannon can add to your WYSIWYG toolbar.
/* Can be applied to blocks of content */
p.callout {
margin: 10px;
border: 1px solid #f5f5f5;
background-color: #eee;
}
/* Can be applied to inline content */
span.big-blue-text {
font-size: 2rem;
color: blue;
}
/* Applied to content, excluded from style dropdown */
h2 {
font-family: cursive;
}
/* Applied to content, excluded from style dropdown */
.align-left { text-align: left; }
.align-center { text-align: center; }
.align-right { text-align: right; }
.align-justify { text-align: justify; }
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a table.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a table. Further table options are available from the table context menu in the rich text editor.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to merge a list item with the item above it in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to merge a list item with the item above it.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to merge a list item with the item below it in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to merge a list item with the item below it.
This key defines input options for block Editable Regions.
44 nested properties
This key defines what format an image is converted to prior to upload.
Examples
In this example, we have configured an Image Input to convert images to WebP format prior to upload.
_inputs:
hero_image:
type: image
options:
mime_type: image/webp
This key defines how image files are resized prior to upload, using a bounding box defined by width and height options.
Valid values are cover, contain, crop, or stretch:
coverkeeps aspect ratio and ensures the image covers the bounding boxcontainkeeps aspect ratio and ensures the image fits inside the bounding boxcropprompts the user with and interface to select an aspect-ratio-respecting areastretchignores aspect ratio and resizes the image to the bounding box
This key does not apply to existing images, and does not work if width and height options are not defined.
Examples
In this example, we have configured an Image Input to resize images using the cover style to ensure images cover the bounding box while maintaining aspect ratio.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines the width of the bounding box used in the resizing method defined by resize_style.
This key defines the height of the bounding box used in the resizing method defined by resize_style.
Examples
In this example, we have configured the height of the bounding box for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines whether you can upscale an image to fit the bounding box while resizing an image prior to upload.
Has no effect if files are not resized.
Examples
In this example, we have configured an Image Input to allow upscaling images to fit the bounding box while resizing.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
expandable: true
This key toggles whether CloudCannon will instruct a rich text editor to save width and height attributes on image elements.
Setting this key to true will instruct the rich text editor to save width and height attributes on image elements. This can prevent pop-in as a page loads.
By default, this key is false (i.e., width and height attributes are not saved on image elements). This defaults to true if the Image Size Attributes site flag is enabled (this is enabled for sites created before June 23 2023, in order to keep those sites working).
Examples
In this example, CloudCannon will save width and height attributes on image elements in a Rich Text Input.
_inputs:
content:
type: markdown
options:
image_size_attributes: true
This key defines which sources and DAMs you are allowed to upload to and browse.
The value can be an array of strings. Valid values include site-files and the reference key for any DAM connected to your site.
If site-files is omitted from the array, site files will not be available as an asset source for this input.
Examples
In this example, we have configured allowed sources for an Image Input.
_inputs:
image:
type: image
options:
allowed_sources:
- site-files
- my-cloudinary-dam
This key toggles whether CloudCannon will skip the image resizing process configured for this input when selecting existing images.
Setting this key to true will skip the image resizing process when selecting existing images.
Examples
In this example, CloudCannon will skip the image resizing process when selecting existing images for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
prevent_resize_existing_files: true
This key defines definitions for creating additional images of different sizes when uploading or selecting existing files.
Examples
In this example, we have configured an Image Input to create additional images of different sizes when uploading or selecting files.
_inputs:
hero_image:
type: image
options:
sizes:
- size: 2x
- size: 3x
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to bold selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to bold selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to copy formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to copy formatting from selected text. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not copy other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to italicize selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to italicize selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to redo recent edits undone with undo.
Setting this key to true will enable a tool in your WYSIWYG toolbar to redo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to remove formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to remove formatting. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not remove other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to strike through selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to strike through selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to subscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to subscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to superscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to superscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to underline selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to underline selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to undo recent edits.
Setting this key to true will enable a tool in your WYSIWYG toolbar to undo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will allow you to strip custom markup from content edited in a rich text editor, allowing you to clean files of unnecessary HTML content.
Setting this key to true will enable stripping custom markup from content. The remove_custom_markup key is disabled if allow_custom_markup is enabled.
This key toggles whether CloudCannon will allow you to edit custom markup in rich text editors and explicitly accept the risk of unintentionally deleting elements that cannot be recreated.
Setting this key to true will enable editing of custom markup. When using allow_custom_markup outside of editable regions, content that uses JavaScript will not be editable for security reasons. These inputs will appear as uneditable snippets.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to wrap selected blocks of text in a block quote.
Setting this key to true will enable a tool in your WYSIWYG toolbar to wrap selected blocks of text in a block quote.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an unordered list or convert selected text to an unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an unordered list or convert selected text to an unordered list.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to center align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to center align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a control in your WYSIWYG toolbar to create an inline code element, containing any selected text.
Setting this key to true will enable a control in your WYSIWYG toolbar to create an inline code element.
By default, this key is false (i.e., the inline code control is not displayed).
This key toggles whether CloudCannon will display a control in your WYSIWYG toolbar to insert a code block in editable regions.
Setting this key to true will enable a control in your WYSIWYG toolbar to insert a code block.
By default, this key is false (i.e., the code block control is not displayed).
This key toggles whether CloudCannon will display tools in your WYSIWYG toolbar to turn selected text into inline code and selected text into a code block.
Setting this key to true will enable two tools in your WYSIWYG toolbar to turn selected text into inline code and selected text into a code block.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a region of raw HTML for YouTube, Vimeo, social media posts, or other media.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a region of raw HTML. Embedded content is sanitized to mitigate XSS risks, which includes removing style tags. Embeds containing script tags are not loaded a rich text editor.
This key toggles whether CloudCannon will display a dropdown menu tool in your WYSIWYG toolbar for structured text.
Setting this key to true will enable a dropdown menu tool in your WYSIWYG toolbar for structured text. Valid values include for p, h1, h2, h3, h4, h5, h6, pre, address, and div. Include a space between each values, e.g. format: p h1 h2.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a horizontal line.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a horizontal line.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an image and enter alternative text and title text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an image. Select an existing image, upload an image, or use an external link.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to increase the indentation of a list item in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to increase the indentation of a list item.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to justify selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to justify selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to left align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to left align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an ordered list or convert selected text to an ordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an ordered list or convert selected text to an ordered list.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to decrease the indentation of a list item in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to decrease the indentation of a list item.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to right align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to right align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a Snippet, if any are available.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a Snippet.
This key toggles whether CloudCannon will display a dropdown menu in your WYSIWYG toolbar to apply a style to selected text.
Examples
In this example, we have enabled a dropdown menu in our WYSIWYG toolbar to apply a style to selected text. The styles are defined in the /css/styles.css file.
_editables:
content:
styles: /css/styles.css
This example file defines the styles that CloudCannon can add to your WYSIWYG toolbar.
/* Can be applied to blocks of content */
p.callout {
margin: 10px;
border: 1px solid #f5f5f5;
background-color: #eee;
}
/* Can be applied to inline content */
span.big-blue-text {
font-size: 2rem;
color: blue;
}
/* Applied to content, excluded from style dropdown */
h2 {
font-family: cursive;
}
/* Applied to content, excluded from style dropdown */
.align-left { text-align: left; }
.align-center { text-align: center; }
.align-right { text-align: right; }
.align-justify { text-align: justify; }
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a table.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a table. Further table options are available from the table context menu in the rich text editor.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to merge a list item with the item above it in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to merge a list item with the item above it.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to merge a list item with the item below it in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to merge a list item with the item below it.
This key defines input options for link Editable Regions.
1 nested properties
This key defines input options for image Editable Regions.
10 nested properties
This key defines what format an image is converted to prior to upload.
Examples
In this example, we have configured an Image Input to convert images to WebP format prior to upload.
_inputs:
hero_image:
type: image
options:
mime_type: image/webp
This key defines how image files are resized prior to upload, using a bounding box defined by width and height options.
Valid values are cover, contain, crop, or stretch:
coverkeeps aspect ratio and ensures the image covers the bounding boxcontainkeeps aspect ratio and ensures the image fits inside the bounding boxcropprompts the user with and interface to select an aspect-ratio-respecting areastretchignores aspect ratio and resizes the image to the bounding box
This key does not apply to existing images, and does not work if width and height options are not defined.
Examples
In this example, we have configured an Image Input to resize images using the cover style to ensure images cover the bounding box while maintaining aspect ratio.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines the width of the bounding box used in the resizing method defined by resize_style.
This key defines the height of the bounding box used in the resizing method defined by resize_style.
Examples
In this example, we have configured the height of the bounding box for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines whether you can upscale an image to fit the bounding box while resizing an image prior to upload.
Has no effect if files are not resized.
Examples
In this example, we have configured an Image Input to allow upscaling images to fit the bounding box while resizing.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
expandable: true
This key toggles whether CloudCannon will instruct a rich text editor to save width and height attributes on image elements.
Setting this key to true will instruct the rich text editor to save width and height attributes on image elements. This can prevent pop-in as a page loads.
By default, this key is false (i.e., width and height attributes are not saved on image elements). This defaults to true if the Image Size Attributes site flag is enabled (this is enabled for sites created before June 23 2023, in order to keep those sites working).
Examples
In this example, CloudCannon will save width and height attributes on image elements in a Rich Text Input.
_inputs:
content:
type: markdown
options:
image_size_attributes: true
This key defines which sources and DAMs you are allowed to upload to and browse.
The value can be an array of strings. Valid values include site-files and the reference key for any DAM connected to your site.
If site-files is omitted from the array, site files will not be available as an asset source for this input.
Examples
In this example, we have configured allowed sources for an Image Input.
_inputs:
image:
type: image
options:
allowed_sources:
- site-files
- my-cloudinary-dam
This key toggles whether CloudCannon will skip the image resizing process configured for this input when selecting existing images.
Setting this key to true will skip the image resizing process when selecting existing images.
Examples
In this example, CloudCannon will skip the image resizing process when selecting existing images for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
prevent_resize_existing_files: true
This key defines definitions for creating additional images of different sizes when uploading or selecting existing files.
Examples
In this example, we have configured an Image Input to create additional images of different sizes when uploading or selecting files.
_inputs:
hero_image:
type: image
options:
sizes:
- size: 2x
- size: 3x
This key defines input options for text Editable Regions.
14 nested properties
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to bold selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to bold selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to copy formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to copy formatting from selected text. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not copy other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to italicize selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to italicize selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to redo recent edits undone with undo.
Setting this key to true will enable a tool in your WYSIWYG toolbar to redo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to remove formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to remove formatting. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not remove other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to strike through selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to strike through selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to subscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to subscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to superscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to superscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to underline selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to underline selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to undo recent edits.
Setting this key to true will enable a tool in your WYSIWYG toolbar to undo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will allow you to strip custom markup from content edited in a rich text editor, allowing you to clean files of unnecessary HTML content.
Setting this key to true will enable stripping custom markup from content. The remove_custom_markup key is disabled if allow_custom_markup is enabled.
This key toggles whether CloudCannon will allow you to edit custom markup in rich text editors and explicitly accept the risk of unintentionally deleting elements that cannot be recreated.
Setting this key to true will enable editing of custom markup. When using allow_custom_markup outside of editable regions, content that uses JavaScript will not be editable for security reasons. These inputs will appear as uneditable snippets.
This key defines input options for the Content Editor.
This key defines what format an image is converted to prior to upload.
Examples
In this example, we have configured an Image Input to convert images to WebP format prior to upload.
_inputs:
hero_image:
type: image
options:
mime_type: image/webp
This key defines how image files are resized prior to upload, using a bounding box defined by width and height options.
Valid values are cover, contain, crop, or stretch:
coverkeeps aspect ratio and ensures the image covers the bounding boxcontainkeeps aspect ratio and ensures the image fits inside the bounding boxcropprompts the user with and interface to select an aspect-ratio-respecting areastretchignores aspect ratio and resizes the image to the bounding box
This key does not apply to existing images, and does not work if width and height options are not defined.
Examples
In this example, we have configured an Image Input to resize images using the cover style to ensure images cover the bounding box while maintaining aspect ratio.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines the width of the bounding box used in the resizing method defined by resize_style.
This key defines the height of the bounding box used in the resizing method defined by resize_style.
Examples
In this example, we have configured the height of the bounding box for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines whether you can upscale an image to fit the bounding box while resizing an image prior to upload.
Has no effect if files are not resized.
Examples
In this example, we have configured an Image Input to allow upscaling images to fit the bounding box while resizing.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
expandable: true
This key toggles whether CloudCannon will instruct a rich text editor to save width and height attributes on image elements.
Setting this key to true will instruct the rich text editor to save width and height attributes on image elements. This can prevent pop-in as a page loads.
By default, this key is false (i.e., width and height attributes are not saved on image elements). This defaults to true if the Image Size Attributes site flag is enabled (this is enabled for sites created before June 23 2023, in order to keep those sites working).
Examples
In this example, CloudCannon will save width and height attributes on image elements in a Rich Text Input.
_inputs:
content:
type: markdown
options:
image_size_attributes: true
This key defines which sources and DAMs you are allowed to upload to and browse.
The value can be an array of strings. Valid values include site-files and the reference key for any DAM connected to your site.
If site-files is omitted from the array, site files will not be available as an asset source for this input.
Examples
In this example, we have configured allowed sources for an Image Input.
_inputs:
image:
type: image
options:
allowed_sources:
- site-files
- my-cloudinary-dam
This key toggles whether CloudCannon will skip the image resizing process configured for this input when selecting existing images.
Setting this key to true will skip the image resizing process when selecting existing images.
Examples
In this example, CloudCannon will skip the image resizing process when selecting existing images for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
prevent_resize_existing_files: true
This key defines definitions for creating additional images of different sizes when uploading or selecting existing files.
Examples
In this example, we have configured an Image Input to create additional images of different sizes when uploading or selecting files.
_inputs:
hero_image:
type: image
options:
sizes:
- size: 2x
- size: 3x
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to bold selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to bold selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to copy formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to copy formatting from selected text. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not copy other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to italicize selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to italicize selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to redo recent edits undone with undo.
Setting this key to true will enable a tool in your WYSIWYG toolbar to redo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to remove formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to remove formatting. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not remove other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to strike through selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to strike through selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to subscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to subscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to superscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to superscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to underline selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to underline selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to undo recent edits.
Setting this key to true will enable a tool in your WYSIWYG toolbar to undo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will allow you to strip custom markup from content edited in a rich text editor, allowing you to clean files of unnecessary HTML content.
Setting this key to true will enable stripping custom markup from content. The remove_custom_markup key is disabled if allow_custom_markup is enabled.
This key toggles whether CloudCannon will allow you to edit custom markup in rich text editors and explicitly accept the risk of unintentionally deleting elements that cannot be recreated.
Setting this key to true will enable editing of custom markup. When using allow_custom_markup outside of editable regions, content that uses JavaScript will not be editable for security reasons. These inputs will appear as uneditable snippets.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to wrap selected blocks of text in a block quote.
Setting this key to true will enable a tool in your WYSIWYG toolbar to wrap selected blocks of text in a block quote.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an unordered list or convert selected text to an unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an unordered list or convert selected text to an unordered list.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to center align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to center align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a control in your WYSIWYG toolbar to create an inline code element, containing any selected text.
Setting this key to true will enable a control in your WYSIWYG toolbar to create an inline code element.
By default, this key is false (i.e., the inline code control is not displayed).
This key toggles whether CloudCannon will display a control in your WYSIWYG toolbar to insert a code block in editable regions.
Setting this key to true will enable a control in your WYSIWYG toolbar to insert a code block.
By default, this key is false (i.e., the code block control is not displayed).
This key toggles whether CloudCannon will display tools in your WYSIWYG toolbar to turn selected text into inline code and selected text into a code block.
Setting this key to true will enable two tools in your WYSIWYG toolbar to turn selected text into inline code and selected text into a code block.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a region of raw HTML for YouTube, Vimeo, social media posts, or other media.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a region of raw HTML. Embedded content is sanitized to mitigate XSS risks, which includes removing style tags. Embeds containing script tags are not loaded a rich text editor.
This key toggles whether CloudCannon will display a dropdown menu tool in your WYSIWYG toolbar for structured text.
Setting this key to true will enable a dropdown menu tool in your WYSIWYG toolbar for structured text. Valid values include for p, h1, h2, h3, h4, h5, h6, pre, address, and div. Include a space between each values, e.g. format: p h1 h2.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a horizontal line.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a horizontal line.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an image and enter alternative text and title text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an image. Select an existing image, upload an image, or use an external link.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to increase the indentation of a list item in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to increase the indentation of a list item.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to justify selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to justify selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to left align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to left align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an ordered list or convert selected text to an ordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an ordered list or convert selected text to an ordered list.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to decrease the indentation of a list item in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to decrease the indentation of a list item.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to right align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to right align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a Snippet, if any are available.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a Snippet.
This key toggles whether CloudCannon will display a dropdown menu in your WYSIWYG toolbar to apply a style to selected text.
Examples
In this example, we have enabled a dropdown menu in our WYSIWYG toolbar to apply a style to selected text. The styles are defined in the /css/styles.css file.
_editables:
content:
styles: /css/styles.css
This example file defines the styles that CloudCannon can add to your WYSIWYG toolbar.
/* Can be applied to blocks of content */
p.callout {
margin: 10px;
border: 1px solid #f5f5f5;
background-color: #eee;
}
/* Can be applied to inline content */
span.big-blue-text {
font-size: 2rem;
color: blue;
}
/* Applied to content, excluded from style dropdown */
h2 {
font-family: cursive;
}
/* Applied to content, excluded from style dropdown */
.align-left { text-align: left; }
.align-center { text-align: center; }
.align-right { text-align: right; }
.align-justify { text-align: justify; }
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a table.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a table. Further table options are available from the table context menu in the rich text editor.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to merge a list item with the item above it in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to merge a list item with the item above it.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to merge a list item with the item below it in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to merge a list item with the item below it.
This key defines input options for block Editable Regions.
This key defines what format an image is converted to prior to upload.
Examples
In this example, we have configured an Image Input to convert images to WebP format prior to upload.
_inputs:
hero_image:
type: image
options:
mime_type: image/webp
This key defines how image files are resized prior to upload, using a bounding box defined by width and height options.
Valid values are cover, contain, crop, or stretch:
coverkeeps aspect ratio and ensures the image covers the bounding boxcontainkeeps aspect ratio and ensures the image fits inside the bounding boxcropprompts the user with and interface to select an aspect-ratio-respecting areastretchignores aspect ratio and resizes the image to the bounding box
This key does not apply to existing images, and does not work if width and height options are not defined.
Examples
In this example, we have configured an Image Input to resize images using the cover style to ensure images cover the bounding box while maintaining aspect ratio.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines the width of the bounding box used in the resizing method defined by resize_style.
This key defines the height of the bounding box used in the resizing method defined by resize_style.
Examples
In this example, we have configured the height of the bounding box for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines whether you can upscale an image to fit the bounding box while resizing an image prior to upload.
Has no effect if files are not resized.
Examples
In this example, we have configured an Image Input to allow upscaling images to fit the bounding box while resizing.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
expandable: true
This key toggles whether CloudCannon will instruct a rich text editor to save width and height attributes on image elements.
Setting this key to true will instruct the rich text editor to save width and height attributes on image elements. This can prevent pop-in as a page loads.
By default, this key is false (i.e., width and height attributes are not saved on image elements). This defaults to true if the Image Size Attributes site flag is enabled (this is enabled for sites created before June 23 2023, in order to keep those sites working).
Examples
In this example, CloudCannon will save width and height attributes on image elements in a Rich Text Input.
_inputs:
content:
type: markdown
options:
image_size_attributes: true
This key defines which sources and DAMs you are allowed to upload to and browse.
The value can be an array of strings. Valid values include site-files and the reference key for any DAM connected to your site.
If site-files is omitted from the array, site files will not be available as an asset source for this input.
Examples
In this example, we have configured allowed sources for an Image Input.
_inputs:
image:
type: image
options:
allowed_sources:
- site-files
- my-cloudinary-dam
This key toggles whether CloudCannon will skip the image resizing process configured for this input when selecting existing images.
Setting this key to true will skip the image resizing process when selecting existing images.
Examples
In this example, CloudCannon will skip the image resizing process when selecting existing images for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
prevent_resize_existing_files: true
This key defines definitions for creating additional images of different sizes when uploading or selecting existing files.
Examples
In this example, we have configured an Image Input to create additional images of different sizes when uploading or selecting files.
_inputs:
hero_image:
type: image
options:
sizes:
- size: 2x
- size: 3x
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to bold selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to bold selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to copy formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to copy formatting from selected text. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not copy other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to italicize selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to italicize selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to redo recent edits undone with undo.
Setting this key to true will enable a tool in your WYSIWYG toolbar to redo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to remove formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to remove formatting. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not remove other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to strike through selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to strike through selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to subscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to subscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to superscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to superscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to underline selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to underline selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to undo recent edits.
Setting this key to true will enable a tool in your WYSIWYG toolbar to undo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will allow you to strip custom markup from content edited in a rich text editor, allowing you to clean files of unnecessary HTML content.
Setting this key to true will enable stripping custom markup from content. The remove_custom_markup key is disabled if allow_custom_markup is enabled.
This key toggles whether CloudCannon will allow you to edit custom markup in rich text editors and explicitly accept the risk of unintentionally deleting elements that cannot be recreated.
Setting this key to true will enable editing of custom markup. When using allow_custom_markup outside of editable regions, content that uses JavaScript will not be editable for security reasons. These inputs will appear as uneditable snippets.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to wrap selected blocks of text in a block quote.
Setting this key to true will enable a tool in your WYSIWYG toolbar to wrap selected blocks of text in a block quote.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an unordered list or convert selected text to an unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an unordered list or convert selected text to an unordered list.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to center align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to center align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a control in your WYSIWYG toolbar to create an inline code element, containing any selected text.
Setting this key to true will enable a control in your WYSIWYG toolbar to create an inline code element.
By default, this key is false (i.e., the inline code control is not displayed).
This key toggles whether CloudCannon will display a control in your WYSIWYG toolbar to insert a code block in editable regions.
Setting this key to true will enable a control in your WYSIWYG toolbar to insert a code block.
By default, this key is false (i.e., the code block control is not displayed).
This key toggles whether CloudCannon will display tools in your WYSIWYG toolbar to turn selected text into inline code and selected text into a code block.
Setting this key to true will enable two tools in your WYSIWYG toolbar to turn selected text into inline code and selected text into a code block.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a region of raw HTML for YouTube, Vimeo, social media posts, or other media.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a region of raw HTML. Embedded content is sanitized to mitigate XSS risks, which includes removing style tags. Embeds containing script tags are not loaded a rich text editor.
This key toggles whether CloudCannon will display a dropdown menu tool in your WYSIWYG toolbar for structured text.
Setting this key to true will enable a dropdown menu tool in your WYSIWYG toolbar for structured text. Valid values include for p, h1, h2, h3, h4, h5, h6, pre, address, and div. Include a space between each values, e.g. format: p h1 h2.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a horizontal line.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a horizontal line.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an image and enter alternative text and title text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an image. Select an existing image, upload an image, or use an external link.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to increase the indentation of a list item in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to increase the indentation of a list item.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to justify selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to justify selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to left align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to left align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an ordered list or convert selected text to an ordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an ordered list or convert selected text to an ordered list.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to decrease the indentation of a list item in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to decrease the indentation of a list item.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to right align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to right align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a Snippet, if any are available.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a Snippet.
This key toggles whether CloudCannon will display a dropdown menu in your WYSIWYG toolbar to apply a style to selected text.
Examples
In this example, we have enabled a dropdown menu in our WYSIWYG toolbar to apply a style to selected text. The styles are defined in the /css/styles.css file.
_editables:
content:
styles: /css/styles.css
This example file defines the styles that CloudCannon can add to your WYSIWYG toolbar.
/* Can be applied to blocks of content */
p.callout {
margin: 10px;
border: 1px solid #f5f5f5;
background-color: #eee;
}
/* Can be applied to inline content */
span.big-blue-text {
font-size: 2rem;
color: blue;
}
/* Applied to content, excluded from style dropdown */
h2 {
font-family: cursive;
}
/* Applied to content, excluded from style dropdown */
.align-left { text-align: left; }
.align-center { text-align: center; }
.align-right { text-align: right; }
.align-justify { text-align: justify; }
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a table.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a table. Further table options are available from the table context menu in the rich text editor.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to merge a list item with the item above it in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to merge a list item with the item above it.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to merge a list item with the item below it in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to merge a list item with the item below it.
This key defines input options for link Editable Regions.
This key defines input options for image Editable Regions.
This key defines what format an image is converted to prior to upload.
Examples
In this example, we have configured an Image Input to convert images to WebP format prior to upload.
_inputs:
hero_image:
type: image
options:
mime_type: image/webp
This key defines how image files are resized prior to upload, using a bounding box defined by width and height options.
Valid values are cover, contain, crop, or stretch:
coverkeeps aspect ratio and ensures the image covers the bounding boxcontainkeeps aspect ratio and ensures the image fits inside the bounding boxcropprompts the user with and interface to select an aspect-ratio-respecting areastretchignores aspect ratio and resizes the image to the bounding box
This key does not apply to existing images, and does not work if width and height options are not defined.
Examples
In this example, we have configured an Image Input to resize images using the cover style to ensure images cover the bounding box while maintaining aspect ratio.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines the width of the bounding box used in the resizing method defined by resize_style.
This key defines the height of the bounding box used in the resizing method defined by resize_style.
Examples
In this example, we have configured the height of the bounding box for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines whether you can upscale an image to fit the bounding box while resizing an image prior to upload.
Has no effect if files are not resized.
Examples
In this example, we have configured an Image Input to allow upscaling images to fit the bounding box while resizing.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
expandable: true
This key toggles whether CloudCannon will instruct a rich text editor to save width and height attributes on image elements.
Setting this key to true will instruct the rich text editor to save width and height attributes on image elements. This can prevent pop-in as a page loads.
By default, this key is false (i.e., width and height attributes are not saved on image elements). This defaults to true if the Image Size Attributes site flag is enabled (this is enabled for sites created before June 23 2023, in order to keep those sites working).
Examples
In this example, CloudCannon will save width and height attributes on image elements in a Rich Text Input.
_inputs:
content:
type: markdown
options:
image_size_attributes: true
This key defines which sources and DAMs you are allowed to upload to and browse.
The value can be an array of strings. Valid values include site-files and the reference key for any DAM connected to your site.
If site-files is omitted from the array, site files will not be available as an asset source for this input.
Examples
In this example, we have configured allowed sources for an Image Input.
_inputs:
image:
type: image
options:
allowed_sources:
- site-files
- my-cloudinary-dam
This key toggles whether CloudCannon will skip the image resizing process configured for this input when selecting existing images.
Setting this key to true will skip the image resizing process when selecting existing images.
Examples
In this example, CloudCannon will skip the image resizing process when selecting existing images for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
prevent_resize_existing_files: true
This key defines definitions for creating additional images of different sizes when uploading or selecting existing files.
Examples
In this example, we have configured an Image Input to create additional images of different sizes when uploading or selecting files.
_inputs:
hero_image:
type: image
options:
sizes:
- size: 2x
- size: 3x
This key defines input options for text Editable Regions.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to bold selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to bold selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to copy formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to copy formatting from selected text. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not copy other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to italicize selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to italicize selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to redo recent edits undone with undo.
Setting this key to true will enable a tool in your WYSIWYG toolbar to redo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to remove formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to remove formatting. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not remove other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to strike through selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to strike through selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to subscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to subscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to superscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to superscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to underline selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to underline selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to undo recent edits.
Setting this key to true will enable a tool in your WYSIWYG toolbar to undo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will allow you to strip custom markup from content edited in a rich text editor, allowing you to clean files of unnecessary HTML content.
Setting this key to true will enable stripping custom markup from content. The remove_custom_markup key is disabled if allow_custom_markup is enabled.
This key toggles whether CloudCannon will allow you to edit custom markup in rich text editors and explicitly accept the risk of unintentionally deleting elements that cannot be recreated.
Setting this key to true will enable editing of custom markup. When using allow_custom_markup outside of editable regions, content that uses JavaScript will not be editable for security reasons. These inputs will appear as uneditable snippets.
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.
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.
_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
This key defines custom order and grouping for Collections in your Site Navigation.
The value is an array of group objects. Each group object must contain a heading key and a collections key.
If undefined, CloudCannon will sort your Collections in the order they are defined under the collections_config key.
Examples
In this example, we have configured Collection groups to organize Collections into "Content" and "Data Files" sections in the Site Navigation.
collection_groups:
- heading: Content
collections:
- pages
- blog
- heading: Data Files
collections:
- data
This key represents an individual group entry in the collection_groups array.
The value defines a group of Collections displayed in the Site Navigation. Each group entry must contain a heading key and a collections key.
Examples
In this example, we have configured two Collection groups with a heading and collections array.
collection_groups:
- heading: Content
collections:
- pages
- blog
- heading: Data Files
collections:
- data
This key defines a short, descriptive label for a group of Collections displayed in the Site Navigation.
This key is required for each group entry in the collection_groups array.
Examples
In this example, we have configured two Collection groups with a heading that labels the group in the Site Navigation.
collection_groups:
- heading: Content
collections:
- pages
- blog
- heading: Data Files
collections:
- data
This key defines the Collections displayed in a group in the Site Navigation.
The value is an array of Collection key name strings, matching the keys defined in collections_config.
This key is required for each group entry in the collection_groups array.
Examples
In this example, we have configured two Collection groups with collections arrays.
collection_groups:
- heading: Content
collections:
- pages
- blog
- heading: Data Files
collections:
- data
This key defines which base URL (or subpath) CloudCannon should use when matching output URLs for your Site.
The base URL will prefix the output URL of each file.
Examples
In this example, we have configured the base URL to /documentation/ so all output URLs will be prefixed with this path.
base_url: /documentation/
This key defines which file or folder data in your Site is available to populate Select Inputs.
Examples
In this example, we have configured data config to make data files available for Select Inputs and Multiselect Inputs.
data_config___1___:
authors:
path___2___: data/authors.csv
offices:
path___3___: data/offices
This key defines what data sets are available to populate Select Inputs.
Examples
In this example, we have configured data config entries for both a CSV file and a folder of files.
data_config___1___:
authors:
path___2___: data/authors.csv
offices:
path___3___: data/offices
This key defines the path to a file or folder of files containing data.
Examples
In this example, we have configured data config paths for both a CSV file and a folder of files.
data_config___1___:
authors:
path___2___: data/authors.csv
offices:
path___3___: data/offices
This key defines file-specific configuration without configuring a collection or modifying files.
This key has no default.
This key defines scope to configure at a file level, without adding configuration to files.
This key defines the glob pattern(s) targeting a path to one or more files.
Examples
In this example, we have configured a file config to target the data/tabs.yml file with object input configuration.
file_config:
- glob: data/tabs.yml
_inputs:
$:
type: object
options:
subtype: tabbed
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.
Examples
In this example, we have enabled only the Content Editor in the blog Collection.
collections_config:
blog:
_enabled_editors:
- content
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.
Examples
In this example, we have configured the Snippet tool for WYSIWYG toolbars in the blog Collection.
collections_config:
blog:
_editables:
content:
snippet: true
5 nested properties
This key defines input options for the Content Editor.
44 nested properties
This key defines what format an image is converted to prior to upload.
Examples
In this example, we have configured an Image Input to convert images to WebP format prior to upload.
_inputs:
hero_image:
type: image
options:
mime_type: image/webp
This key defines how image files are resized prior to upload, using a bounding box defined by width and height options.
Valid values are cover, contain, crop, or stretch:
coverkeeps aspect ratio and ensures the image covers the bounding boxcontainkeeps aspect ratio and ensures the image fits inside the bounding boxcropprompts the user with and interface to select an aspect-ratio-respecting areastretchignores aspect ratio and resizes the image to the bounding box
This key does not apply to existing images, and does not work if width and height options are not defined.
Examples
In this example, we have configured an Image Input to resize images using the cover style to ensure images cover the bounding box while maintaining aspect ratio.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines the width of the bounding box used in the resizing method defined by resize_style.
This key defines the height of the bounding box used in the resizing method defined by resize_style.
Examples
In this example, we have configured the height of the bounding box for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines whether you can upscale an image to fit the bounding box while resizing an image prior to upload.
Has no effect if files are not resized.
Examples
In this example, we have configured an Image Input to allow upscaling images to fit the bounding box while resizing.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
expandable: true
This key toggles whether CloudCannon will instruct a rich text editor to save width and height attributes on image elements.
Setting this key to true will instruct the rich text editor to save width and height attributes on image elements. This can prevent pop-in as a page loads.
By default, this key is false (i.e., width and height attributes are not saved on image elements). This defaults to true if the Image Size Attributes site flag is enabled (this is enabled for sites created before June 23 2023, in order to keep those sites working).
Examples
In this example, CloudCannon will save width and height attributes on image elements in a Rich Text Input.
_inputs:
content:
type: markdown
options:
image_size_attributes: true
This key defines which sources and DAMs you are allowed to upload to and browse.
The value can be an array of strings. Valid values include site-files and the reference key for any DAM connected to your site.
If site-files is omitted from the array, site files will not be available as an asset source for this input.
Examples
In this example, we have configured allowed sources for an Image Input.
_inputs:
image:
type: image
options:
allowed_sources:
- site-files
- my-cloudinary-dam
This key toggles whether CloudCannon will skip the image resizing process configured for this input when selecting existing images.
Setting this key to true will skip the image resizing process when selecting existing images.
Examples
In this example, CloudCannon will skip the image resizing process when selecting existing images for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
prevent_resize_existing_files: true
This key defines definitions for creating additional images of different sizes when uploading or selecting existing files.
Examples
In this example, we have configured an Image Input to create additional images of different sizes when uploading or selecting files.
_inputs:
hero_image:
type: image
options:
sizes:
- size: 2x
- size: 3x
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to bold selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to bold selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to copy formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to copy formatting from selected text. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not copy other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to italicize selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to italicize selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to redo recent edits undone with undo.
Setting this key to true will enable a tool in your WYSIWYG toolbar to redo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to remove formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to remove formatting. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not remove other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to strike through selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to strike through selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to subscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to subscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to superscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to superscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to underline selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to underline selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to undo recent edits.
Setting this key to true will enable a tool in your WYSIWYG toolbar to undo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will allow you to strip custom markup from content edited in a rich text editor, allowing you to clean files of unnecessary HTML content.
Setting this key to true will enable stripping custom markup from content. The remove_custom_markup key is disabled if allow_custom_markup is enabled.
This key toggles whether CloudCannon will allow you to edit custom markup in rich text editors and explicitly accept the risk of unintentionally deleting elements that cannot be recreated.
Setting this key to true will enable editing of custom markup. When using allow_custom_markup outside of editable regions, content that uses JavaScript will not be editable for security reasons. These inputs will appear as uneditable snippets.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to wrap selected blocks of text in a block quote.
Setting this key to true will enable a tool in your WYSIWYG toolbar to wrap selected blocks of text in a block quote.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an unordered list or convert selected text to an unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an unordered list or convert selected text to an unordered list.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to center align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to center align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a control in your WYSIWYG toolbar to create an inline code element, containing any selected text.
Setting this key to true will enable a control in your WYSIWYG toolbar to create an inline code element.
By default, this key is false (i.e., the inline code control is not displayed).
This key toggles whether CloudCannon will display a control in your WYSIWYG toolbar to insert a code block in editable regions.
Setting this key to true will enable a control in your WYSIWYG toolbar to insert a code block.
By default, this key is false (i.e., the code block control is not displayed).
This key toggles whether CloudCannon will display tools in your WYSIWYG toolbar to turn selected text into inline code and selected text into a code block.
Setting this key to true will enable two tools in your WYSIWYG toolbar to turn selected text into inline code and selected text into a code block.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a region of raw HTML for YouTube, Vimeo, social media posts, or other media.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a region of raw HTML. Embedded content is sanitized to mitigate XSS risks, which includes removing style tags. Embeds containing script tags are not loaded a rich text editor.
This key toggles whether CloudCannon will display a dropdown menu tool in your WYSIWYG toolbar for structured text.
Setting this key to true will enable a dropdown menu tool in your WYSIWYG toolbar for structured text. Valid values include for p, h1, h2, h3, h4, h5, h6, pre, address, and div. Include a space between each values, e.g. format: p h1 h2.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a horizontal line.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a horizontal line.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an image and enter alternative text and title text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an image. Select an existing image, upload an image, or use an external link.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to increase the indentation of a list item in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to increase the indentation of a list item.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to justify selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to justify selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to left align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to left align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an ordered list or convert selected text to an ordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an ordered list or convert selected text to an ordered list.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to decrease the indentation of a list item in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to decrease the indentation of a list item.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to right align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to right align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a Snippet, if any are available.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a Snippet.
This key toggles whether CloudCannon will display a dropdown menu in your WYSIWYG toolbar to apply a style to selected text.
Examples
In this example, we have enabled a dropdown menu in our WYSIWYG toolbar to apply a style to selected text. The styles are defined in the /css/styles.css file.
_editables:
content:
styles: /css/styles.css
This example file defines the styles that CloudCannon can add to your WYSIWYG toolbar.
/* Can be applied to blocks of content */
p.callout {
margin: 10px;
border: 1px solid #f5f5f5;
background-color: #eee;
}
/* Can be applied to inline content */
span.big-blue-text {
font-size: 2rem;
color: blue;
}
/* Applied to content, excluded from style dropdown */
h2 {
font-family: cursive;
}
/* Applied to content, excluded from style dropdown */
.align-left { text-align: left; }
.align-center { text-align: center; }
.align-right { text-align: right; }
.align-justify { text-align: justify; }
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a table.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a table. Further table options are available from the table context menu in the rich text editor.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to merge a list item with the item above it in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to merge a list item with the item above it.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to merge a list item with the item below it in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to merge a list item with the item below it.
This key defines input options for block Editable Regions.
44 nested properties
This key defines what format an image is converted to prior to upload.
Examples
In this example, we have configured an Image Input to convert images to WebP format prior to upload.
_inputs:
hero_image:
type: image
options:
mime_type: image/webp
This key defines how image files are resized prior to upload, using a bounding box defined by width and height options.
Valid values are cover, contain, crop, or stretch:
coverkeeps aspect ratio and ensures the image covers the bounding boxcontainkeeps aspect ratio and ensures the image fits inside the bounding boxcropprompts the user with and interface to select an aspect-ratio-respecting areastretchignores aspect ratio and resizes the image to the bounding box
This key does not apply to existing images, and does not work if width and height options are not defined.
Examples
In this example, we have configured an Image Input to resize images using the cover style to ensure images cover the bounding box while maintaining aspect ratio.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines the width of the bounding box used in the resizing method defined by resize_style.
This key defines the height of the bounding box used in the resizing method defined by resize_style.
Examples
In this example, we have configured the height of the bounding box for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines whether you can upscale an image to fit the bounding box while resizing an image prior to upload.
Has no effect if files are not resized.
Examples
In this example, we have configured an Image Input to allow upscaling images to fit the bounding box while resizing.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
expandable: true
This key toggles whether CloudCannon will instruct a rich text editor to save width and height attributes on image elements.
Setting this key to true will instruct the rich text editor to save width and height attributes on image elements. This can prevent pop-in as a page loads.
By default, this key is false (i.e., width and height attributes are not saved on image elements). This defaults to true if the Image Size Attributes site flag is enabled (this is enabled for sites created before June 23 2023, in order to keep those sites working).
Examples
In this example, CloudCannon will save width and height attributes on image elements in a Rich Text Input.
_inputs:
content:
type: markdown
options:
image_size_attributes: true
This key defines which sources and DAMs you are allowed to upload to and browse.
The value can be an array of strings. Valid values include site-files and the reference key for any DAM connected to your site.
If site-files is omitted from the array, site files will not be available as an asset source for this input.
Examples
In this example, we have configured allowed sources for an Image Input.
_inputs:
image:
type: image
options:
allowed_sources:
- site-files
- my-cloudinary-dam
This key toggles whether CloudCannon will skip the image resizing process configured for this input when selecting existing images.
Setting this key to true will skip the image resizing process when selecting existing images.
Examples
In this example, CloudCannon will skip the image resizing process when selecting existing images for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
prevent_resize_existing_files: true
This key defines definitions for creating additional images of different sizes when uploading or selecting existing files.
Examples
In this example, we have configured an Image Input to create additional images of different sizes when uploading or selecting files.
_inputs:
hero_image:
type: image
options:
sizes:
- size: 2x
- size: 3x
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to bold selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to bold selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to copy formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to copy formatting from selected text. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not copy other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to italicize selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to italicize selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to redo recent edits undone with undo.
Setting this key to true will enable a tool in your WYSIWYG toolbar to redo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to remove formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to remove formatting. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not remove other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to strike through selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to strike through selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to subscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to subscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to superscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to superscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to underline selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to underline selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to undo recent edits.
Setting this key to true will enable a tool in your WYSIWYG toolbar to undo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will allow you to strip custom markup from content edited in a rich text editor, allowing you to clean files of unnecessary HTML content.
Setting this key to true will enable stripping custom markup from content. The remove_custom_markup key is disabled if allow_custom_markup is enabled.
This key toggles whether CloudCannon will allow you to edit custom markup in rich text editors and explicitly accept the risk of unintentionally deleting elements that cannot be recreated.
Setting this key to true will enable editing of custom markup. When using allow_custom_markup outside of editable regions, content that uses JavaScript will not be editable for security reasons. These inputs will appear as uneditable snippets.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to wrap selected blocks of text in a block quote.
Setting this key to true will enable a tool in your WYSIWYG toolbar to wrap selected blocks of text in a block quote.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an unordered list or convert selected text to an unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an unordered list or convert selected text to an unordered list.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to center align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to center align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a control in your WYSIWYG toolbar to create an inline code element, containing any selected text.
Setting this key to true will enable a control in your WYSIWYG toolbar to create an inline code element.
By default, this key is false (i.e., the inline code control is not displayed).
This key toggles whether CloudCannon will display a control in your WYSIWYG toolbar to insert a code block in editable regions.
Setting this key to true will enable a control in your WYSIWYG toolbar to insert a code block.
By default, this key is false (i.e., the code block control is not displayed).
This key toggles whether CloudCannon will display tools in your WYSIWYG toolbar to turn selected text into inline code and selected text into a code block.
Setting this key to true will enable two tools in your WYSIWYG toolbar to turn selected text into inline code and selected text into a code block.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a region of raw HTML for YouTube, Vimeo, social media posts, or other media.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a region of raw HTML. Embedded content is sanitized to mitigate XSS risks, which includes removing style tags. Embeds containing script tags are not loaded a rich text editor.
This key toggles whether CloudCannon will display a dropdown menu tool in your WYSIWYG toolbar for structured text.
Setting this key to true will enable a dropdown menu tool in your WYSIWYG toolbar for structured text. Valid values include for p, h1, h2, h3, h4, h5, h6, pre, address, and div. Include a space between each values, e.g. format: p h1 h2.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a horizontal line.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a horizontal line.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an image and enter alternative text and title text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an image. Select an existing image, upload an image, or use an external link.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to increase the indentation of a list item in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to increase the indentation of a list item.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to justify selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to justify selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to left align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to left align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert an ordered list or convert selected text to an ordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert an ordered list or convert selected text to an ordered list.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to decrease the indentation of a list item in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to decrease the indentation of a list item.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to right align selected text by toggling a class name for that text block.
Setting this key to true will enable a tool in your WYSIWYG toolbar to right align selected text. The value is the class name to align the text. The styles for this class must be defined in the styles file.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a Snippet, if any are available.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a Snippet.
This key toggles whether CloudCannon will display a dropdown menu in your WYSIWYG toolbar to apply a style to selected text.
Examples
In this example, we have enabled a dropdown menu in our WYSIWYG toolbar to apply a style to selected text. The styles are defined in the /css/styles.css file.
_editables:
content:
styles: /css/styles.css
This example file defines the styles that CloudCannon can add to your WYSIWYG toolbar.
/* Can be applied to blocks of content */
p.callout {
margin: 10px;
border: 1px solid #f5f5f5;
background-color: #eee;
}
/* Can be applied to inline content */
span.big-blue-text {
font-size: 2rem;
color: blue;
}
/* Applied to content, excluded from style dropdown */
h2 {
font-family: cursive;
}
/* Applied to content, excluded from style dropdown */
.align-left { text-align: left; }
.align-center { text-align: center; }
.align-right { text-align: right; }
.align-justify { text-align: justify; }
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to insert a table.
Setting this key to true will enable a tool in your WYSIWYG toolbar to insert a table. Further table options are available from the table context menu in the rich text editor.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to merge a list item with the item above it in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to merge a list item with the item above it.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to merge a list item with the item below it in an ordered or unordered list.
Setting this key to true will enable a tool in your WYSIWYG toolbar to merge a list item with the item below it.
This key defines input options for link Editable Regions.
1 nested properties
This key defines input options for image Editable Regions.
10 nested properties
This key defines what format an image is converted to prior to upload.
Examples
In this example, we have configured an Image Input to convert images to WebP format prior to upload.
_inputs:
hero_image:
type: image
options:
mime_type: image/webp
This key defines how image files are resized prior to upload, using a bounding box defined by width and height options.
Valid values are cover, contain, crop, or stretch:
coverkeeps aspect ratio and ensures the image covers the bounding boxcontainkeeps aspect ratio and ensures the image fits inside the bounding boxcropprompts the user with and interface to select an aspect-ratio-respecting areastretchignores aspect ratio and resizes the image to the bounding box
This key does not apply to existing images, and does not work if width and height options are not defined.
Examples
In this example, we have configured an Image Input to resize images using the cover style to ensure images cover the bounding box while maintaining aspect ratio.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines the width of the bounding box used in the resizing method defined by resize_style.
This key defines the height of the bounding box used in the resizing method defined by resize_style.
Examples
In this example, we have configured the height of the bounding box for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
This key defines whether you can upscale an image to fit the bounding box while resizing an image prior to upload.
Has no effect if files are not resized.
Examples
In this example, we have configured an Image Input to allow upscaling images to fit the bounding box while resizing.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
expandable: true
This key toggles whether CloudCannon will instruct a rich text editor to save width and height attributes on image elements.
Setting this key to true will instruct the rich text editor to save width and height attributes on image elements. This can prevent pop-in as a page loads.
By default, this key is false (i.e., width and height attributes are not saved on image elements). This defaults to true if the Image Size Attributes site flag is enabled (this is enabled for sites created before June 23 2023, in order to keep those sites working).
Examples
In this example, CloudCannon will save width and height attributes on image elements in a Rich Text Input.
_inputs:
content:
type: markdown
options:
image_size_attributes: true
This key defines which sources and DAMs you are allowed to upload to and browse.
The value can be an array of strings. Valid values include site-files and the reference key for any DAM connected to your site.
If site-files is omitted from the array, site files will not be available as an asset source for this input.
Examples
In this example, we have configured allowed sources for an Image Input.
_inputs:
image:
type: image
options:
allowed_sources:
- site-files
- my-cloudinary-dam
This key toggles whether CloudCannon will skip the image resizing process configured for this input when selecting existing images.
Setting this key to true will skip the image resizing process when selecting existing images.
Examples
In this example, CloudCannon will skip the image resizing process when selecting existing images for an Image Input.
_inputs:
hero_image:
type: image
options:
width: 1200
height: 600
resize_style: cover
prevent_resize_existing_files: true
This key defines definitions for creating additional images of different sizes when uploading or selecting existing files.
Examples
In this example, we have configured an Image Input to create additional images of different sizes when uploading or selecting files.
_inputs:
hero_image:
type: image
options:
sizes:
- size: 2x
- size: 3x
This key defines input options for text Editable Regions.
14 nested properties
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to bold selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to bold selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to copy formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to copy formatting from selected text. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not copy other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to italicize selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to italicize selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to create a hyperlink around selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to redo recent edits undone with undo.
Setting this key to true will enable a tool in your WYSIWYG toolbar to redo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to remove formatting from selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to remove formatting. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not remove other styles or formatting.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to strike through selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to strike through selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to subscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to subscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to superscript selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to superscript selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to underline selected text.
Setting this key to true will enable a tool in your WYSIWYG toolbar to underline selected text.
This key toggles whether CloudCannon will display a tool in your WYSIWYG toolbar to undo recent edits.
Setting this key to true will enable a tool in your WYSIWYG toolbar to undo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
This key toggles whether CloudCannon will allow you to strip custom markup from content edited in a rich text editor, allowing you to clean files of unnecessary HTML content.
Setting this key to true will enable stripping custom markup from content. The remove_custom_markup key is disabled if allow_custom_markup is enabled.
This key toggles whether CloudCannon will allow you to edit custom markup in rich text editors and explicitly accept the risk of unintentionally deleting elements that cannot be recreated.
Setting this key to true will enable editing of custom markup. When using allow_custom_markup outside of editable regions, content that uses JavaScript will not be editable for security reasons. These inputs will appear as uneditable snippets.
This key defines settings for the default editor actions on your site.
This key defines the link for the Home button on the Dashboard page.
Examples
In this example, we have configured the Home button to link to /blog/ instead of the default /.
editor:
default_path: /blog/
This key defines the link for the Home button on the Dashboard page.
Examples
In this example, we have configured the Home button to link to /blog/ instead of the default /.
editor:
default_path: /blog/
This key defines the appearance and behavior of the Source Editor.
For more information, please read our documentation on the Source Editor.
Examples
In this example, we have configured the Source Editor with custom theme, tab size, and gutter settings.
source_editor:
theme: basic_dark
tab_size: 2
show_gutter: true
This key defines the auto-indentation of each line and how many spaces a tab indentation counts as.
Examples
In this example, we have configured the Source Editor to use 2 spaces for tab indentation.
source_editor:
tab_size: 2
This key defines the color theme for syntax highlighting.
Examples
In this example, we have configured the Source Editor to use the dark theme for syntax highlighting.
source_editor:
theme: dark
This key toggles the gutter on the left of the editing interface, displaying line numbers and code folding controls.
Examples
In this example, CloudCannon will show the gutter with line numbers in the Source Editor.
source_editor:
show_gutter: true
This key toggles whether CloudCannon will enable soft wrapping of code in the Source Editor.
Setting this key to true will enable soft wrapping of code, allowing long lines to wrap to the next line without horizontal scrolling.
Examples
In this example, CloudCannon will enable soft wrapping of code in the Source Editor.
source_editor:
soft_wrap: true
This key defines commit message templates available when saving changes.
The value is an array of template objects. Each template object can contain optional label, template_path, template_string, wrap_width, extra_data, and _inputs keys.
Commit messages appear on the Review changes modal when you save your changes.
Examples
In this example, we have configured a commit template with a template string and input configuration.
commit_templates:
- label: Default
template_string: '{commit_type}: {message|trim}'
_inputs:
commit_type:
type: select
options:
allow_empty: true
values:
- feature
- fix
- test
cascade: true
In this example, we have configured a commit template that uses a file for the template content.
commit_templates:
- label: Commit message from file
template_path: /.git/commit-message.txt
In this example, we have configured a commit template with a template string, input configuration, and extra data for nested templates.
commit_templates:
- label: Breaking change
template_string: '{message}{breaking_change|if=breaking_change_message}'
_inputs:
breaking_change_message:
type: text
extra_data:
breaking_change: '⚠️ {breaking_change_message}'
This key defines the commit template to use when pulling changes from the upstream repository.
An upstream commit message template can contain plain text and placeholders. Placeholders insert data related to the commit and use [ ] brackets. CloudCannon supports the following commit placeholders:
[branch]— the name of the current branch.[publish_branch]— the name of the Publish Branch from which you merge upstream changes.[author]— the email address of the person responsible for the upstream merge.[date]— the date of the upstream merge in the format "Tue Nov 28 2023 21:46:17 GMT+0000".
Examples
In this example, we have configured a commit template with placeholders for upstream pulls.
upstream_commit_template: "Merge branch [publish_branch] into develop of [branch] by [author] at [date]"
This key defines your markdown engine for parsing Markdown content into HTML and any configuration options for your engine.
Examples
In this example, we have configured CloudCannon to use the commonmark Markdown engine with various options including attributes and attribute elements.
markdown:
engine: commonmark
options:
attributes: true
attributes_elements:
inline: none
block: space right
ul: below
ol: below
blockquote: below
p: below
img: below
hr: below
table: below
li: none
This key defines which Markdown processing engine CloudCannon will use to convert between HTML and Markdown.
Examples
In this example, we have configured CloudCannon to use the kramdown Markdown engine.
markdown:
engine: kramdown
In this example, we have configured CloudCannon to use the commonmark Markdown engine with custom options.
markdown:
engine: commonmark
options:
html: true
breaks: true
This key defines configuration options for the Markdown processing engine.
The value is an object that can contain various options controlling how Markdown is converted to HTML and vice versa.
Examples
In this example, we have configured Markdown options to enable HTML output, convert line breaks, and enable GitHub Flavored Markdown.
markdown:
engine: commonmark
options:
html: true
breaks: true
gfm: true
19 nested properties
This key toggles whether CloudCannon will output HTML tags from source when converting Markdown to HTML.
Setting this key to true will allow HTML tags in the Markdown source to be output in the resulting HTML.
By default, this key is false (i.e., HTML tags in Markdown source are not output).
Examples
In this example, we have configured Markdown to output HTML tags from source.
markdown:
engine: commonmark
options:
html: true
This key toggles whether CloudCannon will use XHTML-style closing for single tags when converting Markdown to HTML.
Setting this key to true will use / to close single tags (e.g., <br /> instead of <br>).
By default, this key is false (i.e., single tags are not closed with /).
Examples
In this example, we have configured Markdown to use XHTML-style closing for single tags.
markdown:
engine: commonmark
options:
xhtml: true
This key toggles whether CloudCannon will convert line breaks (\n) in paragraphs into <br> tags when converting Markdown to HTML.
Setting this key to true will convert line breaks within paragraphs into <br> tags.
By default, this key is false (i.e., line breaks in paragraphs are not converted to <br> tags).
Examples
In this example, we have configured Markdown to convert line breaks in paragraphs into <br> tags.
markdown:
engine: commonmark
options:
breaks: true
This key toggles whether CloudCannon will automatically convert URL-like text to links when converting Markdown to HTML.
Setting this key to true will automatically convert text that looks like URLs into clickable links.
By default, this key is false (i.e., URL-like text is not automatically converted to links).
Examples
In this example, we have configured Markdown to automatically convert URL-like text to links.
markdown:
engine: commonmark
options:
linkify: true
This key toggles whether CloudCannon will enable typographic replacements and quote beautification when converting Markdown to HTML.
Setting this key to true will enable language-neutral replacements (such as dashes and ellipses) and beautify quotes based on the quotes configuration.
By default, this key is false (i.e., typographic replacements and quote beautification are disabled).
Examples
In this example, we have configured Markdown to enable typographic replacements and quote beautification.
markdown:
engine: commonmark
options:
typographer: true
quotes: '«»„""'
This key defines double and single quotes replacement pairs for quote beautification when typographer is enabled.
The value is a string that specifies quote pairs. For example, you can use "«»„"" for Russian, ""„"‚"" for German, and ["«\xA0", "\xA0»", "‹\xA0", "\xA0›"] for French (including nbsp).
This key only takes effect when typographer is enabled.
Examples
In this example, we have configured quote replacement pairs for Russian typography.
markdown:
engine: commonmark
options:
typographer: true
quotes: '«»„""'
This key toggles whether CloudCannon will output lists with an extra space when converting HTML to Markdown.
Setting this key to true will add an extra space in list items when outputting Markdown.
By default, this key is false (i.e., lists are output without an extra space).
Examples
In this example, we have configured Markdown to output lists with an extra space.
markdown:
engine: commonmark
options:
spaced_lists: true
This key toggles whether CloudCannon will add line breaks between sentences when converting HTML to Markdown.
Setting this key to true will add line breaks between sentences in the output Markdown.
By default, this key is false (i.e., line breaks are not added between sentences).
Examples
In this example, we have configured Markdown to add line breaks between sentences.
markdown:
engine: commonmark
options:
sentence_per_line: true
This key toggles whether CloudCannon will enable GitHub Flavored Markdown (GFM) mode when processing Markdown.
Setting this key to true will enable GFM mode, which includes features like tables, strikethrough, task lists, and autolinks.
By default, this key is false (i.e., GFM mode is disabled).
Examples
In this example, we have configured Markdown to enable GitHub Flavored Markdown mode.
markdown:
engine: commonmark
options:
gfm: true
This key defines which style of code block fences CloudCannon will use when converting HTML to Markdown.
The value can be \``(three backticks) or~~~` (three tildes).
Examples
In this example, we have configured Markdown to use tildes for code block fences.
markdown:
engine: commonmark
options:
code_block_fences: '~~~'
This key toggles whether CloudCannon will treat 4 spaces of indentation as a code block when processing Markdown.
Setting this key to true will read indented blocks (4 spaces) as code blocks.
By default, this key is false (i.e., indented blocks are not treated as code blocks).
Examples
In this example, we have configured Markdown to treat 4 spaces of indentation as code blocks.
markdown:
engine: commonmark
options:
treat_indentation_as_code: true
This key toggles whether CloudCannon will render snippets as plain text within code blocks when processing Markdown.
Setting this key to true will prevent snippets from being processed within code blocks, rendering them as plain text instead.
By default, this key is false (i.e., snippets within code blocks may be processed).
Examples
In this example, we have configured Markdown to render snippets as plain text within code blocks.
markdown:
engine: commonmark
options:
escape_snippets_in_code_blocks: true
This key toggles whether CloudCannon will output tables in Markdown format when converting HTML to Markdown.
Setting this key to true will convert HTML tables to Markdown table format.
By default, this key is false (i.e., tables are not output in Markdown format).
Examples
In this example, we have configured Markdown to output tables in Markdown format.
markdown:
engine: commonmark
options:
table: true
This key toggles whether CloudCannon will output strikethrough text wrapped in double tildes when converting HTML to Markdown.
Setting this key to true will output strikethrough text as ~~strike~~ in Markdown.
By default, this key is false (i.e., strikethrough text is not output in double tildes format).
Examples
In this example, we have configured Markdown to output strikethrough text wrapped in double tildes.
markdown:
engine: commonmark
options:
strikethrough: true
This key toggles whether CloudCannon will output subscript text wrapped in tildes when converting HTML to Markdown.
Setting this key to true will output subscript text as ~sub~ in Markdown.
By default, this key is false (i.e., subscript text is not output in tildes format).
Examples
In this example, we have configured Markdown to output subscript text wrapped in tildes.
markdown:
engine: commonmark
options:
subscript: true
This key toggles whether CloudCannon will output superscript text wrapped in carets when converting HTML to Markdown.
Setting this key to true will output superscript text as ^super^ in Markdown.
By default, this key is false (i.e., superscript text is not output in carets format).
Examples
In this example, we have configured Markdown to output superscript text wrapped in carets.
markdown:
engine: commonmark
options:
superscript: true
This key toggles whether CloudCannon will generate IDs for headings when converting Markdown to HTML.
Setting this key to true will automatically generate ID attributes for heading elements based on their text content.
By default, this key is false (i.e., IDs are not generated for headings).
Examples
In this example, we have configured Markdown to generate IDs for headings.
markdown:
engine: commonmark
options:
heading_ids: true
This key toggles whether CloudCannon will save element attributes in Markdown format instead of converting them to HTML when converting HTML to Markdown.
Setting this key to true will preserve element attributes in Markdown format (using attribute lists) rather than converting them to HTML.
By default, this key is false (i.e., element attributes are converted to HTML).
Examples
In this example, we have configured Markdown to save element attributes in Markdown format.
markdown:
engine: commonmark
options:
attributes: true
This key defines positioning behavior of Markdown attributes for different element types when converting HTML to Markdown.
The value is an object that can contain inline, block, or element-specific properties. Each property value specifies where attribute lists should be positioned for that element type. Valid values are none, right, space right, below, newline below, or right-of-prefix.
This key only takes effect when attributes is enabled.
Examples
In this example, we have configured attribute positioning for inline and block elements.
markdown:
engine: commonmark
options:
attributes: true
attribute_elements:
inline: right
block: below
2 nested properties
This key defines where attribute lists are positioned for inline elements when converting HTML to Markdown.
The value can be none, right, space right, below, newline below, or right-of-prefix. This applies to all inline elements unless overridden by element-specific configuration.
This key only takes effect when attributes is enabled.
Examples
In this example, we have configured inline elements to place attributes on the right.
markdown:
engine: commonmark
options:
attributes: true
attribute_elements:
inline: right
This key defines where attribute lists are positioned for block-level elements when converting HTML to Markdown.
The value can be none, right, space right, below, newline below, or right-of-prefix. This applies to all block-level elements unless overridden by element-specific configuration.
This key only takes effect when attributes is enabled.
Examples
In this example, we have configured block-level elements to place attributes below the element.
markdown:
engine: commonmark
options:
attributes: true
attribute_elements:
block: below
Positioning options for Markdown attribute elements.
This key defines custom snippets for your Site.
This key has no default.
This key defines a snippet configuration.
This key defines the snippet string that contains the text to match for your snippet, with any dynamic sections represented using a placeholder in double square brackets.
Examples
In this example, we have configured a snippet string for a custom button snippet.
_snippets_definitions:
custom_button:
snippet: "[[text]]"
template: button
This key defines the template that this snippet should inherit, out of the available Snippet Templates.
Examples
In this example, we have configured a snippet to use the button template.
_snippets_definitions:
custom_button:
template: button
This key toggles whether this snippet can appear inline (within a sentence).
Setting this key to true will allow this snippet to appear inline (within a sentence).
By default, this key is false (i.e., this snippet is treated as a block-level element in the content editor).
This key defines how selected items are rendered.
Defaults to 'card', or 'inline' if inline is true.
This key toggles whether this snippet treats whitespace as-is or not.
Setting this key to true will make the snippet treat whitespace as-is.
By default, this key is false (i.e., whitespace is normalized).
This key defines the variables required for the selected template.
Examples
In this example, we have configured snippet definitions for a custom snippet template.
_snippets_definitions:
custom_button:
template: button
definitions:
text: Button Text
url: Button URL
This key defines alternate configurations for this snippet.
This key defines the parameters of this snippet.
This key defines alternate configurations for this snippet.
This key defines the parsing configuration for this argument.
This key defines the key that the parser should look for in the source text.
This only needs to be set if it differs from the editor_key.
Examples
parser: "key_values"
options:
models___1___:
- source_key: href
editor_key: link
- source_key: target
editor_key: link_target
- source_key: class
editor_key: classnames
Example usage:
## My blog post
<a href="#link" target="_blank" class="my_link"> ... </a>
Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
When edited in CloudCannon, this will edit as the data model:
{/* TODO: Use screenshot here instead */}
link: "#link"
link_target: "_blank"
classnames: "my_link"
This key defines the key that a user in CloudCannon will see when editing this value.
This key will also be used if you want to specify any input configuration using _inputs.
If no source_key is set, this key will also be assumed to be the source key.
Examples
parser: "key_values"
options:
models___1___:
- editor_key: href
- editor_key: class
- editor_key: target
Example usage:
## My blog post
<a href="#link" target="_blank" class="my_link"> ... </a>
Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
When edited in CloudCannon, this will edit as the data model:
{/* TODO: Use screenshot here instead */}
href: "#link"
target: "_blank"
class: "my_link"
This key toggles whether this key-value pair should be omitted altogether if the value is empty.
Setting this key to true will omit the key-value pair if the value is empty. Requires that this key is also set as optional, as otherwise the snippet would not re-parse.
By default, this key is false (i.e., empty key-value pairs are not omitted).
Examples
parser: "key_values"
options:
models:
- editor_key: href
- editor_key: target
- editor_key: class
optional: true
remove_empty: true
Example usage:
## My blog post
<a href="#link" target="_blank" class=""> ... </a> <!--1-->
<a href="#link" target="_blank"> ... </a> <!--1--> <!--2-->
Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
This key toggles whether a value must exist for this parser.
Setting this key to true will make the value optional for this parser. Useful for long sets of key-value pairs that are not all required.
By default, this key is false (i.e., a value must exist for this parser).
Examples
parser: "key_values"
options:
models:
- editor_key: href
- editor_key: target
optional: true
- editor_key: class
optional: true
Example usage:
## My blog post
<a href="#link" target="_blank" class="my_link"> ... </a> <!--1-->
<a href="#link" target="_blank"> ... </a> <!--1-->
<a href="#link"> ... </a> <!--1-->
<a target="_blank"> ... </a> <!--2-->
Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
This key defines the data type for snippet parameter parsing.
The value can be array, object, string, boolean, or number. This specifies the expected data type when parsing snippet parameters.
Examples
In this example, we have configured a snippet model to expect a string type.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
model:
type: string
This key defines a list of valid values for the parser.
If specified, values not in the provided list will cause this snippet to be skipped,
and a different snippet will be matched if possible.
A user entering a different value while editing this snippet will cause it to error, so this option is
best paired with a select input configured on the editor_key.
Examples
parser: "argument"
options:
model:
editor_key: video_id
allowed_values: ["riXoAr6gO-E", "CZcNgDN81Sw", "0iwNjcFIHNM"]
Example usage:
## My blog post
<<video "CZcNgDN81Sw">> <!--1-->
<<video "riXoAr6gO-E">> <!--1-->
<<video "RuvMHkfOpvg">> <!--2-->
Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
This key toggles whether any value in this argument will alias to true, and an empty value will alias to false.
Setting this key to true will cause any value in this argument to alias to true, and an empty value to alias to false.
By default, this key is false (i.e., values are not aliased to boolean).
Examples
In this example, we have configured implied boolean so any value in this argument will alias to true, and an empty value will alias to false.
parser: "argument"
options:
model:
editor_key: has_video_id
implied_boolean: true
This key defines formatting options for parsing snippet parameters.
The value is an object that can contain various options controlling how snippet parameters are parsed, including boundaries, delimiters, allowed value types, and string formatting options.
Examples
A common option to configure for the
argument parser is the string_boundary:
_snippets:
video:
snippet: "<<video [[video_arg]]>>"
params:
video_arg:
parser: "argument"
options:
model:
editor_key: video_id
format:
string_boundary: ['"', "`"]
This would make our snippet match <<video "CZcNgDN81Sw">> or <<video `CZcNgDN81Sw`>> but not <<video 'CZcNgDN81Sw'>> or <<video CZcNgDN81Sw>>.
Another common requirement is specifying forbidden_tokens,
especially when defining an argument with no string boundary.
_snippets:
video:
snippet: "<<video [[video_arg]]>>"
params:
video_arg:
parser: "argument"
options:
model:
editor_key: video_id
format:
forbidden_tokens:
- ">"
string_boundary:
- ""
This key defines the boundary tokens required for key-value segments when parsing snippet parameters.
The value is an object that contains start and end properties, each specifying a string token. This defines paired tokens that enclose the root parameter structure.
Examples
In this example, we have configured root boundaries to use angle brackets.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
root_boundary:
start: '<<'
end: '>>'
2 nested properties
This key defines the start token for root-level boundaries when parsing snippet parameters.
The value is a string that specifies the token that marks the start of the root-level structure in snippet parameter parsing. This works together with root_boundary.end to define paired tokens that enclose the root parameter structure.
Examples
In this example, we have configured root boundaries to use angle brackets.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
root_boundary:
start: '<<'
end: '>>'
This key defines the end token for root-level boundaries when parsing snippet parameters.
The value is a string that specifies the token that marks the end of the root-level structure in snippet parameter parsing. This works together with root_boundary.start to define paired tokens that enclose the root parameter structure.
Examples
In this example, we have configured root boundaries to use angle brackets.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
root_boundary:
start: '<<'
end: '>>'
This key defines the boundary tokens required for arguments and values when parsing snippet parameters.
The value is an object that contains start and end properties, each specifying a string token. For example, MDX specifies { start: "{", end: "}" }, which allows syntax such as <Component flag={true} />.
Examples
In this example, we have configured root value boundaries to use curly braces.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
root_value_boundary:
start: '{'
end: '}'
2 nested properties
This key defines the start token for root value boundaries when parsing snippet parameters.
The value is a string that specifies the token that marks the start of a root-level value in snippet parameter parsing. This works together with root_value_boundary.end to define paired tokens that enclose root-level values.
Examples
In this example, we have configured root value boundaries to use double square brackets.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
root_value_boundary:
start: '[['
end: ']]'
This key defines the end token for root value boundaries when parsing snippet parameters.
The value is a string that specifies the token that marks the end of a root-level value in snippet parameter parsing. This works together with root_value_boundary.start to define paired tokens that enclose root-level values.
Examples
In this example, we have configured root value boundaries to use double square brackets.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
root_value_boundary:
start: '[['
end: ']]'
This key defines which value types do not require root value boundaries when parsing snippet parameters.
The value is an object where each property key is a value type name and each property value is a boolean. When set to true, that value type does not require root value boundaries. For example, MDX specifies { string: true }, which allows strings to exist as <Component arg="true" /> rather than <Component arg={"true"} />.
Examples
In this example, we have configured root value boundaries to be optional for strings.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
root_value_boundary_optional:
string: true
This key defines the delimiter that separates a key from its value in key-value pairs when parsing snippet parameters.
The value is a string that specifies the delimiter token. For pairs such as key="value", this would be =. For pairs such as key: "value", this would be : .
Examples
In this example, we have configured root value delimiter to use an equals sign.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
root_value_delimiter: '='
This key defines the delimiters that separate each key-value pair from the next when parsing snippet parameters.
The value is an array of strings, where each string specifies a delimiter token. For segments such as href="about" title="Hello World", this would be [" "] (a space). For segments such as href: about, title: "Hello World", this would be [","].
Examples
In this example, we have configured root pair delimiter to use a space.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
root_pair_delimiter:
- ' '
This key toggles whether CloudCannon will remove root boundary tokens from the source code when a key-value segment is empty.
Setting this key to true will remove root boundary tokens when the segment is empty.
By default, this key is false (i.e., root boundary tokens are not removed when segments are empty).
Examples
In this example, we have configured snippet format to remove empty root boundaries from source code.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
remove_empty_root_boundary: true
This key defines the characters that start and end object literals when parsing snippet parameters.
The value is an object that contains start and end properties, each specifying a string token. For objects, this will usually be { start: "{", end: "}" }.
Examples
In this example, we have configured object boundaries to use curly braces.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
object_boundary:
start: '{'
end: '}'
2 nested properties
This key defines the start token for object boundaries when parsing snippet parameters.
The value is a string that specifies the token that marks the start of an object in snippet parameter parsing. This works together with object_boundary.end to define paired tokens that enclose objects.
Examples
In this example, we have configured object boundaries to use curly braces.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
object_boundary:
start: '{'
end: '}'
This key defines the end token for object boundaries when parsing snippet parameters.
The value is a string that specifies the token that marks the end of an object in snippet parameter parsing. This works together with object_boundary.start to define paired tokens that enclose objects.
Examples
In this example, we have configured object boundaries to use curly braces.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
object_boundary:
start: '{'
end: '}'
This key defines the delimiter that separates a key from its value within an object when parsing snippet parameters.
The value is a string that specifies the delimiter token. If required, this will usually be :.
Examples
In this example, we have configured object value delimiter to use a colon.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
object_boundary:
start: '{'
end: '}'
object_value_delimiter: ':'
This key defines the delimiter that separates each key-value pair from the next within an object when parsing snippet parameters.
The value is a string that specifies the delimiter token. If required, this will usually be ,.
Examples
In this example, we have configured object pair delimiter to use a comma.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
object_boundary:
start: '{'
end: '}'
object_pair_delimiter: ','
This key defines the characters that start and end array literals when parsing snippet parameters.
The value is an object that contains start and end properties, each specifying a string token. For arrays, this will usually be { start: "[", end: "]" }.
Examples
In this example, we have configured array boundaries to use square brackets.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
array_boundary:
start: '['
end: ']'
2 nested properties
This key defines the start token for array boundaries when parsing snippet parameters.
The value is a string that specifies the token that marks the start of an array in snippet parameter parsing. This works together with array_boundary.end to define paired tokens that enclose arrays.
Examples
In this example, we have configured array boundaries to use square brackets.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
array_boundary:
start: '['
end: ']'
This key defines the end token for array boundaries when parsing snippet parameters.
The value is a string that specifies the token that marks the end of an array in snippet parameter parsing. This works together with array_boundary.start to define paired tokens that enclose arrays.
Examples
In this example, we have configured array boundaries to use square brackets.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
array_boundary:
start: '['
end: ']'
This key defines the delimiter that separates each value from the next within an array when parsing snippet parameters.
The value is a string that specifies the delimiter token. If required, this will usually be ,.
Examples
In this example, we have configured array delimiter to use a comma.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
array_boundary:
start: '['
end: ']'
array_delimiter: ','
This key defines the valid tokens that can bound a string when parsing snippet parameters.
The value is an array of strings, where each string specifies a valid boundary token. The parser will ensure the matched end token is the same as the start token. To handle common strings with either single or double quotes, this would usually be ["'", "\""].
Examples
In this example, we have configured string boundaries to allow single and double quotes.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
string_boundary:
- '"'
- "'"
This key defines the character that can be placed before a string boundary to escape it when parsing snippet parameters.
The value is a string that specifies the escape character. If required, this will usually be \.
Examples
In this example, we have configured string escape character to use a backslash.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
string_escape_character: '\\'
This key toggles whether CloudCannon will allow unquoted boolean values like true and false when parsing snippet parameters.
Setting this key to true will allow unquoted boolean values in snippet parameter parsing.
By default, this key is false (i.e., unquoted boolean values are not allowed).
Examples
In this example, we have configured snippet format to allow unquoted boolean values.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
allow_booleans: true
This key toggles whether CloudCannon will allow unquoted numbers like 5 and -0.4 when parsing snippet parameters.
Setting this key to true will allow unquoted numeric values in snippet parameter parsing.
By default, this key is false (i.e., unquoted numbers are not allowed).
Examples
In this example, we have configured snippet format to allow unquoted numbers.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
allow_numbers: true
This key toggles whether CloudCannon will allow keys without values to imply a value of true when parsing key-value pairs in snippet parameters.
Setting this key to true will allow keys to be specified without values, which will be interpreted as true.
By default, this key is false (i.e., keys without values are not allowed).
Examples
In this example, we have configured snippet format to allow implied values for keys without values.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
allow_implied_values: true
This key toggles whether CloudCannon will allow null values when parsing snippet parameters.
Setting this key to true will allow null values in snippet parameter parsing.
By default, this key is false (i.e., null values are not allowed).
Examples
In this example, we have configured snippet format to allow null values in parameter parsing.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
allow_null: true
This key defines tokens that stop parsing content as soon as they are encountered when parsing snippet parameters.
The value is an array of strings, where each string specifies a forbidden token. This is useful when the content parser is being greedy and consuming more input than intended.
Examples
In this example, we have configured forbidden tokens to stop parsing when encountering a less-than sign.
_snippets:
highlight:
snippet: "<<highlight>> [[content]] <</highlight>>"
params:
content:
parser: content
options:
editor_key: highlighted_text
format:
forbidden_tokens:
- '<'
This key defines which string case types are allowed when parsing snippet parameters.
The value is an object that can contain any, leading_upper, leading_lower, lower, or upper properties. Each property is a boolean that enables or disables that case type.
Examples
In this example, we have configured snippet format to allow only lowercase strings.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
allowed_string_cases:
lower: true
5 nested properties
This key toggles whether CloudCannon will allow any string case type when parsing snippet parameters.
Setting this key to true will allow any case type (uppercase, lowercase, mixed case) in snippet parameter parsing.
By default, this key is false (i.e., case restrictions apply based on other allowed_string_cases settings).
Examples
In this example, we have configured snippet format to allow any string case type.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
allowed_string_cases:
any: true
This key toggles whether CloudCannon will allow strings starting with an uppercase letter when parsing snippet parameters.
Setting this key to true will allow strings that begin with an uppercase letter in snippet parameter parsing.
By default, this key is false (i.e., strings starting with uppercase are not allowed unless any is enabled).
Examples
In this example, we have configured snippet format to allow strings starting with an uppercase letter.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
allowed_string_cases:
leading_upper: true
This key toggles whether CloudCannon will allow strings starting with a lowercase letter when parsing snippet parameters.
Setting this key to true will allow strings that begin with a lowercase letter in snippet parameter parsing.
By default, this key is false (i.e., strings starting with lowercase are not allowed unless any is enabled).
Examples
In this example, we have configured snippet format to allow strings starting with a lowercase letter.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
allowed_string_cases:
leading_lower: true
This key toggles whether CloudCannon will allow only lowercase strings when parsing snippet parameters.
Setting this key to true will require all characters to be lowercase in snippet parameter parsing.
By default, this key is false (i.e., lowercase-only strings are not required unless any is enabled).
Examples
In this example, we have configured snippet format to allow only lowercase strings.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
allowed_string_cases:
lower: true
This key toggles whether CloudCannon will allow only uppercase strings when parsing snippet parameters.
Setting this key to true will require all characters to be uppercase in snippet parameter parsing.
By default, this key is false (i.e., uppercase-only strings are not required unless any is enabled).
Examples
In this example, we have configured snippet format to allow only uppercase strings.
_snippets:
example:
snippet: "<<example [[param]]>>"
params:
param:
parser: argument
options:
format:
allowed_string_cases:
upper: true
This key defines styling options for snippet output formatting.
The value is an object that can contain output, inline, and block properties. These options control how snippet content is parsed and formatted to produce cleaner source code.
Examples
In this example, we have configured snippet style with inline and block formatting options.
_snippets:
highlight:
snippet: "<<highlight>> [[content]] <</highlight>>"
params:
content:
parser: content
options:
style:
inline:
leading: ' '
trailing: ' '
block:
leading: '\n'
trailing: '\n'
indent: ' '
This key defines the output format style for snippet content.
The value can be legacy, inline, or block. This controls how snippet content is formatted when output to source code.
Examples
In this example, we have configured snippet output style to use block formatting.
_snippets:
highlight:
snippet: "<<highlight>> [[content]] <</highlight>>"
params:
content:
parser: content
options:
style:
output: block
This key defines inline formatting options for snippet output.
The value is an object that can contain leading and trailing properties. These options control whitespace for single-line snippet content.
Examples
In this example, we have configured inline formatting with leading and trailing spaces.
_snippets:
highlight:
snippet: "<<highlight>> [[content]] <</highlight>>"
params:
content:
parser: content
options:
style:
inline:
leading: ' '
trailing: ' '
2 nested properties
This key defines the leading whitespace string for inline snippet content.
The value is a string that specifies whitespace tokens (typically spaces) inserted before inline snippet content.
Examples
In this example, we have configured inline leading whitespace to use a space.
_snippets:
highlight:
snippet: "<<highlight>> [[content]] <</highlight>>"
params:
content:
parser: content
options:
style:
inline:
leading: ' '
This key defines the trailing whitespace string for inline snippet content.
The value is a string that specifies whitespace tokens (typically spaces) inserted after inline snippet content.
Examples
In this example, we have configured inline trailing whitespace to use a space.
_snippets:
highlight:
snippet: "<<highlight>> [[content]] <</highlight>>"
params:
content:
parser: content
options:
style:
inline:
trailing: ' '
This key defines block-level formatting options for snippet output.
The value is an object that can contain leading, trailing, and indent properties. These options control whitespace and indentation for multi-line snippet content.
Examples
In this example, we have configured block formatting with leading, trailing, and indent options.
_snippets:
highlight:
snippet: "<<highlight>> [[content]] <</highlight>>"
params:
content:
parser: content
options:
style:
block:
leading: '\n'
trailing: '\n'
indent: ' '
3 nested properties
This key defines the leading whitespace string for block-level snippet content.
The value is a string that specifies whitespace tokens (typically newlines) inserted before block-level snippet content.
Examples
In this example, we have configured block leading whitespace to use a newline.
_snippets:
highlight:
snippet: "<<highlight>> [[content]] <</highlight>>"
params:
content:
parser: content
options:
style:
block:
leading: '\n'
This key defines the trailing whitespace string for block-level snippet content.
The value is a string that specifies whitespace tokens (typically newlines) inserted after block-level snippet content.
Examples
In this example, we have configured block trailing whitespace to use a newline.
_snippets:
highlight:
snippet: "<<highlight>> [[content]] <</highlight>>"
params:
content:
parser: content
options:
style:
block:
trailing: '\n'
This key defines the indentation string used for block-level snippet content.
The value is a string that specifies the indentation tokens (typically spaces or tabs) applied to each line of block-level snippet content.
Examples
In this example, we have configured block indentation to use two spaces.
_snippets:
highlight:
snippet: "<<highlight>> [[content]] <</highlight>>"
params:
content:
parser: content
options:
style:
block:
indent: ' '
This key defines snippet templates or libraries for your Site.
Some libraries are SSG specific while others work for most SSGs.
For more information, please read our documentation on Docusaurus Components, Eleventy Shortcodes, Hugo Shortcodes, MDX Components, or Python Markdown.
Examples
In this example, we have configured Hugo shortcode imports for the Site.
_snippets_imports:
hugo:
include:
- figure
- youtube
This key defines the list of excluded snippets.
If unset, all snippets are excluded unless defined in include.
This key defines the list of included snippets.
If unset, all snippets are included unless defined in exclude.
This key defines extended options used when creating more complex custom snippets.
A record of reusable values that can be referenced in snippet templates. Values are substituted using { ref: "key" } for direct replacement or { spread_ref: "key" } for spreading arrays/objects. Common definition types include parser formats, argument models, select option lists, and simple string values like shortcode names.
Examples
Define reusable values like shortcode names, argument models, and parser formats that can be referenced in snippet templates.
_snippets_definitions:
# Simple string value for the shortcode name
shortcode_name: "highlight"
content_key: "content"
# Array of argument models for positional arguments
positional_args:
- editor_key: "language"
type: "string"
- editor_key: "linenos"
type: "boolean"
optional: true
default: false
# Parser format configuration
custom_format:
root_pair_delimiter:
- " "
root_value_delimiter: "="
string_boundary:
- '"'
- "'"
- ""
allow_booleans: true
allow_numbers: true
Reference definitions in snippet templates using { ref: "key" } syntax. This allows you to reuse common configurations across multiple snippets.
_snippets_definitions:
shortcode_name: "figure"
named_args:
- editor_key: "src"
type: "string"
- editor_key: "alt"
type: "string"
optional: true
_snippets_templates:
my_shortcode_template:
snippet: "{{< [[name]] [[args]] >}}"
params:
name:
parser: "literal"
options:
literal:
ref: "shortcode_name"
args:
parser: "key_values"
options:
models:
ref: "named_args"
_snippets:
figure:
template: "my_shortcode_template"
definitions:
shortcode_name: "figure"
named_args:
- editor_key: "src"
type: "string"
- editor_key: "alt"
type: "string"
Define a list of select options for use in snippet inputs, such as a list of programming languages for a code highlighting snippet.
_snippets_definitions:
languages:
- name: "JavaScript"
value: "js"
- name: "Python"
value: "python"
- name: "Ruby"
value: "ruby"
- name: "HTML"
value: "html"
- name: "CSS"
value: "css"
A reusable value that can be referenced in snippet templates via { ref: "key" } or { spread_ref: "key" }. Can be a string, number, boolean, parser format, parser model, array of models, or array of select options.
A value option for select inputs, typically used in language lists. Contains a display name and the actual value to use.
The actual value used when this option is selected. Can be a string, number, or boolean. For example, "js" for JavaScript or 4 for an indentation level.
The display name shown to users when selecting this option. For example, "JavaScript" for a language with value "js".