What is the CloudCannon Configuration File?

Last modified: October 7th, 2025

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.

The CloudCannon Configuration File is the heart of your CloudCannon experience, allowing you to customize the functionality and appearance of your Site. Adding formatted content to your Configuration File lets you configure your Site Navigation, Editing Interfaces, file appearance in the app, how CloudCannon adds new files, and more.

Your Configuration File allows you to make CloudCannon your own, customizing your app experience for you and your team members.

CloudCannon supports the following configuration file types:

cloudcannon.config.json
cloudcannon.config.yaml
cloudcannon.config.yml (recommended)

After syncing your Site files, creating your CloudCannon Configuration File should be the first thing you do. CloudCannon will prompt you to create a configuration file using the Getting Started task list on your Site Dashboard.

A screenshot of the Create your CloudCannon Configuration File task from the Getting Started task list shows the Create my Configuration File button.

By default, CloudCannon assumes your Configuration File is in the root folder of your Git repository, however you can define a custom Configuration File path if your file is within a nested folder.

You can edit your CloudCannon Configuration File using Configuration Mode or by finding the file in your File Browser and opening it in the Source Editor. For more information, please read out documentation on Configuration Mode in general or the Source Editor.

Here's an example of what your CloudCannon Configuration File might look like:

cloudcannon.config.yaml

copied

source: /
paths:
  uploads: public/uploads
  static: public
collections_config:
  pages:
    path: pages
    name: Pages
    icon: wysiwyg
    url: /[full_slug]/
  blog:
    path: blog
    name: Blog
    icon: post_add
    url: /blog/[full_slug]/
  services:
    path: services
    name: Services
    icon: volunteer_activism
  staff_members:
    path: staff-members
    name: Staff Members
    icon: groups
  data:
    path: data
    name: Site Elements
    icon: important_devices

cloudcannon.config.json

copied

{
  "source": "/",
  "paths": {
    "uploads": "public/uploads",
    "static": "public"
  },
  "collections_config": {
    "pages": {
      "path": "pages",
      "name": "Pages",
      "icon": "wysiwyg",
      "url": "/[full_slug]/"
    },
    "blog": {
      "path": "blog",
      "name": "Blog",
      "icon": "post_add",
      "url": "/blog/[full_slug]/"
    },
    "services": {
      "path": "services",
      "name": "Services",
      "icon": "volunteer_activism"
    },
    "staff_members": {
      "path": "staff-members",
      "name": "Staff Members",
      "icon": "groups"
    },
    "data": {
      "path": "data",
      "name": "Site Elements",
      "icon": "important_devices"
    }
  }
}

The configuration cascade#

The CloudCannon Configuration File is the first level in the Configuration Cascade, which means any configuration defined here will affect all the files on your Site. This makes it a great place to configure the default appearance and behavior you want. You can add more specific configuration at other levels of the cascade.

For more information, please read our documentation on the Configuration Cascade.

The source folder#

The first key you should define in your CloudCannon Configuration File is source. This key determines the Source Folder for your website's files relative to the root of your Git repository. Your Collections are configured relative to your Source Folder. This is useful if you have multiple websites nested in a single repository.