Migrating to global configuration files

Last modified: October 17th, 2024

How you set global configuration in CloudCannon has changed. We recommend updating, but the previous configuration will continue to work. CloudCannon now uses specific files rather than relying on your SSG configuration files. This allows us to provide a consistent experience across SSGs as we add more. This also separates the configuration itself, making your sites more maintainable.

To migrate, create your CloudCannon configuration file with these instructions, then move your configuration here.

Many of the configuration keys are the same. You can fin these keys in the CloudCannon configuration file reference documentation. Globally-scoped configuration cascade values must also be moved to your CloudCannon configuration file.

Here are the notable changes for your specific SSG:

For Jekyll sites

CloudCannon used to read global configuration from your _config.yml file.

Base collection configuration is still automatically read from Jekyll itself. Collection settings are now set under collections_config in your global configuration file rather than in collections or cloudcannon.collections inside _config.yml. The contents are the same, except for these renamed keys. Read more about configuring your collections.

Including data files is now set in data_config in your global configuration file rather than in cloudcannon.data in _config.yml. The format is the same.

Your global uploads path is now set in paths.uploads in your global configuration file rather than in uploads_dir in _config.yml. The format is the same.

For Hugo sites

CloudCannon used to read global configuration from your config.toml file.

Base collection configuration is still automatically read from Hugo top-level content sections. Collection configuration is now set under collections_config in your global configuration file rather than in cloudcannon.collections inside config.toml. The contents are the same, except for these renamed keys. Read more about configuring your collections.

Including data files is now set in data_config in your global configuration file rather than in cloudcannon.data in config.toml. The format is the same.

Your global uploads path is now set in paths.uploads in your global configuration file rather than in uploads_dir in config.toml. The format is the same.

For Eleventy sites

CloudCannon used to read global configuration from your _data/cloudcannon.* file.

Base collection configuration is still automatically read from Eleventy itself. Collection configuration is now set under collections_config in your global configuration file rather than in collections inside _data/cloudcannon.*. The contents are the same, except for these renamed keys. Read more about configuring your collections.

By overwhelming demand, defining collection configuration no longer overrides automatically-discovered collections. If you want to restore this behavior, use the collections_config_override global setting.

Including data files is now set in data_config in your global configuration file rather than in data in _data/cloudcannon.*. The format is the same.

Your global uploads path is now set in paths.uploads in your global configuration file rather than in uploads_dir in _data/cloudcannon.*. The format is the same.

For all other sites

CloudCannon already reads global configuration from your cloudcannon.config.* file for other SSGs. There are a couple of extra renamed keys here:

  • collections-config to collections_config
  • data-config to data_config
  • base-url to base_url

Renamed keys#

Since collection-level configuration is now always defined separately, there's no longer any risk of clashing with SSG-specific configuration. We've taken this chance to clean up and rename the configuration keys that started with underscores in an effort to reduce that risk:

  • _collection_groups to collection_groups
  • _source_editor to source_editor
  • _subtext_key to subtext_key inside collections_config
  • _image_key to image_key inside collections_config
  • _image_size to image_size inside collections_config
  • _singular_name to singular_name inside collections_config
  • _singular_key to singular_key inside collections_config
  • _disable_add to disable_add inside collections_config
  • _icon to icon inside collections_config
  • _add_options to add_options inside collections_config
  • _sort_key to sort_key inside collections_config

sort_key has been superseded by sort and sort_options has been introduced.

The remaining underscore-prefixed configuration keys are not renamed so they can be identified as part of the configuration cascade.

Open in a new tab