Collection configuration

The global configuration file#

The global configuration file is one of many places to set your website’s configuration. This file is the broadest in scope and the lowest priority - configurations setting specified here affect the entire site, but more specific settings from other sources can override these. This configuration cascade allows you to have fine control over your site configuration.

The configuration cascade sources are as follows, from lowest priority to highest:

• Global configuration
• Collection configuration
• Schema configuration
• Front matter
• Containing structure

The CloudCannon global configuration file can be one of several file types. When CloudCannon searches the root directory for your config file, it will use the first matching file from this list.

1. cloudcannon.config.json
2. cloudcannon.config.yaml
3. cloudcannon.config.yml
4. cloudcannon.config.js
5. cloudcannon.config.cjs

Let’s set up a cloudcannon.config.yml global configuration file in your source directory using the CloudCannon configuration GUI.

Once you have created your site, CloudCannon will automatically detect if you do not have a configuration file. In your sidebar, you will see the Get started button, which will prompt you to Generate your global configuration file.

The CloudCannon configuration GUI will direct you through creating a configuration file for your website.

Defining your collections#

We’ve talked about collections earlier in this guide — these are groups of related content. This could be pages, blog posts, data files, or any other file type.

Defining your collections is an important step in setting up your CloudCannon site. By defining your collections, you can navigate to them easily using the app sidebar and customize unique settings for each collection’s content (such as choosing a default editing interface).

The first section of the configuration GUI will help you define your collections. Each section of the GUI links to the CloudCannon documentation for that feature.

For each collection, you can:

• Specify the Path, URL, and Output for the Visual Editor.
• Customize icons, names, descriptions, and documentation links.
• Filter and Sort files.
• Choose how to group collections in the navigation sidebar.
• Enable or disable specific editors.

When you have created your CloudCannon global configuration file, your collections will look something like this:

collections_config:
  posts:
    path: content/blog
    output: true
    url: /blog/[slug]/
    _enabled_editors:
      - content
  pages:
    path: content/pages
    output: true
    url: /[slug]/
    _enabled_editors:
      - visual

{
  "collections_config": {
    "posts": {
      "path": "content/blog",
      "output": true,
      "url": "/blog/[slug]/",
      "_enabled_editors": [
        "content"
      ]
    },
    "pages": {
      "path": "content/pages",
      "output": true,
      "url": "/[slug]/",
      "_enabled_editors": [
        "visual"
      ]
    }
  }
}

module.exports = {
  collections_config: {
    posts: {
      path: "content/blog",
      output: true,
      url: "/blog/[slug]/",
      _enabled_editors: [
        "content"
      ]
    },
    pages: {
      path: "content/pages",
      output: true,
      url: "/[slug]/",
      _enabled_editors: [
        "visual"
      ]
    }
  }
};

While configuring your collections, you will see sections that refer to Inputs, Structures, and Schemas. We’ll discuss each of these in this section of the guide.

Inputs#

You can edit all your site data and front matter using Inputs in the Data Editor. Each input corresponds to a field in your front matter or data file, providing an editing interface for those values.

You can customize the _inputs for your site and for each collection in the global configuration file. These sections look like this in the configuration GUI:

Inputs come in various types linked to your keys and values (such as text, date picker, color picker, etc.). Defining your inputs means you can design the best editing experience for your team.

Each input should have a label, a comment, and a type.

• Label — The name of the input, as displayed in the Data Editor.
• Comment — A short description of what this input does.
• Type — What type of input (e.g., text, number, image, select).

You can further configure your input by adding the following options if required:

• Instance Value — Initialize a field with a unique UUID or today’s date.
• Options — Specify the settings for your inputs, where applicable.
• Hidden — Hide a field you don’t want your content team to change.
• Cascade — Specifies whether or not this input configuration should be merged with any matching, less specific configuration.

For more examples, visit our documentation on customizing your inputs.

If you already have input keys in your site, CloudCannon will automatically detect any inputs that match our naming conventions. For example, if your site has a front matter field ending with _image, like background_image, CloudCannon will assign that input to the file upload/selector type. While creating your global configuration file, reviewing all the inputs for each collection to ensure they were assigned the correct type is a good idea.

Read our documentation on input types for a complete list of our naming conventions.

When you have created your CloudCannon global configuration file, your inputs will look something like this:

_inputs:
  hero_image:
    type: image
    label: Hero Image
    comment: Appears at the top of the page
    options:
      width: 720
      height: 480
      resize_style: cover

{
  "_inputs": {
    "hero_image": {
      "type": "image",
      "label": "Hero Image",
      "comment": "Appears at the top of the page",
      "options": {
        "width": 720,
        "height": 480,
        "resize_style": "cover"
      }
    }
  }
}

module.exports = {
  _inputs: {
    hero_image: {
      type: "image",
      label: "Hero Image",
      comment: "Appears at the top of the page",
      options: {
        width: 720,
        height: 480,
        resize_style: "cover"
      }
    }
  }
};

We’ll talk about inputs some more in the next section of the guide when we cover front matter and data files.

Structures#

CloudCannon structures are an easy way to support a set of predefined objects. For example, you might have a structure that allows your content team to add photo galleries, testimonials, image and text blocks, or CTAs to a page.

You can customize the _structures for your site and for each collection in the global configuration file. These sections look like this in the configuration GUI:

Structures and arrays go hand-in-hand. Configuring your structures will allow you to create predefined objects which to add to your arrays.

Arrays are one of the most powerful parts of any static site generator. For example, you might use an array to create:

• Lists of related content, such as a list of staff members.
• Any repeated component or content block, such as testimonials or a gallery.

CloudCannon will automatically detect your arrays when you connect your site files and make them editable in the Data Editor. You can add new items to your arrays without the need for configuration, which will clone the previous array item and clear the data. However, this behavior can be limiting if you do not have at least one entry in your array or want to have different data types in the array. You can overcome these limitations with structures by configuring how new array items are added.

Structures are perfect for creating your own page builder.

You can configure your site structures to empower your content team, providing them with page components and letting them add, remove, reorder, and update these components to build pages.

You can choose a dropdown select menu or a modal pop-up window option to add structures to a page.

Currently, you cannot configure the values for your Structures in the Configuration GUI, however, it is easy to do manually. Navigate to your CloudCannon global configuration file through the Files tab in your navigation sidebar. The configuration file will be in the root of your directory.

For more examples, visit our documentation on defining your structures.

When you have created your CloudCannon global configuration file, your structures will look something like this:

_structures:
  example:
    values:
      - label: First
        value:
          name: 
          description: 
          image: 
      - label: Second
        value:
          heading: 
          subtext: 

{
  "_structures": {
    "example": {
      "values": [
        {
          "label": "First",
          "value": {
            "name": null,
            "description": null,
            "image": null
          }
        },
        {
          "label": "Second",
          "value": {
            "heading": null,
            "subtext": null
          }
        }
      ]
    }
  }
}

module.exports = {
  _structures: {
    example: {
      values: [
        {
          label: "First",
          value: {
            name: null,
            description: null,
            image: null
          }
        },
        {
          label: "Second",
          value: {
            heading: null,
            subtext: null
          }
        }
      ]
    }
  }
};

Schemas#

Use schemas to keep your files consistent. Configuring your schemas for each collection will help you to:

• Populate the front matter of a new file created in the CloudCannon app.
• Update the front matter for existing files in your collection.
• Customize the types of content you can add to a collection through the + Add button in the top right.

You can define the schemas for each collection in the global configuration file. These sections look like this in the configuration GUI:

Schema files are the same file type as the file you want to create. For example, you must use a Markdown schema to create a new Markdown file in your collection. You can have multiple schemas for each collection, each with a different file type and contents.

In your schema, you define the inputs for the front matter of all files using this schema.

Here is a simple example of a Markdown schema:

---
title:
author:
image:
---

Once you have created your schemas, you can configure each collection to reference a particular schema in the configuration GUI. New files in that collection will automatically have the correct front matter. When you edit an existing file in a collection with a defined schema, the front matter will update to keep data consistent.

CloudCannon will automatically display the schemas available for your collection as a drop-down menu from the + Add button.

You can further customize your + Add button through add_options; however, this isn’t necessary to get started on CloudCannon.

When you have created your CloudCannon global configuration file, your schemas will look something like this:

collections_config:
  posts:
    schemas:
      default:
        path: schemas/posts/default.md
      news:
        path: schemas/posts/news.md
        name: Newsletter Entry

{
  "collections_config": {
    "posts": {
      "schemas": {
        "default": {
          "path": "schemas/posts/default.md"
        },
        "news": {
          "path": "schemas/posts/news.md",
          "name": "Newsletter Entry"
        }
      }
    }
  }
}

module.exports = {
  collections_config: {
    posts: {
      schemas: {
        default: {
          path: "schemas/posts/default.md"
        },
        news: {
          path: "schemas/posts/news.md",
          name: "Newsletter Entry"
        }
      }
    }
  }
};

Finish the Configuration GUI#

Once you have finished making edits to your CloudCannon configuration file, you can save your changes using the Save button in the top right corner of the configuration GUI.

CloudCannon will push your cloudcannon.config.yml file back to your repository, and your site will rebuild automatically!