Configuration File Reference

Your CloudCannon configuration file allows you to customize your app experience by configuration CloudCannon's appearance and functionality.

This article covers all the keys available at the root level of your configuration file. To learn more about the configuration file, please read our documentation on the CloudCannon configuration file.

cloudcannon.config.yaml

copied

source: /
paths:
  uploads: /assets/uploads
collections_config:
  pages:
    path: content
    name: Pages
    icon: wysiwyg
  blog:
    path: content/blog
    name: Blog
    icon: post_add
    _enabled_editors:
      - content
      - data
  data:
    path: data
    name: Site Elements
    icon: important_devices
collection_groups:
  - heading: Content
    collections:
      - pages
      - blog
  - heading: Data Files
    collections:
      - data
_enabled_editors:
  - data
  - content
  - visual
_inputs:
  blog_tags:
    type: multiselect
    options:
      values: _select_data.blog_topics
_select_data:
  blog_topics:
    - Opinion
    - Feature
    - Resource
_structures:
  example:
    values:
      - value:
          name: 
          description: 
          image: 
_editables:
  content:
    bold: true
    italics: true
    underline: true
_snippets_imports:
  hugo:
    include:
      - hugo_youtube
      - hugo_vimeo
_snippets: 
base_url: documentation
data_config:
  authors:
    path: data/authors.csv
file_config:
  - glob: data/locations.csv
    _structures:
      location_entries:
        values:
          - label: Location
            value:
              name: 
              lat: 
              long: 
              image: 
editor:
  default_path: /en/
source_editor:
  tab_size: 2
  show_gutter: false
  theme: pastel_on_dark
timezone: Etc/UTC
commit_templates:
  - template_string: '{message}'
markdown:
  engine: commonmark

cloudcannon.config.json

copied

{
  "source": "/",
  "paths": {
    "uploads": "/assets/uploads"
  },
  "collections_config": {
    "pages": {
      "path": "content",
      "name": "Pages",
      "icon": "wysiwyg"
    },
    "blog": {
      "path": "content/blog",
      "name": "Blog",
      "icon": "post_add",
      "_enabled_editors": [
        "content",
        "data"
      ]
    },
    "data": {
      "path": "data",
      "name": "Site Elements",
      "icon": "important_devices"
    }
  },
  "collection_groups": [
    {
      "heading": "Content",
      "collections": [
        "pages",
        "blog"
      ]
    },
    {
      "heading": "Data Files",
      "collections": [
        "data"
      ]
    }
  ],
  "_enabled_editors": [
    "data",
    "content",
    "visual"
  ],
  "_inputs": {
    "blog_tags": {
      "type": "multiselect",
      "options": {
        "values": "_select_data.blog_topics"
      }
    }
  },
  "_select_data": {
    "blog_topics": [
      "Opinion",
      "Feature",
      "Resource"
    ]
  },
  "_structures": {
    "example": {
      "values": [
        {
          "value": {
            "name": null,
            "description": null,
            "image": null
          }
        }
      ]
    }
  },
  "_editables": {
    "content": {
      "bold": true,
      "italics": true,
      "underline": true
    }
  },
  "_snippets_imports": {
    "hugo": {
      "include": [
        "hugo_youtube",
        "hugo_vimeo"
      ]
    }
  },
  "_snippets": null,
  "base_url": "documentation",
  "data_config": {
    "authors": {
      "path": "data/authors.csv"
    }
  },
  "file_config": [
    {
      "glob": "data/locations.csv",
      "_structures": {
        "location_entries": {
          "values": [
            {
              "label": "Location",
              "value": {
                "name": null,
                "lat": null,
                "long": null,
                "image": null
              }
            }
          ]
        }
      }
    }
  ],
  "editor": {
    "default_path": "/en/"
  },
  "source_editor": {
    "tab_size": 2,
    "show_gutter": false,
    "theme": "pastel_on_dark"
  },
  "timezone": "Etc/UTC",
  "commit_templates": [
    {
      "template_string": "{message}"
    }
  ],
  "markdown": {
    "engine": "commonmark"
  }
}

Many of these configuration options have dedicated documentation. For more information, please read the documentation linked under each key description in the reference table.

Your CloudCannon configuration file has the following options available:

source — String#

This key defines the base path for your source files, relative to the root folder of your repository. Unless you use a nested folder as the source for your Site you can leave this key empty or set it to /.

By default, this key is empty.

For more information, please read our documentation on the Site source folder in your configuration file.

paths — Object#

This key enables you to define paths for your Rich Text editors or File inputs. The following nested keys are available:

dam_static
dam_uploads
dam_uploads_filename
static
uploads
uploads_filename
uploads_use_relative_paths

This key has no default. If undefined at higher levels of the configuration cascade, paths will default to any values configured in the CloudCannon configuration file.

For more information, please read our documentation on Rich Text editors or File inputs.

collections_config — Array of Objects#

This key defines your Collections.

The following nested keys are available for each Collection:

path
glob
name
singular_name
icon
url
disable_url
documentation
description
preview
sort
sort_options
_editables
_enabled_editors
_inputs
_select_data
_structures
add_options
create
disable_add
disable_add_folder
disable_file_actions
new_preview_url
schemas
schema_key
include_developer_files

By default, CloudCannon uses your source key to make assumptions about your Collections.

For more information, please read our documentation on Collections.

collection_groups — Array of Objects#

This key defines the groups and order of Collections in your Site Navigation. Each item in the array must contain the heading and collections keys.

The following nested keys are available for each entry in collection_groups:

heading
collections

This key has no default. If undefined, CloudCannon will sort your Collections in the following order: the Pages Collection, all output Collections in alphabetical order, then all non-output Collections in alphabetical order.

For more information, please read our documentation on configuring your Site Navigation.

_enabled_editors — Array#

This key defines which editing interfaces are available by default for files at a given level of the configuration cascade. Whether an editing interface is available for a specific file is determined by other factors.

Values can be one of the following: visual, content, or data. Specifying one or more editing interfaces will disable all unspecified editing interfaces. You cannot disable the Source Editor with this key.

By default, this key is set to visual, content, and data. If undefined at higher levels of the configuration cascade, _enabled_editables will default to any values configured in the CloudCannon configuration file.

Show exampleHide example

In this example, we have enabled only the Content Editor in the blog Collection.

cloudcannon.config.yaml

copied

collections_config:
  blog:
    _enabled_editors:
      - content

cloudcannon.config.json

copied

{
  "collections_config": {
    "blog": {
      "_enabled_editors": [
        "content"
      ]
    }
  }
}

For more information, please read our documentation on the Visual Editor, Content Editor, Data Editor, and Source Editor.

_inputs — Object#

This key defines which inputs are available at a given level of the configuration cascade.

The following nested keys are available for each input inside _inputs:

type
label
comment
context
hidden
instance_value
cascade
options

This key has no default. If undefined at higher levels of the configuration cascade, _inputs will default to any values configured in the CloudCannon configuration file.

For more information, please read our documentation on inputs.

_select_data — Object#

This key defines defines fixed data sets to populate Select and Multiselect inputs at a given level of the configuration cascade.

This key has no default. If undefined at higher levels of the configuration cascade, _select_data will default to any values configured in the CloudCannon configuration file.

Show exampleHide example

In this example, we have configured the blog_tags Multiselect input for the blog Collection.

cloudcannon.config.yaml

copied

collections_config:
  blog:
    _select_data:
      blog_topics:
        - Opinion
        - Feature
        - Resource

cloudcannon.config.json

copied

{
  "collections_config": {
    "blog": {
      "_select_data": {
        "blog_topics": [
          "Opinion",
          "Feature",
          "Resource"
        ]
      }
    }
  }
}

For more information, please read our documentation on Select and Multiselect inputs.

_structures — Object#

This key defines which structures are available for Object inputs and Array inputs at a given level of the configuration cascade.

The following nested keys are available for each structure inside _structures:

style
id_key
values
hide_extra_inputs
reorder_inputs
remove_empty_inputs
remove_extra_inputs

This key has no default. If undefined at higher levels of the configuration cascade, _structures will default to any values configured in the CloudCannon configuration file.

Show exampleHide example

In this example, we want to populate an Array input with Staff members, including the name, job_description, and profile_picture fields for all staff types, and the url field for Managers only.

cloudcannon.config.yaml

copied

_structures:
  staff:
    style: modal
    hide_extra_inputs: false
    values:
      - value:
          _type: Employee
          name: 
          job_description: 
          profile_picture: 
        preview:
          text:
            - key: name
            - Employee
          subtext:
            - key: job_description
            - Description of position
          image:
            - key: profile_picture
          icon: support_agent
      - value:
          _type: Manager
          name: 
          job_description: 
          profile_picture: 
          url: 
        preview:
          text:
            - key: name
            - Manager
          subtext:
            - key: job_description
            - Description of position
          image:
            - key: profile_picture
          icon: face

cloudcannon.config.json

copied

{
  "_structures": {
    "staff": {
      "style": "modal",
      "hide_extra_inputs": false,
      "values": [
        {
          "value": {
            "_type": "Employee",
            "name": null,
            "job_description": null,
            "profile_picture": null
          },
          "preview": {
            "text": [
              {
                "key": "name"
              },
              "Employee"
            ],
            "subtext": [
              {
                "key": "job_description"
              },
              "Description of position"
            ],
            "image": [
              {
                "key": "profile_picture"
              }
            ],
            "icon": "support_agent"
          }
        },
        {
          "value": {
            "_type": "Manager",
            "name": null,
            "job_description": null,
            "profile_picture": null,
            "url": null
          },
          "preview": {
            "text": [
              {
                "key": "name"
              },
              "Manager"
            ],
            "subtext": [
              {
                "key": "job_description"
              },
              "Description of position"
            ],
            "image": [
              {
                "key": "profile_picture"
              }
            ],
            "icon": "face"
          }
        }
      ]
    }
  }
}

In this example, we want to populate an Array input in the blog Collection with Related Articles, including the name, description, and url fields.

cloudcannon.config.yaml

copied

collections_config:
  blog:
    _structures:
      related_articles:
        values:
          - value:
              name: 
              description: 
              url:

cloudcannon.config.json

copied

{
  "collections_config": {
    "blog": {
      "_structures": {
        "related_articles": {
          "values": [
            {
              "value": {
                "name": null,
                "description": null,
                "url": null
              }
            }
          ]
        }
      }
    }
  }
}

For more information, please read our documentation on structures.

_editables — Object#

This key defines which Rich Text editors have custom configuration for the associated WYSIWYG toolbar.

The following nested keys are available:

content
block
link
text

This key has no default.

For more information, please read our documentation on Rich Text editors.

_snippets_imports — Object#

This key defines snippet templates or libraries for your Site. Some libraries are SSG specific while others work for most SSGs.

The following nested keys are available:

docusaurus_mdx
eleventy_liquid
eleventy_nunjucks
hugo
jekyll
mdx
python_markdown_extensions

This key has no default.

For more information, please read our documentation on Docusaurus Components, Eleventy Shortcodes, Hugo Shortcodes, MDX Components, or Python Markdown.

_snippets — Object#

This key defines custom snippets for your Site.

The following nested keys are available for each snippet inside _snippets:

template
inline
preview
definitions
_inputs

This key has no default.

base_url — String#

This key defines the base URL (or subpath) when generating output URLs for your Site. The base URL will prefix the output URL of each file.

This key has no default.

data_config — Object#

This key defines which file or folder data in your Site is available to populate Select and Multiselect inputs.

This key has no default.

For more information, please read our documentation on defining your data.

file_config — Array#

This key defines file-specific configuration without configuring a collection or modifying files.

The following nested keys are available for each entry in file_config:

glob (required)
_select_data
_structures
_select_data
_enabled_editors
_inputs
_editables

This key has no default.

editor.default_path — Object#

This key defines the link for the Home button on the Dashboard page.

By default, this key is set to / (i.e., your index output URL).

source_editor — Object#

This key defines the appearance and behavior of the Source Editor. The following nested keys are available:

tab_size
show_gutter
theme

This key has no default.

For more information, please read our documentation on the Source Editor.

timezone — String#

This key defines the timezone for your Site. Value must be in IANA timezone format.

By default, this key is Etc/UTC.

For more information, please read our documentation on Date and Time inputs.

commit_templates — Array of Objects#

This key defines your commit message templates. Commit messages appear on the Review changes modal when you save your changes.

This key has no default.

For more information, please read our documentation on commit templates.

markdown — Object#

This key defines your markdown engine for parsing Markdown content into HTML and any configuration options for your engine.

The following nested keys are available:

engine
options

This key has no default.

For more information, please read our documentation on configuring your markdown engine.