Skip to content
Home button
  • Pricing
Edit
Skip to content

Configuration

On this page:

Loading...

CloudCannon offers different configuration options for each input and editor. Use this to improve the editing experience for your sites.

Configuration can be set from a number of sources, from lowest priority to highest:

  1. Site configuration
  2. Collection configuration
  3. Front matter
  4. Containing array structure
  5. Element data attribute

Inside each of these sources, the configuration groups are _options, _select_data, _array_structures and _comments.

Configuration for inputs and editors is set with properties on the key matching the same name. (e.g. _options.image matches the image front matter input).

Site configuration - configure something everywhere on your site. For example:

_config.yml 
_options:
  image_path:
    width: 90
    height: 120
_comments:
  image_path: Helpful message here
_select_data:
  colors:
    - Red
    - Blue
Note

Use Jekyll defaults to target collections and other groups of files to reduce front matter per file (in addition to global configuration).

Collection configuration - configure inputs for files in a collection. For example:

Configuration 
cloudcannon:
  collections:
    products:
      _options:
        image_path:
          width: 90
          height: 120
      _comments:
        image_path: Helpful message here
      _select_data:
        colors:
          - Red
          - Blue

Front matter - configure inputs inside a single file. For example:

Configuration 
image_path: /uploads/me.png
_options:
  image_path:
    width: 90
    height: 120
_comments:
  image_path: Helpful message here
_select_data:
  colors:
    - Red
    - Blue

Containing array structure - configure inputs inside an array structure. For example:

Configuration 
_array_structures:
  gallery:
    values:
      - label: Image
        icon: image
        _options:
          image:
            width: 50
            height: 50
        _comments:
          caption: Applies inside this structure
        _select_data:
          colors:
            - Red
            - Blue
        value:
          image: /placeholder.png
          caption:
Note

For complex structured data, you can nest _array_structures alongside the other configuration groups inside an array structure definition.

Element data attribute - configure _options for a specific element. For example:

page.html 
<p class="editable" data-cms-options='{"bold": true, "italic": true}'>...</p>

Input Options

Hidden Fields

Control which front matter fields your editors see with the hidden option.

Configuration 
_options:
  layout:
    hidden: true

Hidden fields can be edited with modal-style Editor Links.

Alternatively, hide front matter fields by prefixing the key with an underscore (e.g. _hidden_text).

Code Blocks

Change the appearance and behavior of your front matter code blocks to fit your use case and brand.

Configuration 
_options:
  code_block:
    tab_size: 2
    show_gutter: false
  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.

Upload Options

File Uploads

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.

Configuration 
_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"

The :collections, :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. Any placeholder that has no value is collapsed.

You can also set site.uploads_dir in your _config.yml to set it everywhere:

_config.yml 
uploads_dir: "uploads/:categories/:year/:month/:day/:title"

Image Uploads

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.

Configuration 
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"
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:

  • cover ensures the image covers the bounding box
  • contain ensures the image fits inside the bounding box
  • stretch ignores aspect ratio to resize the image to the bounding 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.

Size Attributes

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.

styles.css 
img {
  max-width: 100%;
  height: auto;
}

Restricting file types

Restrict which files types editors can upload for specific inputs with the accepts_mime_types option.

For example, to make it so editors can only upload png and svg files in the featured_image field of each blog post:

Configuration 
_options:
  featured_image:
    accepts_mime_types:
      - "image/png"
      - "image/svg+xml"

Not setting the accepts_mime_type option allows 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.).

Rich Text Options

Toolbars

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.

Configuration 
_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

You can also set options directly on elements for Editable Regions:

index.html 
<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)

Note

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.

Embedding Media

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.

Configuration 
_options:
  content:
    embed: true

Styles

Add predefined styles in plain CSS for your clients and team members to use in the Visual Editor, Content Editor, and Front Matter interfaces.

Configuration 
_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 applied to the editor, but not shown as options.

styles.css 
/* 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;
}

/* Excluded from style dropdown, used as center class described below */
.center-this-text {
  text-align: center;
}
Note

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:

Configuration 
_options:
  _block:
    left: align-left
    center: center-this-text
    right: align-right
    justify: full-width-text
Note

Be sure to include these classes in your styles CSS for them to take effect.

Select Data

Use a fixed dataset to populate and restrict the options editors can choose within select and multiselect front matter inputs.

Configuration 
color: Red
colors:
  - Red
ssg: jekyll
ssgs:
 - hugo
 - 11ty
_select_data:
  colors:
    - Red
    - Blue
  ssgs:
    jekyll: Jekyll
    hugo: Hugo
    11ty: Eleventy
Note

In addition to _select_data, select and multiselect front matter inputs can be populated from collections and site data.

Array Structures

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. CloudCannon then provides editors the option to select one of the components when adding an item to the array. 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:

Configuration 
_array_structures:
  gallery:
    style: modal
    values:
      - label: Image
        image: /path/to/source-image.png
        icon: image
        tags:
          - Media
          - Asset
        value:
          image: /placeholder.png
          caption:
      - label: External link
        icon: link
        tags:
          - Media
        value:
          url:
          title:

Define a single structure to skip the choice step when adding items.

Configuration 
_array_structures:
  gallery:
    style: select
    values:
      - label: Image
        icon: image
        value:
          image: /placeholder.png
          caption:

Customize the array structure interface for your editors with the following options:

label

String

Used in the array interface to display what kind of items editors can add.

description

String

Used in the array interface as subtext to describe the items editors can add.

icon

String (Material Design icon name)

An icon used when displaying the array structure.

image

String

Path to an image in your source files to be used when displaying the array structure.

image_size

String (cover, contain, or padded)

Defines how the image is displayed within its containing box.

style

String (modal or select)

Defines whether the items are shown to your editors in a select menu (select, default) or a modal pop up window (modal).

tags

Array

Used to group and filter items when selecting from a modal.

Note

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.

Comments

Helper text to provide additional context.

Configuration 
_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.

Instance Values

Values which are hydrated at create time in the editor. Used when files are created from collection defaults and when array items are added using array structures.

__CLOUDCANNON_UUID

String

Generates a uuidv4, useful to indentify each unique item. e.g. 6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b.

__CLOUDCANNON_NOW

Datetime

The current datetime in the site configured timezone. Output will be dependant on the input used, either Date Time or Date.

Configuration 
_uuid: __CLOUDCANNON_UUID
created_at: __CLOUDCANNON_NOW
Previous
Collections
Edit / Editing
Next
Introduction
Edit / Sharing
On this page:

Loading...

Don’t miss the latest
CloudCannon news freshly delivered to your inbox
Illustration of woman holding an envilope