Home button
Skip to content
Home button
Edit
Skip to content

Configuration

On this page:

Loading...

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:

_config.yml 
_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:

_config.yml 
defaults:
 -
   scope:
     path: ""
     type: "posts"
   values:
     _options:
       image_path:
         width: 90
         height: 120
# other config content

In front matter - If you want configuration only for a single file. For example:

Front Matter 
_options:
  image_path:
    width: 90
    height: 120

On an element - Some options allow you to configure based on a particular element. For example:

page.html 
<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.

Input Options

Hidden Fields

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

Front Matter 
_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).

Code Blocks

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

Front Matter 
_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.

Restricting file types

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

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

Front Matter 
---
_options:
  featured_image:
    accepts_mime_types:
      - "image/png"
      - "image/svg+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.).

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. 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:

_config.yml or front matter 
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:

_config.yml 
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:

If you need editors to add different types to an array, you can also define multiple structures:

config.yml 
_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:

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:

_config.yml or Front Matter 
_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:
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.

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.

Front Matter 
_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 :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:

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

Front Matter 
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;
}

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.

Front Matter 
_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.

Front Matter 
_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.

Front Matter 
_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.

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

Front Matter 
_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.

Comments

Helper text to provide additional context.

Configured globally in _config.yml or per file in front matter with a _comments object:

_config.yml or 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

Alternatively, configure comments on a custom scope with Jekyll defaults:

_config.yml 
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

Comments are displayed for fields with the same keys as in the _comments object.

Previous
Collections
Edit / Editing
Next
Introduction
Edit / Sharing
On this page:

Loading...

Don’t miss the latest
CloudCannon news freshly delivered to your inbox