Choose your preferred SSG:
Choose your preferred SSG:

Setting global configuration

We’ve recently changed the way you set global configuration. Check out our migration guide here.

Global configuration files contain your global CloudCannon configuration, and top-level values for the configuration cascade.

Configuration is set in one of the following files, the first supported file found in this order is used:

Jekyll content

  • cloudcannon.config.json
  • cloudcannon.config.yaml
  • cloudcannon.config.yml

Hugo content

Eleventy content

Other content

This file is stored in the root directory of your repository (e.g. /cloudcannon.config.*). Alternatively, use a specific config file in a custom location using the CLOUDCANNON_CONFIG_PATH environment variable:


Here’s an example file:

Jekyll content

# Global CloudCannon configuration
    type: text
    comment: The title of your page.
    - Red
    - Green
    - Blue

# Base path to your site source files, same as source for Jekyll
source: src

# The subpath your built output files are mounted at, same as baseurl for Jekyll
base_url: /documentation

# Populates collections for navigation and metadata in the editor
    # Base path for files in this collection, relative to source
    path: content/people

    # Whether this collection produces output files or not
    output: true

    # Collection-level configuration
    name: Personnel
      - data
    path: _posts
    output: true
    name: Main pages

# Generates the data for select and multiselect inputs matching these names
  # Populates data with authors from an data file with the matching name
  authors: true
  offices: true

  # The default location for newly uploaded files, relative to source
  uploads: assets/uploads

  # The path to the root collections folder, relative to source
  collections: items

  # The path to site data files, relative to source
  data: _data

  # The path to site layout files, relative to source
  layouts: _layouts

  # The path to site include files, relative to source
  includes: _partials

The following is automatically read from Jekyll if not set in the global configuration file:

  • collections_config from collections in _config.yml
  • paths.collections from collections_dir in _config.yml
  • paths.layouts from layouts_dir in _config.yml
  • from data_dir in _config.yml
  • paths.includes from includes_dir in _config.yml
  • base_url from baseurl in _config.yml
  • source from the --source CLI option or source in _config.yml

Hugo content

Eleventy content

Other content


Global configuration files have the following options available:

base_url - String

The subpath your output files are mounted at.

collections_config - Object

Contains definitions for your collections, the related sets of content files for your site grouped by folder. Entries are keyed by your collection key, and contain configuration specific to that collection. Read more about defining your collections and the available configuration.

collections_config_override - Boolean

Prevents CloudCannon from automatically discovering collections for supported SSGs if true. Defaults to false.

collection_groups - Array of objects

Controls which collections are displayed in the site navigation and how those collections are grouped. Defaults to splitting all available collections between Pages, Blogging and Data groups. Read more about configuring your navigation section.

data_config - Object or boolean

Controls what data sets are available to populate select and multiselect inputs.

If set as a boolean and true, all auto-discoverable data sets are added. This is only applicable to Jekyll and Hugo sites.

If set as an object, only those data sets are added.

editor - Object

Contains settings for the default editor actions on your site. The only available option is default_path, which sets what URL the editor opens from the dashboard.

paths - Object

Global paths to common folders. These are often automatically populated from your SSG, and not all paths are relevant to all SSGs. Each path is relative to source. The available keys are:

  • uploads for the default location of newly uploaded site files.
  • dam_uploads for the default location of newly uploaded DAM files.
  • static for the location of statically copied assets.
  • dam_static for the location of statically copied assets for DAM files.
  • collections for the parent folder of all collections.
  • data for the location of site data files.
  • layouts for the top-most folder of site layout files.
  • includes for the top-most folder of includes/partials/shortcode files.

uploads and dam_uploads have a number of dynamic placeholders available.

source - String

Base path to your site source files, relative to the root folder of your site.

source_editor - Object

Contains settings for the behavior and appearance of the Source Editor.

timezone - String

Timezone of your site in IANA format. Used by date and datetime inputs. Defaults to Etc/UTC.

output - String

Generates the integration file in another folder. Not available for Jekyll, Hugo and Eleventy. Defaults to the root folder of your site.

Configuration cascade options

Global configuration files are the base level for defining options in the configuration cascade, allowing you to define these options here at a global scope.

Was this article helpful? or Suggest an improvement >

Related articles