Create a global configuration file

Working with a specific static site generator?
Customize CloudCannon's documentation to suit your SSG.

Great! We'll show you documentation relevant to .
You can change this any time using the dropdown in the navigation bar.

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

cloudcannon.config.json
cloudcannon.config.yaml
cloudcannon.config.yml
cloudcannon.config.js
cloudcannon.config.cjs

cloudcannon.config.json
cloudcannon.config.yaml
cloudcannon.config.yml
cloudcannon.config.js
cloudcannon.config.cjs

cloudcannon.config.json
cloudcannon.config.yaml
cloudcannon.config.yml
cloudcannon.config.js
cloudcannon.config.cjs

This file is stored in the root directory of your repository (i.e. /cloudcannon.config.*). Alternatively, use a specific config file in a custom location using the CLOUDCANNON_CONFIG_PATH environment variable:

CLOUDCANNON_CONFIG_PATH=src/cloudcannon.config.yaml

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.

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.

CloudCannon will prompt you to create a configuration file

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

Here's an example file:

cloudcannon.config.yaml

copied

_inputs:
  title:
    type: text
    comment: The title of your page.
_select_data:
  colors:
    - Red
    - Green
    - Blue
source: src
base_url: /documentation
collections_config:
  people:
    path: content/people
    output: true
    name: Personnel
    _enabled_editors:
      - data
  posts:
    path: _posts
    output: true
  pages:
    name: Main pages
data_config:
  authors: true
  offices: true
paths:
  uploads: assets/uploads
  collections: items
  data: _data
  layouts: _layouts
  includes: _partials

cloudcannon.config.json

copied

{
  "_inputs": {
    "title": {
      "type": "text",
      "comment": "The title of your page."
    }
  },
  "_select_data": {
    "colors": [
      "Red",
      "Green",
      "Blue"
    ]
  },
  "source": "src",
  "base_url": "/documentation",
  "collections_config": {
    "people": {
      "path": "content/people",
      "output": true,
      "name": "Personnel",
      "_enabled_editors": [
        "data"
      ]
    },
    "posts": {
      "path": "_posts",
      "output": true
    },
    "pages": {
      "name": "Main pages"
    }
  },
  "data_config": {
    "authors": true,
    "offices": true
  },
  "paths": {
    "uploads": "assets/uploads",
    "collections": "items",
    "data": "_data",
    "layouts": "_layouts",
    "includes": "_partials"
  }
}

cloudcannon.config.cjs

copied

module.exports = {
  _inputs: {
    title: {
      type: "text",
      comment: "The title of your page."
    }
  },
  _select_data: {
    colors: [
      "Red",
      "Green",
      "Blue"
    ]
  },
  source: "src",
  base_url: "/documentation",
  collections_config: {
    people: {
      path: "content/people",
      output: true,
      name: "Personnel",
      _enabled_editors: [
        "data"
      ]
    },
    posts: {
      path: "_posts",
      output: true
    },
    pages: {
      name: "Main pages"
    }
  },
  data_config: {
    authors: true,
    offices: true
  },
  paths: {
    uploads: "assets/uploads",
    collections: "items",
    data: "_data",
    layouts: "_layouts",
    includes: "_partials"
  }
};

The following is automatically read from Jekyll if not set in the global configuration file:

collections_config from collections in _config.yml
paths.collections from collections_dir in _config.yml
paths.layouts from layouts_dir in _config.yml
paths.data from data_dir in _config.yml
paths.includes from includes_dir in _config.yml
base_url from baseurl in _config.yml
source from the --source CLI option or source in _config.yml

cloudcannon.config.yaml

copied

_inputs:
  title:
    type: text
    comment: The title of your page.
_select_data:
  colors:
    - Red
    - Green
    - Blue
source: src
base_url: /documentation
collections_config:
  people:
    path: content/people
    output: true
    name: Personnel
    _enabled_editors:
      - data
  posts:
    path: _posts
    output: true
  pages:
    name: Main pages
data_config:
  authors: true
  offices: true
paths:
  uploads: assets/uploads
  data: _data
  layouts: _layouts

cloudcannon.config.json

copied

{
  "_inputs": {
    "title": {
      "type": "text",
      "comment": "The title of your page."
    }
  },
  "_select_data": {
    "colors": [
      "Red",
      "Green",
      "Blue"
    ]
  },
  "source": "src",
  "base_url": "/documentation",
  "collections_config": {
    "people": {
      "path": "content/people",
      "output": true,
      "name": "Personnel",
      "_enabled_editors": [
        "data"
      ]
    },
    "posts": {
      "path": "_posts",
      "output": true
    },
    "pages": {
      "name": "Main pages"
    }
  },
  "data_config": {
    "authors": true,
    "offices": true
  },
  "paths": {
    "uploads": "assets/uploads",
    "data": "_data",
    "layouts": "_layouts"
  }
}

cloudcannon.config.cjs

copied

module.exports = {
  _inputs: {
    title: {
      type: "text",
      comment: "The title of your page."
    }
  },
  _select_data: {
    colors: [
      "Red",
      "Green",
      "Blue"
    ]
  },
  source: "src",
  base_url: "/documentation",
  collections_config: {
    people: {
      path: "content/people",
      output: true,
      name: "Personnel",
      _enabled_editors: [
        "data"
      ]
    },
    posts: {
      path: "_posts",
      output: true
    },
    pages: {
      name: "Main pages"
    }
  },
  data_config: {
    authors: true,
    offices: true
  },
  paths: {
    uploads: "assets/uploads",
    data: "_data",
    layouts: "_layouts"
  }
};

The following is automatically read from Hugo if not set in the global configuration file:

collections_config from your folder structure inside contentDir in Hugo config
paths.layouts from layoutsDir in Hugo config
paths.data from dataDir in Hugo config
paths.static from staticDir in Hugo config
base_url from the --baseURL CLI option or baseURL in Hugo config
source from source in Hugo config

cloudcannon.config.js

copied

module.exports = {
  // Global CloudCannon configuration
  _inputs: {
    title: {
      type: 'text',
      comment: 'The title of your page.'
    }
  },
  _select_data: {
    colors: ['Red', 'Green', 'Blue']
  },

  // Base path to your site source files, same as input for Eleventy
  source: 'src',

  // The subpath your built output files are mounted at
  base_url: '/documentation',

  // Populates collections for navigation and metadata in the editor
  collections_config: {
    people: {
      // Base path for files in this collection, relative to source
      path: 'content/people',

      // Whether this collection produces output files or not
      output: true,

      // Collection-level configuration
      name: 'Personnel',
      _enabled_editors: ['data']
    },
    posts: {
      path: '_posts',
      output: true
    },
    pages: {
      name: 'Main pages'
    }
  },

  // Generates the data for select and multiselect inputs matching these names
  data_config: {
    // Populates data with authors from an data file with the matching name
    authors: true,
    offices: true
  },

  paths: {
    // The default location for newly uploaded files, relative to source
    uploads: 'assets/uploads',

    // The path to site data files, relative to source
    data: 'data', // defaults to _data

    // The path to site layout files, relative to source
    layouts: '_layouts', // defaults to _includes

    // The path to site include files, relative to source
    includes: '_partials' // defaults to _includes
  }
};

The following is automatically read from Eleventy if not set in the global configuration file:

paths from dir in .eleventy.js options
base_url from pathPrefix in .eleventy.js options
source from the --input CLI option or dir.input in .eleventy.js options

These options match Eleventy's configuration format and are set as follows:

Automatically installed is the recommended default with Manage eleventy-plugin-cloudcannon manually disabled in your build configuration.

.eleventy.js

copied

  module.exports = function (eleventyConfig) {
    return {
      pathPrefix: '/',
      dir: {
        input: '.',
        data: '_settings',
        layouts: '_layouts',
        includes: '_partials'
      }
    };
  };

Applicable if you have Manage eleventy-plugin-cloudcannon manually enabled in your build configuration.

.eleventy.js

copied

const pluginCloudCannon = require('eleventy-plugin-cloudcannon');

module.exports = function (eleventyConfig) {
  const config = {
    pathPrefix: '/',
    dir: {
      input: '.',
      data: '_settings',
      layouts: '_layouts',
      includes: '_partials'
    }
  };

  eleventyConfig.addPlugin(pluginCloudCannon, config);
  return config;
};

cloudcannon.config.js

copied

module.exports = {
  // Global CloudCannon configuration
  _inputs: {
    title: {
      type: 'text',
      comment: 'The title of your page.'
    }
  },
  _select_data: {
    colors: ['Red', 'Green', 'Blue']
  },

  // Read from ./src instead of .
  source: 'src',

  // Write to ./output/_cloudcannon/info.json instead of ./_cloudcannon/info.json
  output: 'output',

  // Populates the sidebar navigation and provides metadata for the editor
  collections_config: {
    people: {
      // Reads the contents of each file in this directory
      path: 'content/people',

      // The URL template for items in this collection
      url: '/people/{department|slugify}/[slug]/',

      // Tells CloudCannon this collection produces output files
      output: true

      // CloudCannon collection-level configuration
      name: 'Personnel',
      _enabled_editors: ['data']
    },
    posts: {
      // Reads the contents of each file in this directory
      path: '_posts',

      // How to parse the files in this collection
      parser: 'front-matter',

      // The URL function for items in this collection
      url: (filePath, parsed, { filters }) => {
        const year = new Date(parsed.date).getFullYear();
        const slug = filters.slugify(parsed.title || '');
        return `/posts/${year}/${slug}/`;
      },

      // Tells CloudCannon this collection produces output files
      output: true
    },
    pages: {
      // Tells CloudCannon to navigate to this path for this collection
      path: '',

      // Reads the contents of each file for this pattern (takes priority over path)
      glob: ['**/*.md', './src/pages/*.html'],

      // Tells CloudCannon to only show successfully parsed files for this collection
      // Useful for excluding other collections when using '' as path
      filter: 'strict',

      // Tells CloudCannon this collection produces output files
      output: true
    },
    data: {
      // Reads the contents of each file in this directory
      path: 'data',

      // How to parse the files in this collection
      parser: (filePath, raw, { parsers, filters }) => {
        const parsed = parsers['front-matter'].parse(raw);
        const slug = filters.slugify(parsed.title || '');
        return { ...data, slug };
      }
    }
  },

  // Generates the data for select and multiselect inputs matching these names
  data_config: {
    authors: {
      // Reads the contents of this file
      path: 'data/authors.csv'
    },
    offices: {
      // Reads the contents of each file in this directory
      path: 'data/offices',
      parser: 'json'
    }
  }
};

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.

collections_config_override - Boolean#

Prevents CloudCannon from automatically discovering collections for supported SSGs if true. Defaults to false.

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.

If set as a boolean and true, all auto-discoverable data sets are added. This is only applicable to Jekyll and Hugo sites.

If set as an object, only those data sets are added.

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.
collections for the parent folder of all collections.
data for the location of site data files.
layouts for the top-most folder of site layout files.
includes for the top-most folder of includes/partials/shortcode 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.

output - String#

Generates the integration file in another folder. Not available for Jekyll, Hugo and Eleventy. Defaults to the root folder of your site.

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.

Create a global configuration file

What is a configuration file?#

Creating a configuration file#

Options#

Configuration cascade options#

Related Articles