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:

CLOUDCANNON_CONFIG_PATH=src/cloudcannon.config.yaml

Here’s an example file:

Jekyll content

cloudcannon.config.yml
# Global CloudCannon configuration
_inputs:
  title:
    type: text
    comment: The title of your page.
_select_data:
  colors:
    - 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
collections_config:
  people:
    # 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
    _enabled_editors:
      - data
  posts:
    path: _posts
    output: true
  pages:
    name: Main pages

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

paths:
  # 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
  • paths.data 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

Options

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 files
  • static for the location of statically copied assets
  • 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 has dynamic placeholders available. Placeholders can result in empty values and sequential slashes are collapsed into one after applying placeholders. The available placeholders are:

  • :categories and :title from the front matter or data of the containing file
  • :year, :month, and :day from the date front matter or data of the containing file
  • :collection resolves to the collection key the containing file belongs to
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