Create a global configuration file

Last modified: October 3rd, 2024

As of October 2024, this documentation is only applicable to Sites using Unified Configuration. For Sites that have not migrated to Unified Configuration, please read the documentation on our non-unified documentation website.

What is a configuration file?#

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

Configuration is set in one of the following supported file types. CloudCannon will search the root directory for the first matching file from this list.

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

This file is stored in the root directory of your repository (i.e. /cloudcannon.config.*). Alternatively, you can specify a custom location in the Editing section of your site settings.

Creating a configuration file#

The global configuration file is the heart of your integration with CloudCannon. You can create your configuration file locally or using the CloudCannon configuration GUI. When creating a new site, CloudCannon will guide you through creating a configuration file.

Here's an example file:

cloudcannon.config.yml
copied
# Use the given folder as the root for the site
# Collections will be relative to this path
source: src

# Determines the collections shown in the CMS sidebar
collections_config:
  people:
    path: 'content/people'
    name: Personnel
    _enabled_editors: ['data']
  posts:
    path: 'content/blog'
    # Configure inputs per collection
    _inputs:
      title:
        comment: Used for Blog SEO
  pages:
    path: 'content'
    glob:
      - "*.html"
    _enabled_editors: ['visual', 'data']

# Configure inputs across your site
_inputs:
  title:
    type: text
    comment: The title of your page

# Specify custom data for select and multiselect inputs
_select_data:
  colors:
    - Red
    - Green
    - Blue

# Generate data for select and multiselect inputs from data files
data_config:
  authors:
    path: data/authors.csv

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.

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.

file_config - Object#

Provides scope to configure settings at a file level, without configuring a collection, or modifying files.

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.

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.

markdown - Object#

Contains settings for various Markdown engines. See the Configure your Markdown engine documentation.

commit_templates - Array of objects#

Templates for commit messages when saving changes. See the Configure your commit templates documentation.

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.

Related Articles

Open in a new tab