Configure the editors for your needs.
Options can be set for keys matching the same name in four ways:
In your site configuration - Use this if you want a configuration available globally on your site. For example:
_options:
image_path:
width: 90
height: 120
# other config content
As a Jekyll default - Useful if you want to scope a configuration to a particular collection. For example:
defaults:
-
scope:
path: ""
type: "posts"
values:
_options:
image_path:
width: 90
height: 120
# other config content
[params._options.image_path]
width = 90
height = 90
# other config content
In front matter - If you want configuration only for a single file. For example:
_options:
image_path:
width: 90
height: 120
[_options.image_path]
width = 90
height = 130
On an element - Some options allow you to configure based on a particular element. For example:
<p class="editable" data-cms-options='{"bold": true, "italic": true}'>...</p>
CloudCannon will use the most specific option that applies. In order of specificity: data-cms-options
attributes, front matter, and Jekyll defaults, then globally in _config.yml
.
CloudCannon will use the most specific option that applies. In order of specificity: data-cms-options
attributes, front matter, then globally in your site config.
Control which front matter fields your editors see with the hidden
option.
_options:
layout:
hidden: true
[_options.layout]
hidden = true
Hidden fields can be edited with modal-style Editor Links.
Alternatively, you can hide front matter fields by prefixing the key with an underscore (_hidden_text
).
Change the appearance and behavior of your front matter code blocks to fit your use case and brand.
_options:
code_block:
tab_size: 2
show_gutter: false
javascript_code_block:
tab_size: 4
theme: dawn
[_options.code_block]
tab_size = 2
show_gutter = false
[_options.javascript_code_block]
tab_size = 4
theme = "dawn"
tab_size
Integer (Optional, defaults to 4)
Controls how many spaces lines are auto indented.
theme
String
Must match one from themes (optional, defaults to monokai).
Controls the appearance of the editor.
show_gutter
Boolean (Optional, defaults to true)
Toggles line numbers and code folding controls.
You can restrict which filetypes editors can upload in certain fields in the visual editor. This is done by using the accepts_mime_types
option.
For example, if you wanted to make sure that your editors could only upload png and svg files in the featured_image
field of each blog post:
Scoped within your _config.yml
defaults:
-
scope:
path: ""
type: "posts"
values:
layout: "post"
push_sidebar_down: true
print_stylesheet: true
comments: true
_options:
content:
width: 1560
height: 2000
featured_image:
width: 1560
height: 2000
accepts_mime_types:
- "image/png"
- "image/svg+xml"
Or if you wanted to set the option on a more refined scope, configure the liquid front-matter in _defaults.md
or in individual files Markdown files like so:
---
_options:
featured_image:
accepts_mime_types:
- "image/png"
- "image/svg+xml"
---
Within Front Matter for each file:
_options:
featured_image:
accepts_mime_types:
- "image/png"
- "image/svg+xml"
[_options.featured_image]
accepts_mime_types = [
"image/png",
"image/scg+xml"
]
Not setting the accepts_mime_type
option will allow all files of the appropriate type within the field. For example, in an image field an editor could upload any image with a valid ‘image’ extension (.jpg
, .jpeg
, .png
, etc.).
Create reusable components which content editors use to create their own feature-rich pages. To set up an array structure, you define the different components available. When a content editor adds an item to the array in a CloudCannon Editor, it will give them the option to select one of the components. This adds that component to the array where they can then fill out the inputs.
For example, set the structure for new items in a gallery
array with:
Configured per-file in front matter or globally in _config.yml
:
gallery:
style: select
values:
- label: Image
image: /path/to/source-image.png
value:
image: /placeholder.png
caption:
- label: External link
icon: link
value:
url:
title:
Alternatively, configure on a custom scope with Jekyll defaults:
defaults:
- scope:
path: ''
type: 'pages'
values:
_array_structures:
gallery:
style: modal
values:
- label: Image
icon: image
tags:
- Media
- Asset
value:
image: /placeholder.png
caption:
- label: External link
icon: link
description: A link to another web site
tags:
- Raw value
value:
url:
title:
Within the front matter of a content file:
[[_array_structures.gallery.values]]
label = "Image"
icon = "image"
[_array_structures.gallery.values.value]
image = "/placeholder.png"
caption = ""
Or globally by adding to your config’s params
object:
[[params._array_structures.gallery.values]]
label = "Image"
icon = "image"
[params._array_structures.gallery.values.value]
image = "/placeholder.png"
caption = ""
If you need editors to add different types to an array, you can also define multiple structures:
_array_structures:
gallery:
style: select
values:
- label: Image
image: /path/to/source-image.png
value:
image: /placeholder.png
caption:
- label: External link
icon: link
value:
url:
title:
[[_array_structures.gallery.values]]
label = "Image"
icon = "image"
[_array_structures.gallery.values.value]
image = "/placeholder.png"
caption = ""
[[_array_structures.gallery.values]]
label = "External link"
image = "link"
[_array_structures.gallery.values.value]
url = ""
title = ""
You can customize the Array Structure interface for your editors with the following options:
The label
is used in the array interface to display what kind of item(s) editors can add.
The description
is used in the array interface as subtext to describe the item(s) editors can add.
The icon
is a Material Design icon name for customising how the array item preview.
The image
is a path to an image in your source files to be used in place of the icon (icon
takes precedence if both present).
The style
defines whether the items are shown to your editors in a select menu (select
, default) or a modal pop up window (modal
).
The tags
are used to group and filter items when selecting a structure from an add modal.
See below for usage:
_array_structures:
gallery:
style: modal
values:
- label: Image
icon: image
tags:
- Media
- Asset
value:
image: /placeholder.png
caption:
- label: External link
icon: link
description: A link to another web site
tags:
- Raw value
value:
url:
title:
[_array_structures.gallery]
style = "modal"
[[_array_structures.gallery.values]]
label = "Image"
icon = "image"
tags = ["Media", "Asset"]
[_array_structures.gallery.values.value]
image = "/placeholder.png"
caption = ""
[[_array_structures.gallery.values]]
label = "External link"
icon = "link"
description = "A link to another website"
tags = ["Raw value"]
[_array_structures.gallery.values.value]
url = ""
title = ""
New array items have their keys and values populated from the value
you set. If no structure is defined, new array items clone the structure from existing array items.
Keep a consistent file structure by setting up an uploads path structure. Images, documents, and other files in the editor are uploaded to this location.
_options:
image: # Front matter field
uploads_dir: "uploads/front-matter-images/:title"
content: # Content Editor and block Editable Regions
uploads_dir: "uploads/:year/:month/:day/:title"
[_options.image] # Front matter field
uploads_dir = "uploads/front-matter-images/:title"
[_options.content] # Content Editor and block Editaable Regions
uploads_dir = "uploads/:year/:month/:day/:title"
The :categories
and :title
dynamic fields resolve to the associated Front Matter fields for the containing file. :year
, :month
, and :day
are obtained from the date
Front Matter field for the containing file.
You can also set site.uploads_dir
in your _config.yml
to set it everywhere:
uploads_dir: "uploads/:categories/:year/:month/:day/:title"
You can also set uploadsDir
in your site’s config to set it everywhere:
uploadsDir = "uploads/:categories/:year/:month/:day/:title"
Control the size and format of images clients or team members upload through the interface. Images are resized and converted automatically.
Set options for images uploaded with the Content Editor and block element Editable Regions using the content
key. Options for front matter interfaces are specified by matching key names.
options:
image_path:
width: 90
height: 120
resize_style: "contain"
mime_type: "image/jpeg"
expandable: true
content:
width: 90
height: 120
resize_style: "cover"
mime_type: "image/png"
[_options.image_path]
width = 90
height = 120
resize_style = "contain"
mime_type = "image/jpeg"
expandable = true
[_options.content]
width = 90
height = 120
resize_style = "cover"
mime_type = "image/png"
width
Integer
Defines the width of the bounding box
height
Integer
Defines the height of the bounding box
resize_style
String, one of contain, cover or stretch (optional, defaults to contain)
Defines how uploaded images are resized with respect to that box:
mime_type
String, one of* image/jpeg, *image/png (optional, defaults to uploaded type if supported)
Sets what format the image is converted into on upload.
expandable
Boolean (optional, defaults to false)
Set to true allows images to be enlarged past original dimensions.
CloudCannon automatically adds size attributes (width, height, sizes) to the HTML for images uploaded in the Content Editor and Editable Regions.
This allows browsers to size <img>
elements before CSS and images are loaded. Otherwise, the page can shift around in front of the viewer as images are loaded, and elements are resized.
These attributes are also required for srcset
attributes to work properly. Browsers assume by default that the width of an image is 100vw. If the image has a srcset
but no explicit size attributes, it will appear full width regardless of the srcset
.
In cases where these size attributes are not right for your layout, some simple CSS can ensure that your images are sized correctly on the page. Define a width for your images, then set height
to auto
. This will allow the browser to calculate the appropriate height for your image based on the width.
img {
max-width: 100%;
height: auto;
}
Control the toolbar options for your clients or editors to increase focus on the content at hand.
Set toolbar options for the Content Editor with the content
key, and Editable Regions using the _block
and _text
keys. Options for Rich Text front matter interfaces are specified by matching key names.
_options:
some_markdown:
bold: true
table: true
_text:
italic: true
_block:
format: p h3
undo: true
redo: true
content:
format: p h1 h2 h3 h4 h5 h6 pre address div
bold: true
numberedlist: true
code: true
table: true
right: align-to-right
styles: /_sass/_content-typography.scss
embed: true
[_options.some_markdown]
bold = true
table = true
[_options._text]
italic = true
[_options._block]
format = "p h3"
undo = true
redo = true
[_options.content]
format = "p h1 h2 h3 h4 h5 h6 pre address div"
bold = true
numberedlist = true
code = true
table = true
right = align-to-right
styles = "/_sass/_content-typography.scss"
embed = true
You can also set options directly on elements for Editable Regions:
<p class="editable" data-cms-options='{"bold": true, "italic": true}'>...</p>
bold
Boolean
redo
Boolean
underline
Boolean
strike
Boolean
subscript
Boolean
superscript
Boolean
code
Boolean
(unavailable for _text
)
format
String, Space separated options
(unavailable for _text
)
blockquote
Boolean
(unavailable for _text
)
horizontalrule
Boolean
(unavailable for _text
)
numberedlist
Boolean
(unavailable for _text
)
bulletedlist
Boolean
(unavailable for _text
)
outdent
Boolean
(unavailable for _text
)
indent
Boolean
(unavailable for _text
)
image
Boolean
(unavailable for _text
)
embed
Boolean
(unavailable for _text
)
table
Boolean
(unavailable for _text
)
styles
String, path to CSS file
(unavailable for _text
)
left
String, class name
(unavailable for _text
)
center
String, class name
(unavailable for _text
)
right
String, class name
(unavailable for _text
)
justify
String, class name
(unavailable for _text
)
The removeformat
and copyformatting
options in the editor only apply to bold
, italic
, underline
, strike
, subscript
, and superscript
. The controls do not remove or copy other styles or formatting.
Allow your editors to embed YouTube, Vimeo, Tweets, and other media into their content. Embedded content is sanitized to mitigate XSS risks, which includes removing style
tags. Embeds containing script
tags are not loaded in the editor.
_options:
content:
embed: true
[_options.content]
embed = true
Add predefined styles in plain CSS for your clients and team members to use in the Visual Editor, Content Editor, and Front Matter interfaces.
_options:
content:
styles: /css/editor.css
[_options.content]
styles = "/css/editor.css"
The file can be in either source or output. The source CSS file is used if both exist. In either case, it must contain plain CSS.
Selectors must specify an element and one class in order to be included in the styles dropdown. Styles with incompatible selectors are included in the editor, but not shown as options.
p.callout { /* Can be applied to blocks of content */margin: 10px;
border: 1px solid #f5f5f5;
background-color: #eee;
}
span.big-blue-text { /* Can be applied to inline content */font-size: 2rem;
color: blue;
}
h2 { /* Applied to content, excluded from style dropdown */font-family: cursive;
}
.center-this-text { /* Excluded from style dropdown, used as center class described below */text-align: center;
}
Custom styles in the Visual Editor require the same styles on your live site. If you don’t have the same styles on your live site, the class will be there but it won’t change the styling.
Use the justification options to specify classes for alignment rather than the dropdown for a better editing experience:
_options:
_block:
left: align-left
center: center-this-text
right: align-right
justify: full-width-text
[_options.block]
left = "align-left"
center = "center-this-text"
right = "align-right"
justify = "full-width-text"
Be sure to include these classes in your styles CSS for them to take effect.
Helper text to provide additional context.
Configured globally in _config.yml
or per file in front matter with a _comments
object:
_comments:
title: The page title
output: Does this item have a dedicated page?
brand_color: The primary brand color
footer: Update the details in the footer
Alternatively, configure comments on a custom scope with Jekyll defaults:
defaults:
- scope:
path:
type:
values:
_comments:
title: The page title
output: Does this item have a dedicated page?
brand_color: The primary brand color
footer: Update the details in the footer
Configured with a _comments
object - globally in the params
object in your site’s config, or per-file in Front Matter:
# in Front Matter
[_comments]
title = "The page title"
output = "Does this item have a dedicated page?"
brand_color = "The primary brand color"
footer = "Update the details in the footer"
# in config.toml
[params._comments]
title = "The page title"
output = "Does this item have a dedicated page?"
brand_color = "The primary brand color"
footer = "Update the details in the footer"
Comments are displayed for fields with the same keys as in the _comments
object.