Configuration File

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

This reference covers all keys available in your CloudCannon configuration file. To learn more about the configuration file, please read our documentation on the CloudCannon configuration file.

The configuration file can be named cloudcannon.config.yml, cloudcannon.config.yaml, cloudcannon.config.json, cloudcannon.config.cjs, or cloudcannon.config.js and should be placed in the root directory of your repository.

For IDE autocomplete and validation, see our JSON Schemas and TypeScript Types.

This key represents the main CloudCannon configuration schema.

Type#

Object

Properties

base_url — string#

This key defines which base URL (or subpath) CloudCannon should use when matching output URLs for your Site.

The base URL will prefix the output URL of each file.

Show examplesHide examples

In this example, we have configured the base URL to /documentation/ so all output URLs will be prefixed with this path.

Copied to clipboard

base_url: /documentation/

{
  "base_url": "/documentation/"
}

collection_groups — Array<collection_groups[*]>#

This key defines custom order and grouping for Collections in your Site Navigation.

The value is an array of group objects. Each group object must contain a heading key and a collections key.

If undefined, CloudCannon will sort your Collections in the order they are defined under the collections_config key.

Show examplesHide examples

In this example, we have configured Collection groups to organize Collections into "Content" and "Data Files" sections in the Site Navigation.

Copied to clipboard

collection_groups:
  - heading: Content
    collections:
      - pages
      - blog
  - heading: Data Files
    collections:
      - data

{
  "collection_groups": [
    {
      "heading": "Content",
      "collections": [
        "pages",
        "blog"
      ]
    },
    {
      "heading": "Data Files",
      "collections": [
        "data"
      ]
    }
  ]
}

collections_config — Object<collections_config.*>#

This key defines your Collections.

Show examplesHide examples

In this example, we have configured a blog Collection. Key settings include two Schemas to populate files with different content, a Blog Tags input populated by a fixed data set, and a custom Create Path to generate file names from structured data.

Copied to clipboard

collections_config:
  blog:
    path: content/blog
    glob:
      - '!_index.md'
    name: Blog
    icon: post_add
    url: /blog/[full_slug]/
    documentation:
      url: https://example.com/travel-blog-style-guide
      text: Documentation
      icon: auto_stories
    description: |-
      This Collection is for *Travel blogs* and *Customer stories*.

      If your have any questions, please contact Heather.
    _editables: 
    _enabled_editors:
      - content
    _inputs:
      blog_tags:
        type: multiselect
        label: Blog type
        comment: Select a blog type
        context:
          open: false
          title: Help
          icon: help
          content: |
            Blog tags help our users filter articles by topic.
        options:
          values: _select_data.blog_topics
    _select_data:
      blog_topics:
        - Opinion
        - Feature
        - Resource
    create:
      extra_data:
        filename: '{date|year}-{date|month}-{date|day}-{title}'
      path: '[relative_base_path]/{filename|slugify}.[ext]'
    disable_add: false
    disable_add_folder: false
    disable_file_actions: false
    schemas:
      blog:
        path: schemas/travel_blog.md
        name: Blog Post
        icon: post_add
      customer_story:
        path: schemas/customer_story.md
        name: Customer Story
        icon: post_add
    schema_key: _blog_template
    include_developer_files: false

{
  "collections_config": {
    "blog": {
      "path": "content/blog",
      "glob": [
        "!_index.md"
      ],
      "name": "Blog",
      "icon": "post_add",
      "url": "/blog/[full_slug]/",
      "documentation": {
        "url": "https://example.com/travel-blog-style-guide",
        "text": "Documentation",
        "icon": "auto_stories"
      },
      "description": "This Collection is for *Travel blogs* and *Customer stories*.\n\nIf your have any questions, please contact Heather.",
      "_editables": null,
      "_enabled_editors": [
        "content"
      ],
      "_inputs": {
        "blog_tags": {
          "type": "multiselect",
          "label": "Blog type",
          "comment": "Select a blog type",
          "context": {
            "open": false,
            "title": "Help",
            "icon": "help",
            "content": "Blog tags help our users filter articles by topic.\n"
          },
          "options": {
            "values": "_select_data.blog_topics"
          }
        }
      },
      "_select_data": {
        "blog_topics": [
          "Opinion",
          "Feature",
          "Resource"
        ]
      },
      "create": {
        "extra_data": {
          "filename": "{date|year}-{date|month}-{date|day}-{title}"
        },
        "path": "[relative_base_path]/{filename|slugify}.[ext]"
      },
      "disable_add": false,
      "disable_add_folder": false,
      "disable_file_actions": false,
      "schemas": {
        "blog": {
          "path": "schemas/travel_blog.md",
          "name": "Blog Post",
          "icon": "post_add"
        },
        "customer_story": {
          "path": "schemas/customer_story.md",
          "name": "Customer Story",
          "icon": "post_add"
        }
      },
      "schema_key": "_blog_template",
      "include_developer_files": false
    }
  }
}

In this example, we have configured a team Collection. Key settings include custom sorting options, add options, and Card previews.

Copied to clipboard

collections_config:
  team:
    path: _data/team
    name: Our Team
    singular_name: Team Member
    icon: groups
    disable_url: true
    description: This Collection has a file for every member of our team!
    preview:
      text:
        - key: name
      subtext:
        - key: job_title
      icon:
        - key: profile_picture
    sort:
      key: name
      order: ascending
    sort_options:
      - key: name
        order: ascending
        label: Name (A-Z)
      - key: name
        order: descending
        label: Name (Z-A)
      - key: job_title
        order: ascending
        label: Job Title (A-Z)
      - key: date
        order: descending
        label: Job Title (Z-A)
    _enabled_editors:
      - data
    add_options:
      - name: Office Locations
        icon: map
        href: /our-offices
    schemas:
      manager:
        path: schemas/manager.yml
        name: Manager
        icon: face
      employee:
        path: schemas/employee.yml
        name: Employee
        icon: support_agent

{
  "collections_config": {
    "team": {
      "path": "_data/team",
      "name": "Our Team",
      "singular_name": "Team Member",
      "icon": "groups",
      "disable_url": true,
      "description": "This Collection has a file for every member of our team!",
      "preview": {
        "text": [
          {
            "key": "name"
          }
        ],
        "subtext": [
          {
            "key": "job_title"
          }
        ],
        "icon": [
          {
            "key": "profile_picture"
          }
        ]
      },
      "sort": {
        "key": "name",
        "order": "ascending"
      },
      "sort_options": [
        {
          "key": "name",
          "order": "ascending",
          "label": "Name (A-Z)"
        },
        {
          "key": "name",
          "order": "descending",
          "label": "Name (Z-A)"
        },
        {
          "key": "job_title",
          "order": "ascending",
          "label": "Job Title (A-Z)"
        },
        {
          "key": "date",
          "order": "descending",
          "label": "Job Title (Z-A)"
        }
      ],
      "_enabled_editors": [
        "data"
      ],
      "add_options": [
        {
          "name": "Office Locations",
          "icon": "map",
          "href": "/our-offices"
        }
      ],
      "schemas": {
        "manager": {
          "path": "schemas/manager.yml",
          "name": "Manager",
          "icon": "face"
        },
        "employee": {
          "path": "schemas/employee.yml",
          "name": "Employee",
          "icon": "support_agent"
        }
      }
    }
  }
}

collections_config_from_glob — Array<collections_config_from_glob[*]>#

This key defines globs that filter which files CloudCannon should use for Collection configuration.

Values in this array are relative to the root of your repository (i.e., /, not the value of source⁠) and must end in the file extension .cloudcannon.collections.yml.

Show examplesHide examples

In this example, each Collection has its own Configuration File in the .cloudcannon/collections/ folder. The value of the collections_config_from_glob key tells CloudCannon to use all files in that folder that match the glob *.cloudcannon.collections.yml.

Copied to clipboard

collections_config_from_glob:
  - /.cloudcannon/collections/*.cloudcannon.collections.yml

{
  "collections_config_from_glob": [
    "/.cloudcannon/collections/*.cloudcannon.collections.yml"
  ]
}

Copied to clipboard

posts:
  path: content/posts
  icon: event

{
  "posts": {
    "path": "content/posts",
    "icon": "event"
  }
}

commit_templates — Array<commit_templates[*]>#

This key defines commit message templates available when saving changes.

The value is an array of template objects. Each template object can contain optional label, template_path, template_string, wrap_width, extra_data, and _inputs keys.

Commit messages appear on the Review changes modal when you save your changes.

Show examplesHide examples

In this example, we have configured a commit template with a template string and input configuration.

Copied to clipboard

commit_templates:
  - label: Default
    template_string: '{commit_type}: {message|trim}'
    _inputs:
      commit_type:
        type: select
        options:
          allow_empty: true
          values:
            - feature
            - fix
            - test
        cascade: true

{
  "commit_templates": [
    {
      "label": "Default",
      "template_string": "{commit_type}: {message|trim}",
      "_inputs": {
        "commit_type": {
          "type": "select",
          "options": {
            "allow_empty": true,
            "values": [
              "feature",
              "fix",
              "test"
            ]
          },
          "cascade": true
        }
      }
    }
  ]
}

In this example, we have configured a commit template that uses a file for the template content.

Copied to clipboard

commit_templates:
  - label: Commit message from file
    template_path: /.git/commit-message.txt

{
  "commit_templates": [
    {
      "label": "Commit message from file",
      "template_path": "/.git/commit-message.txt"
    }
  ]
}

In this example, we have configured a commit template with a template string, input configuration, and extra data for nested templates.

Copied to clipboard

commit_templates:
  - label: Breaking change
    template_string: '{message}{breaking_change|if=breaking_change_message}'
    _inputs:
      breaking_change_message:
        type: text
    extra_data:
      breaking_change: ⚠️ {breaking_change_message}

{
  "commit_templates": [
    {
      "label": "Breaking change",
      "template_string": "{message}{breaking_change|if=breaking_change_message}",
      "_inputs": {
        "breaking_change_message": {
          "type": "text"
        }
      },
      "extra_data": {
        "breaking_change": "⚠️ {breaking_change_message}"
      }
    }
  ]
}

data_config — Object<data_config.*>#

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

Show examplesHide examples

In this example, we have configured data config to make data files available for Select Inputs and Multiselect Inputs.

Copied to clipboard

data_config:
  authors:
    path: data/authors.csv
  offices:
    path: data/offices

{
  "data_config": {
    "authors": {
      "path": "data/authors.csv"
    },
    "offices": {
      "path": "data/offices"
    }
  }
}

Configure all data files or folders under the data_config key in your CloudCannon configuration file.

Select Inputs and Multiselect Inputs which use the authors key are populated by the contents of the authors.csv file.

Select Inputs and Multiselect Inputs which use the offices key are populated by the contents of each file in the offices folder.

_editables — Object#

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

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

Appears in: schemas.*, collections_config.*, file_config[*].

Show examplesHide examples

In this example, we have configured the Snippet tool for WYSIWYG toolbars in the blog Collection.

Copied to clipboard

collections_config:
  blog:
    _editables:
      content:
        snippet: true

{
  "collections_config": {
    "blog": {
      "_editables": {
        "content": {
          "snippet": true
        }
      }
    }
  }
}

_editables_from_glob — Array<_editables_from_glob[*]>#

This key defines globs that filter which files CloudCannon should use for configuring Rich Text formatting.

Values in this array are relative to the root of your repository (i.e., /, not the value of source⁠) and must end in the file extension .cloudcannon.editables.yml.

You can use this key anywhere you would use the _editables key in the configuration cascade.

This key has no default.

Appears in: schemas.*, collections_config.*, file_config[*].

Show examplesHide examples

In this example, we have several WYSIWYG Toolbar Configuration Files in the .cloudcannon/editables/ folder, with each file containing multiple definitions. The value of the _editables_from_glob key tells CloudCannon all files in that folder that match the glob *.cloudcannon.editables.yml.

Copied to clipboard

_editables_from_glob:
  - /.cloudcannon/editables/*.cloudcannon.editables.yml

{
  "_editables_from_glob": [
    "/.cloudcannon/editables/*.cloudcannon.editables.yml"
  ]
}

Copied to clipboard

text:
  bold: true
  italic: true
  underline: true
block:
  format: p h3
  undo: true
  redo: true
link:
  bold: true
  italic: true
  underline: true

{
  "text": {
    "bold": true,
    "italic": true,
    "underline": true
  },
  "block": {
    "format": "p h3",
    "undo": true,
    "redo": true
  },
  "link": {
    "bold": true,
    "italic": true,
    "underline": true
  }
}

editor — Object#

This key defines settings for the default editor actions on your site.

_enabled_editors — Array<_enabled_editors[*]>#

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.

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

Appears in: schemas.*, collections_config.*, file_config[*].

Show examplesHide examples

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

Copied to clipboard

collections_config:
  blog:
    _enabled_editors:
      - content

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

file_config — Array<file_config[*]>#

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

This key has no default.

_inputs — Object<_inputs.*>#

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

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.

Appears in: create, [*], schemas.*, collections_config.*, file_config[*], pull_request_templates[*], commit_templates[*], Snippet.

Show examplesHide examples

In this example, we have configured the date_created key as a Date and Time Input, which will automatically populate when you create a file using this input. Editors cannot alter this input as the interface is disabled.

Copied to clipboard

_inputs:
  date_created:
    type: datetime
    label: Date of article creation
    comment: UTC +0 timezone
    context:
      open: false
      title: Help
      icon: help
      content: This date field will automatically populate when you create an article.
    hidden: false
    disabled: true
    instance_value: NOW
    cascade: true
    options:
      timezone: Etc/UTC

{
  "_inputs": {
    "date_created": {
      "type": "datetime",
      "label": "Date of article creation",
      "comment": "UTC +0 timezone",
      "context": {
        "open": false,
        "title": "Help",
        "icon": "help",
        "content": "This date field will automatically populate when you create an article."
      },
      "hidden": false,
      "disabled": true,
      "instance_value": "NOW",
      "cascade": true,
      "options": {
        "timezone": "Etc/UTC"
      }
    }
  }
}

In this example, we have configured the blog_tags key as a Multiselect Input in the blog Collection.

Copied to clipboard

collections_config:
  blog:
    _inputs:
      blog_tags:
        type: multiselect
        label: Blog type
        comment: Select a blog type
        context:
          open: false
          title: Help
          icon: help
          content: |
            Blog tags help our users filter articles by topic.
        options:
          values:
            - Opinion
            - Feature
            - Resource

{
  "collections_config": {
    "blog": {
      "_inputs": {
        "blog_tags": {
          "type": "multiselect",
          "label": "Blog type",
          "comment": "Select a blog type",
          "context": {
            "open": false,
            "title": "Help",
            "icon": "help",
            "content": "Blog tags help our users filter articles by topic.\n"
          },
          "options": {
            "values": [
              "Opinion",
              "Feature",
              "Resource"
            ]
          }
        }
      }
    }
  }
}

_inputs_from_glob — Array<_inputs_from_glob[*]>#

This key defines globs that filter which files CloudCannon should use for Input configuration.

Values in this array are relative to the root of your repository (i.e., /, not the value of source⁠) and must end in the file extension .cloudcannon.inputs.yml.

You can use this key anywhere you would use the _inputs key in the configuration cascade.

This key has no default.

Appears in: [*], create, schemas.*, collections_config.*, file_config[*], Snippet.

Show examplesHide examples

In this example, we have several Input Configuration Files in the .cloudcannon/inputs/ folder, with each file containing multiple Input definitions. The value of the _inputs_from_glob key tells CloudCannon to only use the seo.cloudcannon.inputs.yml and blog-details.cloudcannon.inputs.yml files in that folder.

Copied to clipboard

collections_config:
  posts:
    path: content/posts
    icon: event
    inputs_from_glob:
      - /.cloudcannon/inputs/seo.cloudcannon.inputs.yml
      - /.cloudcannon/inputs/blogDetails.cloudcannon.inputs.yml

{
  "collections_config": {
    "posts": {
      "path": "content/posts",
      "icon": "event",
      "inputs_from_glob": [
        "/.cloudcannon/inputs/seo.cloudcannon.inputs.yml",
        "/.cloudcannon/inputs/blogDetails.cloudcannon.inputs.yml"
      ]
    }
  }
}

Copied to clipboard

seo_title:
  type: text
  options:
    required: true
    max_length: 50
seo_description:
  type: textarea
  options:
    show_count: true
    required: true
    max_length: 125
seo_image:
  type: image
  options:
    path:
      uploads: images
    accepts_mime_types:
      - image/png
      - image/jpeg
    required: true
    pattern: (?i)\.(jpe?g|png)$
    pattern_message: Please select a JPG or PNG image file

{
  "seo_title": {
    "type": "text",
    "options": {
      "required": true,
      "max_length": 50
    }
  },
  "seo_description": {
    "type": "textarea",
    "options": {
      "show_count": true,
      "required": true,
      "max_length": 125
    }
  },
  "seo_image": {
    "type": "image",
    "options": {
      "path": {
        "uploads": "images"
      },
      "accepts_mime_types": [
        "image/png",
        "image/jpeg"
      ],
      "required": true,
      "pattern": "(?i)\\.(jpe?g|png)$",
      "pattern_message": "Please select a JPG or PNG image file"
    }
  }
}

markdown — Object#

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

Show examplesHide examples

In this example, we have configured CloudCannon to use the commonmark Markdown engine with various options including attributes and attribute elements.

Copied to clipboard

markdown:
  engine: commonmark
  options:
    attributes: true
    attributes_elements:
      inline: none
      block: space right
      ul: below
      ol: below
      blockquote: below
      p: below
      img: below
      hr: below
      table: below
      li: none

{
  "markdown": {
    "engine": "commonmark",
    "options": {
      "attributes": true,
      "attributes_elements": {
        "inline": "none",
        "block": "space right",
        "ul": "below",
        "ol": "below",
        "blockquote": "below",
        "p": "below",
        "img": "below",
        "hr": "below",
        "table": "below",
        "li": "none"
      }
    }
  }
}

paths — Object#

This key defines paths for your Rich Text editors or File inputs.

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

Appears in: Rich Text Input options, URL Input options, File Input options, _editables.content, _editables.block, _editables.link, _editables.image, _editables.text.

Show examplesHide examples

In this example, we have configured paths for the blog Collection to set custom upload and static paths.

Copied to clipboard

collections_config:
  blog:
    paths:
      uploads: /uploads/blog/
      static: /assets/

{
  "collections_config": {
    "blog": {
      "paths": {
        "uploads": "/uploads/blog/",
        "static": "/assets/"
      }
    }
  }
}

pull_request_templates — Array<pull_request_templates[*]>#

This key defines the Pull Request templates available on your Site.

The value is an array of template objects. Each template object can contain optional label, title, body, template_path, and _inputs keys.

This key has no default.

Show examplesHide examples

In this example, we have two Pull Request templates in the pull_request_templates array.

Copied to clipboard

pull_request_templates:
  - label: General changes
    _inputs:
      title:
        options:
          required: true
      body:
        type: markdown
        options:
          bold: true
          italic: true
          link: true
          format: p h1 h2 h3
  - label: Delete content
    title: Delete content
    _inputs:
      title:
        options:
          disabled: true
    template_path: .github/templates/delete-content.md

{
  "pull_request_templates": [
    {
      "label": "General changes",
      "_inputs": {
        "title": {
          "options": {
            "required": true
          }
        },
        "body": {
          "type": "markdown",
          "options": {
            "bold": true,
            "italic": true,
            "link": true,
            "format": "p h1 h2 h3"
          }
        }
      }
    },
    {
      "label": "Delete content",
      "title": "Delete content",
      "_inputs": {
        "title": {
          "options": {
            "disabled": true
          }
        }
      },
      "template_path": ".github/templates/delete-content.md"
    }
  ]
}

_select_data — Object<_select_data.*>#

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.

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

Appears in: [*], create, schemas.*, collections_config.*, file_config[*], Snippet.

Show examplesHide examples

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

Copied to clipboard

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

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

_snippets — Object<Snippet>#

This key defines custom snippets for your Site.

This key has no default.

_snippets_definitions — Object<Snippet Definition Value>#

A record of reusable values that can be referenced in snippet templates. Values are substituted using { ref: "key" } for direct replacement or { spread_ref: "key" } for spreading arrays/objects. Common definition types include parser formats, argument models, select option lists, and simple string values like shortcode names.

Show examplesHide examples

Define reusable values like shortcode names, argument models, and parser formats that can be referenced in snippet templates.

Copied to clipboard

_snippets_definitions:
  shortcode_name: highlight
  content_key: content
  positional_args:
    - editor_key: language
      type: string
    - editor_key: linenos
      type: boolean
      optional: true
      default: false
  custom_format:
    root_pair_delimiter:
      - ' '
    root_value_delimiter: '='
    string_boundary:
      - '"'
      - ''''
      - ''
    allow_booleans: true
    allow_numbers: true

{
  "_snippets_definitions": {
    "shortcode_name": "highlight",
    "content_key": "content",
    "positional_args": [
      {
        "editor_key": "language",
        "type": "string"
      },
      {
        "editor_key": "linenos",
        "type": "boolean",
        "optional": true,
        "default": false
      }
    ],
    "custom_format": {
      "root_pair_delimiter": [
        " "
      ],
      "root_value_delimiter": "=",
      "string_boundary": [
        "\"",
        "'",
        ""
      ],
      "allow_booleans": true,
      "allow_numbers": true
    }
  }
}

Reference definitions in snippet templates using { ref: "key" } syntax. This allows you to reuse common configurations across multiple snippets.

Copied to clipboard

_snippets_definitions:
  shortcode_name: figure
  named_args:
    - editor_key: src
      type: string
    - editor_key: alt
      type: string
      optional: true
_snippets_templates:
  my_shortcode_template:
    snippet: '{{< [[name]] [[args]] >}}'
    params:
      name:
        parser: literal
        options:
          literal:
            ref: shortcode_name
      args:
        parser: key_values
        options:
          models:
            ref: named_args
_snippets:
  figure:
    template: my_shortcode_template
    definitions:
      shortcode_name: figure
      named_args:
        - editor_key: src
          type: string
        - editor_key: alt
          type: string

{
  "_snippets_definitions": {
    "shortcode_name": "figure",
    "named_args": [
      {
        "editor_key": "src",
        "type": "string"
      },
      {
        "editor_key": "alt",
        "type": "string",
        "optional": true
      }
    ]
  },
  "_snippets_templates": {
    "my_shortcode_template": {
      "snippet": "{{< [[name]] [[args]] >}}",
      "params": {
        "name": {
          "parser": "literal",
          "options": {
            "literal": {
              "ref": "shortcode_name"
            }
          }
        },
        "args": {
          "parser": "key_values",
          "options": {
            "models": {
              "ref": "named_args"
            }
          }
        }
      }
    }
  },
  "_snippets": {
    "figure": {
      "template": "my_shortcode_template",
      "definitions": {
        "shortcode_name": "figure",
        "named_args": [
          {
            "editor_key": "src",
            "type": "string"
          },
          {
            "editor_key": "alt",
            "type": "string"
          }
        ]
      }
    }
  }
}

Define a list of select options for use in snippet inputs, such as a list of programming languages for a code highlighting snippet.

Copied to clipboard

_snippets_definitions:
  languages:
    - name: JavaScript
      value: js
    - name: Python
      value: python
    - name: Ruby
      value: ruby
    - name: HTML
      value: html
    - name: CSS
      value: css

{
  "_snippets_definitions": {
    "languages": [
      {
        "name": "JavaScript",
        "value": "js"
      },
      {
        "name": "Python",
        "value": "python"
      },
      {
        "name": "Ruby",
        "value": "ruby"
      },
      {
        "name": "HTML",
        "value": "html"
      },
      {
        "name": "CSS",
        "value": "css"
      }
    ]
  }
}

_snippets_definitions_from_glob — Array<_snippets_definitions_from_glob[*]>#

_snippets_from_glob — Array<_snippets_from_glob[*]>#

This key defines globs that filter which files CloudCannon should use for Snippet configuration.

Values in this array are relative to the root of your repository (i.e., /, not the value of source⁠) and must end in the file extension .cloudcannon.snippets.yml.

You can use this key anywhere you would use the _snippets key in the configuration cascade.

This key has no default.

Show examplesHide examples

In this example, each Custom Snippet has its own Configuration File in the .cloudcannon/snippets/ folder. The value of the _snippets_from_glob key tells CloudCannon to use the callout.cloudcannon.snippets.yml file in that folder.

Copied to clipboard

_snippets_imports:
  eleventy_liquid: true
_snippets_from_glob:
  - /.cloudcannon/snippets/callout.cloudcannon.snippets.yml

{
  "_snippets_imports": {
    "eleventy_liquid": true
  },
  "_snippets_from_glob": [
    "/.cloudcannon/snippets/callout.cloudcannon.snippets.yml"
  ]
}

Copied to clipboard

callout:
  template: eleventy_liquid_include
  inline: false
  preview:
    text: Callout
  definitions:
    include_name: callout
    named_args:
      - source_key: type
        editor_key: label
        type: string
      - editor_key: message
        type: string
  _inputs:
    label:
      type: select
      options:
        values:
          - info
          - warning
          - error

{
  "callout": {
    "template": "eleventy_liquid_include",
    "inline": false,
    "preview": {
      "text": "Callout"
    },
    "definitions": {
      "include_name": "callout",
      "named_args": [
        {
          "source_key": "type",
          "editor_key": "label",
          "type": "string"
        },
        {
          "editor_key": "message",
          "type": "string"
        }
      ]
    },
    "_inputs": {
      "label": {
        "type": "select",
        "options": {
          "values": [
            "info",
            "warning",
            "error"
          ]
        }
      }
    }
  }
}

_snippets_imports — Object#

This key defines snippet templates or libraries for your Site.

Some libraries are SSG specific while others work for most SSGs.

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

Show examplesHide examples

In this example, we have configured Hugo shortcode imports for the Site.

Copied to clipboard

_snippets_imports:
  hugo:
    include:
      - figure
      - youtube

{
  "_snippets_imports": {
    "hugo": {
      "include": [
        "figure",
        "youtube"
      ]
    }
  }
}

_snippets_imports_from_glob — Array<_snippets_imports_from_glob[*]>#

This key defines globs that filter which files CloudCannon should use for Snippet imports configuration.

Values in this array are relative to the root of your repository (i.e., /, not the value of source⁠) and must end in the file extension .cloudcannon.snippets-imports.yml.

You can use this key anywhere you would use the _snippets_imports key in the configuration cascade.

This key has no default.

Show examplesHide examples

In this example, we have several Snippet Configuration Files in the .cloudcannon/snippets/ folder. The value of the _snippets_import_from_glob key tells CloudCannon all files in that folder that match the glob *.cloudcannon.snippets-import.yml.

Copied to clipboard

_snippets_imports_from_glob:
  - /.cloudcannon/snippets/*.cloudcannon.snippets-imports.yml

{
  "_snippets_imports_from_glob": [
    "/.cloudcannon/snippets/*.cloudcannon.snippets-imports.yml"
  ]
}

Copied to clipboard

mdx: true
docusaurus_mdx:
  exclude:
    - docusaurus_mdx_truncate

{
  "mdx": true,
  "docusaurus_mdx": {
    "exclude": [
      "docusaurus_mdx_truncate"
    ]
  }
}

_snippets_templates — Object<Snippet>#

This key defines extended options used when creating more complex custom snippets.

_snippets_templates_from_glob — Array<_snippets_templates_from_glob[*]>#

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 /.

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

Show examplesHide examples

In this example, we have configured the source path to src so CloudCannon will look for source files in the src folder.

Copied to clipboard

source: src

{
  "source": "src"
}

source_editor — Object#

This key defines the appearance and behavior of the Source Editor.

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

Show examplesHide examples

In this example, we have configured the Source Editor with custom theme, tab size, and gutter settings.

Copied to clipboard

source_editor:
  theme: basic_dark
  tab_size: 2
  show_gutter: true

{
  "source_editor": {
    "theme": "basic_dark",
    "tab_size": 2,
    "show_gutter": true
  }
}

_structures — Object<Structure>#

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

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.

For more information, please read our documentation on structures.

Appears in: [*], create, schemas.*, collections_config.*, file_config[*], Snippet.

Show examplesHide examples

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

Copied to clipboard

collections_config:
  blog:
    _structures:
      related_articles:
        style: select
        values:
          - preview:
              text:
                - key: name
              subtext:
                - key: url
            value:
              name: 
              description: 
              url:

{
  "collections_config": {
    "blog": {
      "_structures": {
        "related_articles": {
          "style": "select",
          "values": [
            {
              "preview": {
                "text": [
                  {
                    "key": "name"
                  }
                ],
                "subtext": [
                  {
                    "key": "url"
                  }
                ]
              },
              "value": {
                "name": null,
                "description": null,
                "url": null
              }
            }
          ]
        }
      }
    }
  }
}

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.

Copied to clipboard

_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

{
  "_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"
          }
        }
      ]
    }
  }
}

_structures_from_glob — Array<_structures_from_glob[*]>#

This key defines globs that filter which files CloudCannon should use for Structure configuration.

Values in this array are relative to the root of your repository (i.e., /, not the value of source⁠) and must end in the file extension .cloudcannon.structures.yml.

You can use this key anywhere you would use the _structures key in the configuration cascade.

Please see our documentation on values_from_glob for defining individual Structure values in a split Configuration File.

This key has no default.

Appears in: [*], create, schemas.*, collections_config.*, file_config[*], Snippet.

Show examplesHide examples

In this example, we have several Structure Configuration Files in the .cloudcannon/structures/ folder. The value of the _structures_from_glob key tells CloudCannon to use the staffMembers.cloudcannon.structures.yml file in that folder.

Copied to clipboard

_structures_from_glob:
  - /.cloudcannon/structures/staffMembers.cloudcannon.structures.yml

{
  "_structures_from_glob": [
    "/.cloudcannon/structures/staffMembers.cloudcannon.structures.yml"
  ]
}

Copied to clipboard

staff:
  style: modal
  values:
    - label: Employee
      value:
        name: 
        job_description: 
        profile_picture: 
    - label: Manager
      value:
        name: 
        job_description: 
        profile_picture: 
        url:

{
  "staff": {
    "style": "modal",
    "values": [
      {
        "label": "Employee",
        "value": {
          "name": null,
          "job_description": null,
          "profile_picture": null
        }
      },
      {
        "label": "Manager",
        "value": {
          "name": null,
          "job_description": null,
          "profile_picture": null,
          "url": null
        }
      }
    ]
  }
}

timezone — string#

This key defines the timezone for your Site.

Value must be in IANA timezone format.

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

Allowed values: Africa/Abidjan Africa/Accra Africa/Addis_Ababa Africa/Algiers Africa/Asmara Africa/Asmera Africa/Bamako Africa/Bangui Africa/Banjul Africa/Bissau and 585 more.

Appears in: Date/Datetime Input options.

upstream_commit_template — string#

This key defines the commit template to use when pulling changes from the upstream repository.

An upstream commit message template can contain plain text and placeholders. Placeholders insert data related to the commit and use [ ] brackets. CloudCannon supports the following commit placeholders:

[branch] — the name of the current branch.
[publish_branch] — the name of the Publish Branch from which you merge upstream changes.
[author] — the email address of the person responsible for the upstream merge.
[date] — the date of the upstream merge in the format "Tue Nov 28 2023 21:46:17 GMT+0000".

Show examplesHide examples

In this example, we have configured a commit template with placeholders for upstream pulls.

Copied to clipboard

upstream_commit_template: Merge branch [publish_branch] into develop of [branch] by [author] at [date]

{
  "upstream_commit_template": "Merge branch [publish_branch] into develop of [branch] by [author] at [date]"
}

User Articles

User Guides

User Glossary

Developer Articles

Developer Guides

Developer Reference

Recent searches

Configuration File

On this page

Type#

Properties