Using the configuration cascade

Last modified: January 30th, 2024

Working with a specific static site generator?
Customize CloudCannon's documentation to suit your SSG.

Great! We'll show you documentation relevant to .
You can change this any time using the dropdown in the navigation bar.

The configuration cascade is a set of sources containing customizable options for the editor. Each source has a different scope and priority. This allows you to set global defaults and override those for specific collections or files.

When CloudCannon needs an option you have set in the configuration cascade, it looks at each scope in order. In most cases, the cascade stops looking when an option is found. This means the most specific value is used in place of any less specific values.

Input configuration (i.e. _inputs) has a different cascading default, where CloudCannon continues looking over less specific sources to merge into a single option.

Sources#

The configuration cascade sources are as follows, from lowest priority to highest:

  1. Global configuration
  2. Collection configuration
  3. Schema configuration
  4. Front matter
  5. Containing structure

Global configuration#

For configuring everywhere on your site. For example:

cloudcannon.config.yaml
copied
_inputs:
  image_path:
    type: image
    comment: Helpful message here
    options:
      width: 90
      height: 120
_select_data:
  colors:
    - Red
    - Blue
cloudcannon.config.json
copied
{
  "_inputs": {
    "image_path": {
      "type": "image",
      "comment": "Helpful message here",
      "options": {
        "width": 90,
        "height": 120
      }
    }
  },
  "_select_data": {
    "colors": [
      "Red",
      "Blue"
    ]
  }
}
cloudcannon.config.js
copied
module.exports = {
  _inputs: {
    image_path: {
      type: "image",
      comment: "Helpful message here",
      options: {
        width: 90,
        height: 120
      }
    }
  },
  _select_data: {
    colors: [
      "Red",
      "Blue"
    ]
  }
};

Collection configuration#

For configuring all files within a collection. For example:

cloudcannon.config.yaml
copied
collections_config:
  pages:
    _inputs:
      image_path:
        type: image
        comment: Helpful message here
        options:
          width: 90
          height: 120
    _select_data:
      colors:
        - Red
        - Blue
cloudcannon.config.json
copied
{
  "collections_config": {
    "pages": {
      "_inputs": {
        "image_path": {
          "type": "image",
          "comment": "Helpful message here",
          "options": {
            "width": 90,
            "height": 120
          }
        }
      },
      "_select_data": {
        "colors": [
          "Red",
          "Blue"
        ]
      }
    }
  }
}
cloudcannon.config.js
copied
module.exports = {
  collections_config: {
    pages: {
      _inputs: {
        image_path: {
          type: "image",
          comment: "Helpful message here",
          options: {
            width: 90,
            height: 120
          }
        }
      },
      _select_data: {
        colors: [
          "Red",
          "Blue"
        ]
      }
    }
  }
};

Schema configuration#

For configuring all files within one of a collection's schemas. For example:

cloudcannon.config.yaml
copied
collections_config:
  pages:
    schemas:
      default:
        path: schemas/page.md
        _inputs:
          image_path:
            type: image
            comment: Helpful message here
            options:
              width: 90
              height: 120
      landing_page:
        path: schemas/landing-page.md
        _select_data:
          colors:
            - Red
            - Blue
cloudcannon.config.json
copied
{
  "collections_config": {
    "pages": {
      "schemas": {
        "default": {
          "path": "schemas/page.md",
          "_inputs": {
            "image_path": {
              "type": "image",
              "comment": "Helpful message here",
              "options": {
                "width": 90,
                "height": 120
              }
            }
          }
        },
        "landing_page": {
          "path": "schemas/landing-page.md",
          "_select_data": {
            "colors": [
              "Red",
              "Blue"
            ]
          }
        }
      }
    }
  }
}
cloudcannon.config.js
copied
module.exports = {
  collections_config: {
    pages: {
      schemas: {
        default: {
          path: "schemas/page.md",
          _inputs: {
            image_path: {
              type: "image",
              comment: "Helpful message here",
              options: {
                width: 90,
                height: 120
              }
            }
          }
        },
        landing_page: {
          path: "schemas/landing-page.md",
          _select_data: {
            colors: [
              "Red",
              "Blue"
            ]
          }
        }
      }
    }
  }
};

Front matter#

For configuring a single file. For example:

Configuration
copied
image_path: /uploads/me.png
_inputs:
  image_path:
    type: image
    comment: Helpful message here
    options:
      width: 90
      height: 120
_select_data:
  colors:
    - Red
    - Blue
Configuration
copied
{
  "image_path": "/uploads/me.png",
  "_inputs": {
    "image_path": {
      "type": "image",
      "comment": "Helpful message here",
      "options": {
        "width": 90,
        "height": 120
      }
    }
  },
  "_select_data": {
    "colors": [
      "Red",
      "Blue"
    ]
  }
}
Configuration
copied
image_path = "/uploads/me.png"

[_inputs.image_path]
type = "image"
comment = "Helpful message here"

  [_inputs.image_path.options]
  width = 90
  height = 120

[_select_data]
colors = [ "Red", "Blue" ]

Containing structure#

For configuring inputs inside inside a structure. For example:

Configuration
copied
_structures:
  gallery:
    values:
      - label: Image
        icon: image
        _inputs:
          image:
            type: image
            options:
              width: 50
              height: 50
          caption:
            comment: Applies inside this structure
        _select_data:
          colors:
            - Red
            - Blue
        value:
          image: /uploads/placeholder.png
          caption: 
          color: 
Configuration
copied
{
  "_structures": {
    "gallery": {
      "values": [
        {
          "label": "Image",
          "icon": "image",
          "_inputs": {
            "image": {
              "type": "image",
              "options": {
                "width": 50,
                "height": 50
              }
            },
            "caption": {
              "comment": "Applies inside this structure"
            }
          },
          "_select_data": {
            "colors": [
              "Red",
              "Blue"
            ]
          },
          "value": {
            "image": "/uploads/placeholder.png",
            "caption": null,
            "color": null
          }
        }
      ]
    }
  }
}
Configuration
copied
[[_structures.gallery.values]]
label = "Image"
icon = "image"

[_structures.gallery.values._inputs.image]
type = "image"

  [_structures.gallery.values._inputs.image.options]
  width = 50
  height = 50

[_structures.gallery.values._inputs.caption]
comment = "Applies inside this structure"

  [_structures.gallery.values._select_data]
  colors = [ "Red", "Blue" ]

  [_structures.gallery.values.value]
  image = "/uploads/placeholder.png"

For nested structured data, you can nest _structures alongside the other configuration groups inside a structure definition.

Options#

Since configuration cascade options can be defined alongside your data, they always begin with an underscore in an effort to avoid clashing with a key you would use.

The following configuration cascade options are available:

_editables - Object#

Contains input options for Editable Regions and the Content Editor. Read more about the defining editable regions and controlling the available options.

_enabled_editors - Array of strings#

Controls how your team edits specific files, use this to set a preferred editor and/or disable the others. The first value sets which editor opens from the collection list, the other values specify which editors are accessible. Available values are:

The Source Editor is always available for those with permission.

_inputs - Object#

Contains configuration for controlling the behavior and appearance of your inputs in the Data Editor. Read more about how inputs work.

_select_data - Object#

Definitions of fixed data sets available to populate select and multiselect inputs.

_structures - Object#

Provides structure definitions at a global scope. This allows you to provide multiple values when editors set objects or add items to arrays in the Data Editor.

Open in a new tab