# CloudCannon Documentation (Full)

> Complete documentation content. See llms.txt for a structured index.


---

---
title: About User Articles
description: Learn about CloudCannon's User Documentation articles, which will aid you in using the app to manage your content, billing, and teams.
url: https://cloudcannon.com/documentation/user-articles/
content_type: user article
last_modified: 2026-02-13
---

Welcome to CloudCannon's User Documentation. These articles cover everything you need to know about using CloudCannon.

A User is anyone who uses CloudCannon to update their website content, review content changes made by others, organize their team members, or manage their CloudCannon subscription. A Developer can also be a User, but Developers also customize CloudCannon for use by their team members or clients (see our [Developer Articles](/documentation/developer-articles/)).

As a User, you'll be working in the CloudCannon web app ([https://app.cloudcannon.com/](https://app.cloudcannon.com/)) rather than a development environment. CloudCannon's **User Interface** provides you with all the tools you need. The articles in this section of our documentation are designed to explain CloudCannon concepts and provide instructions for achieving your content management goals.

If you need further assistance with your website on CloudCannon, contact your developer or our friendly [support team](/support/).

## CloudCannon UI

Articles in the [CloudCannon UI](/documentation/user-articles/introduction-to-cloudcannon-ui/) section provide a tour of the CloudCannon app. Learn your way around CloudCannon, including what different elements in the app are called and where you can find specific tools. These articles are a great place to start for new Users, or to return to when you see an element of UI referenced in another article and you need a refresher.

## Editing

Articles in the [Editing](/documentation/user-articles/introduction-to-editing/) section teach you everything you need to know about adding, editing, and deleting the content on your website. Learn about **Sites** in CloudCannon and how to find your **files** in the **Collection Browser**. Learn how to open your **files** in one of CloudCannon's *Editing Interfaces*, update your content, and **save** the changes to your website. These articles cover the majority of the CloudCannon experience for managing your content.

## Syncing & Publishing

Articles in the [Syncing & Publishing](/documentation/user-articles/introduction-to-syncing-and-publishing/) section will teach you the basics of **Git** (the technology CloudCannon uses to store your files securely and enable version control). Learn how CloudCannon syncs your files from your storage provider and how to publish your changes from a test copy of your website to the live version your visitors see. These articles are helpful for everyone, and they are also relevant to websites where a developer has set up a branching workflow for publishing changes.

## Sharing

Articles in the [Sharing](/documentation/user-articles/introduction-to-sharing/) section cover how you can collaborate with others on CloudCannon. Learn how to join or leave an **Organization**, invite and remove team members from an *Organization* you control, and manage the permissions that you and your team members have over your content, billing, and more. These articles are useful for Users who manage teams of content creators and need to ensure that everyone has the correct level of access to your website.

## Hosting

Articles in the [Hosting](/documentation/user-articles/introduction-to-hosting/) section cover the features available when you host your website on the Internet using CloudCannon. Learn what web hosting is, and how it can enable you to see a preview of your content on a **Testing Domain**, and collect visitor form submissions in a **Site Inbox**. These articles are relevant to websites where a developer has opted in to hosting through CloudCannon.

## Accounts

Articles in the [Accounts](/documentation/user-articles/introduction-to-accounts/) section teach you everything you need to know about your account on CloudCannon, including how to create or delete one, manage your billing and subscription details, ensure a secure login, and determine who has ownership over your content. These articles are useful for everyone, but also for any Users who need financial oversight and ownership over *Organizations* on CloudCannon.


---

---
title: Accessing and configuring your invoices
description: Learn how to access and configure your invoices in CloudCannon.
url: https://cloudcannon.com/documentation/user-articles/accessing-and-configuring-your-invoices/
content_type: user article
last_modified: 2026-03-29
---

CloudCannon keeps a record of your billing history in the form of invoices. You can add your billing details to invoices and set your invoices to email automatically.

#### Accessing your invoices

You can access a complete list of all your invoices for your **Organization** by heading to *Organization Settings > Invoices*. From here, you can access a PDF file for each invoice by clicking **Download**.

![A screenshot of a list of invoices, downloadable as PDFs in CloudCannon.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Invoices-List.webp)

### Configuring your invoices

#### Billing details on invoices

Add your billing details, such as your physical address, to your invoices by updating your  *Billing Contacts*. These will display on the top of your invoices. We won't mail copies to your physical address.

#### Automatically emailing invoices

By default, invoices won't automatically send to any email address. You can configure this by adding an email to your *Billing Contacts* in your *Subscription*  settings. Once set, you will see confirmation of the email address and the next expected invoice date in your *Billing* section.

#### How to update your Billing Contacts

1. Head to *Organization Settings > Subscription*.
2. Under the *Billing* section, click **Update Contacts**.
3. Add your preferred email address in the top field.
4. Add your billing details in the bottom field.
5. Click **Update Billing Contacts** to save.

![Screenshot of adding your Billing email and address to your CloudCannon invoices.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Billing-Contacts.webp)


---

---
title: Add a file
description: Learn how to add files in CloudCannon without opening your Git repository.
url: https://cloudcannon.com/documentation/user-articles/add-a-file/
content_type: user article
last_modified: 2026-03-29
---

There are multiple ways to add files in CloudCannon. When you add a file to your site and [save your changes](/documentation/user-articles/save-your-changes/), CloudCannon will push the new file to your Git repository. This way, technical and non-technical team members can contribute to your Git repository.

## Create a new file in the collection browser

You can create a new collection file using the *+ Add* button in the top right of the collection browser. The [+ Add dropdown](/documentation/developer-articles/configure-the-add-button-in-collections/) shows a list of available [Schemas](/documentation/developer-articles/what-is-a-schema/) for this collection or a default file template if no Schemas are configured.

- **Schema** - A Schema is a preconfigured file template that will populate new files with matching front matter and contents. You can configure your *+ Add* dropdown to list a library of Schemas for each collection.
- **Default file template** — If no Schemas are defined for a collection, CloudCannon will generate a default file template. The default template will copy the front matter (but not the contents) of the first alphabetical file in the collection. In the *+ Add* dropdown, the default template will appear as “+ Add [collection item]”, for example, “+ Add Blog” for a collection named “Blog”.

![A closeup of the Collection Browser shows the option to add a file in the Add dropdown.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-Controls-Add-Menu-Dropdown.webp)

To create a file in the collection browser:

1. Navigate to the location you want to create the file using the collection or File Browser.
2. Click the *+ Add* button in the top right of the browser.
3. Select the Schema or template you want to use.

CloudCannon will open a new file in an editing interface and save it to the location open in your collection browser.

## Upload from the File Browser

Your File Browser uses the same file structure as your Git repository. You can upload an individual file or a folder of files using the *+ Add* button in the top right of the files browser. Uploading a folder uploads all files inside it rather than the folder itself.

> The File Browser is not available to team members in the [Editor Default Permission Group](/documentation/user-articles/what-are-default-permission-groups/#editors) or [Clients](/documentation/user-articles/what-is-client-sharing/).

![A closeup of the File Browser shows the options to Upload files and Upload a folder in the Add dropdown.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-File-Browser-Controls-Add-Menu-Dropdown.webp)

To upload a file or folder from the File Browser:

1. Navigate to the location where you want to upload the file in your File Browser.
2. Click the *+ Add* button in the top right of the browser and select *Upload files* or *Upload a folder*.
3. CloudCannon will open a local File Browser. Select the file or folder you want to upload.
4. Review the files you want to upload in the *Confirm your files* modal.
5. Click the *Confirm selection* button.

CloudCannon will upload your file or folder to the location open in your File Browser.

> When uploading files to CloudCannon, the maximum size per file is 50 MB. Files synced from a Git provider have no maximum size.

Alternatively, you can also drag and drop files from your local computer into the CloudCannon File Browser to upload them to the location you have open.

## Duplicate a file

You can add a new file to your site by cloning an existing file. This method is useful if you need files with similar contents. You can also duplicate a folder to create a copy of every file in that folder.

> If your workflow requires many files with similar contents, we recommend setting up a [Schema](/documentation/developer-articles/what-is-a-schema/).

![A closeup of the Collection Browser shows the file Context Menu with options including Duplicate item.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-File-Context-Menu.webp)

To Duplicate a file or folder:

1. Navigate to the item you want to Duplicate in your collection or File Browser.
2. Open the *Context Menu* by clicking the icon in the top right of the file card.
3. Select *Duplicate item/folder*.

CloudCannon will Duplicate your file or folder. Duplicated files and folders will have “-copy” added to the file or folder name. Filenames inside Duplicated folders will not change.

If you are cloning an individual file, CloudCannon will open that file in an editing interface.

Alternatively, you can duplicate a file from the editing interface using the *File menu* in the top left corner.

## Upload from an editing interface

While in the [Visual Editor](/documentation/user-articles/what-is-the-visual-editor/), [Content Editor](/documentation/user-articles/what-is-the-content-editor/), or [Data Editor](/documentation/user-articles/what-is-the-data-editor/), you can upload files through a file input. Uploading from a file input is a convenient way to add files without leaving the editing interface. We recommend this method for uploading images or other file types that you want to include within another file.

File inputs in the sidebar of the Visual or Content Editor, or in the Data Editor, allow you to select a file from your local computer or browse existing files stored in your repository or a remote DAM.

> Although you can upload videos this way, we recommend using external storage to prevent large files from affecting the size of your Git repository.

### Upload to the root directory from a file input

![A closeup of the file input shows the options to upload or explore existing files in the input dropdown.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Image-Input-Dropdown-Open.webp)

To upload a file to your root directory:

1. Navigate to the file you want to add another file to in your collection or File Browser.
2. Open that file in the Visual, Content, or Data Editor.
3. Click on the input where you want to upload your file in the sidebar or Data Editor and select *Upload a new file*.
4. If you have a DAM connected to your site, the *Choose your file destination* modal will prompt you to select either your DAM or *Site files*. Click *Confirm destination*. If you do not have a DAM, CloudCannon will upload your file to your *Site files*.
5. CloudCannon will open a local File Browser. Select the file you want to upload.

CloudCannon will upload your file to the root directory and add the file to the input you selected.

### Upload to a folder from a file input

Uploading a file to the root directory may not be ideal for some sites. You can choose where in your file structure to upload your file by using the *Explore existing files* option.

![The file browser shows existing files with the Add button dropdown open, providing options to upload new files.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-File-Input-File-Browser-Add-Dropdown.webp)

To upload a file to a folder in your file structure:

1. Navigate to the file you want to add another file to in your collection or File Browser.
2. Open that file in the Visual, Content, or Data Editor.
3. Click on the input where you want to upload your file in the sidebar or Data Editor and select *Explore existing files*.
4. CloudCannon will open a File Browser modal. If you have a DAM connected to your site, you can choose which location to browse using the *Select your source* dropdown.
5. Navigate to the location where you want to upload the file (you can create new folders using the *+ Add* button in the top right of the modal).
6. Click the *+ Add* button and select *Upload files*.
7. CloudCannon will open a local File Browser. Select the file you want to upload.
8. Review the files you want to upload in the *Confirm your files* modal.
9. Click the *Confirm selection* button.

CloudCannon will upload your file. To add that file to the input in your editing interface, select the file and click the *Select file* button.


---

---
title: Add a team member to a Permission Group
description: Learn how to add a team member to a Permission Group.
url: https://cloudcannon.com/documentation/user-articles/add-a-team-member-to-a-permission-group/
content_type: user article
last_modified: 2026-04-11
---

Adding a [team member](/documentation/user-articles/what-is-a-team-member/) to a [Permission Group](/documentation/user-articles/what-are-permission-groups/) will increase their permissions in your [Organization](/documentation/user-articles/what-is-an-organization/).

There are three ways to add a team member to a Permission Group. The best method to use will depend on whether you want to:

- Add multiple team members to multiple Permission Groups.
- Add a specific team member to multiple Permission Groups.
- Add multiple team members to a specific Permission Group.

> Only members of the [Owners Permission Group](/documentation/user-articles/what-are-default-permission-groups/#owners) can update the members of the Owners Group.

## Add multiple team members to multiple Permission Groups

To add team members to multiple Permission Groups:

1. Navigate to the *Team* page under *Org settings*.
2. Under the *Members* tab, click the *+ Add members* button on the right to open the *Invite team members to your Organization* modal.
3. Enter the name of the team member(s) whose permissions you want to update.
4. Enter the Permission Group(s) to which you want to add these team members. You must select at least one.
5. Click the *Add member(s)* button.

![A screenshot of the Team page shows the Invite Team members modal with two fields for names and Permission Groups.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Team-Invite-Members-Modal.webp)

> You can use the *Invite team members to your Organization* modal to update the permissions of existing team members at the same time as inviting new users.

## Add a specific team member to a Permission Group

To add a specific team member to one or more Permission Groups:

1. Navigate to the *Team* page under *Org settings*.
2. Under the *Members* tab, click on the member whose permissions you want to update. This will open their *Team member* page.
3. Click the *+ Add group* button on the right to open the *Add to Groups* modal.
4. Enter the Permission Group(s) to which you want to add this team member.
5. Click the *Add to group(s)* button.

![A screenshot of the Team Member page shows the Add to Team Member to Groups modal with a field for Permission Groups.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Team-Add-Member-To-Groups-Modal.webp)

## Add a team member to a specific Permission Group

To add one or more team members to a specific Permission Group:

1. Navigate to the *Team* page under *Org settings*.
2. Click on the *Groups* tab.
3. Under the *Groups* tab, click on the Permission Group to which you want to add members. This will open the *Permission Group* page.
4. Click the *+ Add group member* button on the right to open the *Add members* modal.
5. Enter the name of the team member(s) you want to add to this Permission Group. You can also enter the email addresses of new users you want to invite to your Organization.
6. Click the *Add member(s)* button.

![A screenshot of the Developers Permission Group page shows the Add Team Members to Group modal with a field for names.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Team-Add-Members-To-Group-Modal.webp)


---

---
title: Add a team member to your Organization
description: Learn how to add a team member to your Organization.
url: https://cloudcannon.com/documentation/user-articles/add-a-team-member-to-your-organization/
content_type: user article
last_modified: 2026-04-01
---

To add a [team member](/documentation/user-articles/what-is-a-team-member/) to your [Organization](/documentation/user-articles/what-is-an-organization/):

1. Navigate to the *Team* page under *Org settings*.
2. Under the *Members* tab, click the *+Add members* button on the right. This will open the *Invite team members to your Organization* modal.
3. Enter the email address of the person you want to add to your Organization.
4. Enter the Permission Group(s) to which you want to add this team member. You must select at least one.
5. Click the *Add member(s)* button.

![A screenshot of the Team page shows team members and the Add members button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Team-Members-Tab.webp)

![A screenshot of the Team page shows the Invite Team members modal with two fields for names and Permission Groups.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Team-Invite-Modal.webp)

CloudCannon will send an email to your pending team members, inviting them to your Organization. If someone does not have a CloudCannon account, this email will prompt them to create one. While you wait for them to accept the invitation, their name will appear in the list of *Pending members* under the *Members* tab of the *Team* page.

If you need to re-send or cancel an invitation to a pending member, select the *Re-send invitation* or *Cancel invitation* options from the *Context Menu* at the top right of the member card.

> You can paste a list of email addresses into the *Invite team members to your Organization* modal to quickly add multiple members to your Organization. When you enter multiple team members and multiple Permission Groups, CloudCannon will add all members to all Groups.


---

---
title: Create a CloudCannon Account
description: Learn how to create a CloudCannon account.
url: https://cloudcannon.com/documentation/user-articles/create-a-cloudcannon-account/
content_type: user article
last_modified: 2026-04-11
---

When you create an account on CloudCannon, you can manage your own websites, experiment with a website template, or join someone else's team to manage their content.

If this is your first time creating a CloudCannon account, we highly recommend reading the [Getting Started with CloudCannon](/documentation/developer-guides/getting-started-with-cloudcannon/) guide.

> Do not share your CloudCannon password with anyone. CloudCannon employees will never ask you for your password.

To create a CloudCannon account:

1. Open the [CloudCannon app](https://app.cloudcannon.com/register) using your Internet browser.
2. Click on the *Sign up with email* button.
3. Enter your email in the *Email address* field and click the *Send Code* button. CloudCannon will send a six-digit confirmation code to validate your email address. This validation email should arrive quickly and will expire after 10 minutes.
4. Enter the code in the *Confirmation Code* field and click *Continue*.
5. Enter your first name, last name, and an account password, and whether you are a developer or a content editor. Your password must be at least nine characters long.
6. Click *Create my account* button.

![A screenshot of the Register page shows the options to sign up with GitHub, Bitbucket, GitLab, or email.](assets/onboarding_screenshots/CloudCannon-Documentation-Create-Account-Login-Page.png)

![A screenshot of the Signup page shows fields for your first name, last name, password, and role.](assets/onboarding_screenshots/CloudCannon-Documentation-Create-Account-Details.png)


---

---
title: Customizing CloudCannon to match your brand
description: Learn how to customize CloudCannon to match your brand.
url: https://cloudcannon.com/documentation/user-articles/customizing-cloudcannon-to-match-your-brand/
content_type: user article
last_modified: 2026-03-29
---

Bring your brand to CloudCannon.

You can add your brand to CloudCannon in three major ways:

1. Set a Brand color
2. Organization Badge
3. Organization Sites List Logo

## Brand Color

Brand color defines the color of the sidebar and many other UI elements in CloudCannon.

To set your brand color:

1. Go to *Organization Settings* / *Details*
2. Use the color picker to set a color
3. Click **Update Organization** to confirm the configuration

## Add your brand assets

To add the assets defined above:

1. Go to *Organization Settings* / *Details*
2. Upload an image for both available assets
3. Click **Update Organization** to confirm the configuration

![Screenshot of organization branding interface](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Branding-Settings.webp)

## Organization Badge

This asset is used in the organization list. For best results, the image should be square with a minimum width of 256px.

![Screenshot of Organizations list](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Account-Organizations-Click-Through-List.webp)

## Organization Sites List Logo

This asset is used in the organizations site list. For best results, the image should be wider than it is tall and have a minimum width of 512px.

![Screenshot of Sites list with custom branding](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Branded-Sites-List.webp)


---

---
title: Delete a file
description: Learn how to delete files in CloudCannon without opening your Git repository.
url: https://cloudcannon.com/documentation/user-articles/delete-a-file/
content_type: user article
last_modified: 2026-03-29
---

Deleting files in CloudCannon does not occur immediately. Instead, the *Delete* file action will mark the file for deletion and add a *Deleted* [badge](/documentation/user-articles/edit-your-files/#file-badges) to the file card. CloudCannon will delete marked files the next time you [save your changes](/documentation/user-articles/save-your-changes/).

This workflow protects your site from unintentional file deletion by providing multiple opportunities to cancel the deletion.

To mark a file or folder for deletion:

1. Navigate to the item you want to delete in your collection or File Browser.
2. Open the *Context Menu* by clicking the icon in the top right of the file card.
3. Select *Delete item* or *Delete folder*.

CloudCannon will mark your item for deletion and add a *Deleted* badge to the file card.

![A closeup of the Collection Browser shows the file Context Menu with the Delete item option.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-File-Context-Menu.webp)

Alternatively, you can delete a file using the *File menu* in the top left corner of the editing interface.

You can still open files marked for deletion in an editing interface. These files are in read-only mode, and a red *Deleted file banner* will appear at the bottom of the editing interface.

![The Content Editor in the CloudCannon app shows a 'This file has been deleted' banner with the option to 'Restore file'.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Deleted-File-Banner.webp)

Once you save your changes, CloudCannon will sync to your Git repository and delete your files.

## Delete a file with unsaved changes

You cannot immediately delete a file with unsaved changes or folders that contain files with unsaved changes.

While there are unsaved changes, CloudCannon will disable the *Delete item* option in the *Context Menu* and the editing interface *File menu*. To protect your work, CloudCannon requires you to explicitly discard your unsaved changes before you can mark a file for deletion.

![A closeup of the Collection Browser shows the Context Menu for an edited file with the option to discard unsaved changes.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-Edited-File-Context-Menu.webp)

To discard unsaved changes:

1. Navigate to the item you want to delete in your collection or File Browser.
2. Open the *Context Menu* by clicking the icon in the top right of the file card.
3. Select *Discard unsaved changes*.
4. In the *Discard unsaved changes* modal, review the files that will be affected (if you are discarding a folder, this may affect many files).
5. Click *Discard unsaved changes*.

CloudCannon will discard your unsaved changes and enable the *Delete* option in the *Context Menu* and *File menu*.

Alternatively, you can discard unsaved changes from the editing interface using the *File menu* in the top left corner.

> *New* files will be destroyed when you discard unsaved changes.

## Restore a deleted file

You can restore files marked for deletion before you [save your site](/documentation/user-articles/save-your-changes/). Restoring a file does not restore any unsaved changes discarded before marking the file for deletion.

To restore a file:

1. Navigate to the item you want to delete in your collection or File Browser.
2. Open the *Context Menu* by clicking the icon in the top right of the file card.
3. Select *Restore file*.

CloudCannon will restore your file and remove the *Deleted* [badge](/documentation/user-articles/edit-your-files/#file-badges).

![A closeup of the Collection Browser shows the Context Menu for a deleted file with the option to restore.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-Deleted-File-Context-Menu.webp)

Alternatively, you can restore a file using the *File menu* in the top left of an editing interface or the *Restore file* button in the *Deleted file banner* at the bottom of an editing interface.


---

---
title: Edit your files
description: Learn how to edit your files in CloudCannon, use the editing interfaces, and find files with unsaved changes.
url: https://cloudcannon.com/documentation/user-articles/edit-your-files/
content_type: user article
last_modified: 2026-03-29
---

Editing in CloudCannon is as easy as opening a file in one of our in-browser editing interfaces.

CloudCannon supports four editing interfaces:

- [The Visual Editor](/documentation/user-articles/what-is-the-visual-editor/) — This interface offers an interactive preview of your site for editing directly onto the page.
- [The Content Editor](/documentation/user-articles/what-is-the-content-editor/) — This interface offers a rich text editor useful for clean, distraction-free editing of content-heavy files.
- [The Data Editor](/documentation/user-articles/what-is-the-data-editor/) — This interface offers a simple way to manage structured data and doubles as the sidebar in the Visual and Content Editors.
- [The Source Editor](/documentation/user-articles/what-is-the-source-editor/) — This interface offers an in-browser code editor for minor changes.

> Depending on your SSG and site configuration, you may only have access to a subset of these editing interfaces. An editing interface may not be available because:
> 
> - Some SSGs are incompatible with the Visual Editor (e.g., Docusaurus, MkDocs).
> - Some permission levels cannot access the Source Editor (e.g., unavailable to the [Editors Default Permission Group](/documentation/user-articles/what-are-default-permission-groups/#editors) or [Clients](/documentation/user-articles/what-is-client-sharing/)).
> - A Developer on your team has [specified which editing interfaces are enabled](/documentation/developer-articles/set-a-default-editing-interface/) for a particular collection or schema.

In CloudCannon, you can edit your files in editing sessions. An editing session is the period of time between the first change someone makes to any file and when someone clicks the *Save* button. Editing sessions can contain any number of changes to any number of files, with any number of team members contributing to those changes.

To edit your files:

1. Open any file in an editing interface by clicking on that file in the CloudCannon collection or File Browser.
2. Make changes to as many files as you want.
3. When you are done with your editing session, [save your changes](/documentation/user-articles/save-your-changes/) by clicking the *Save* button in the top right of an editing interface or in the *Site navigation*.

Every change you make is remembered by CloudCannon, so you are safe to take a break, close the editing interface, refresh the tab, change the editing interface, or switch who is editing the file any time.

## Editing interface navigation

The *Editing interface navigation* has a number of tools to help you edit your files.

![The Editing interface header, showing the return button, file details, update status, avatars, editing dropdown, interface buttons, and save button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Editing-Interface-Header.webp)

From left to right, the navigation items are:

- The *Update status* indicator — This shows you the last time this file was last updated.
- *Avatars* — These appear when a team member opens a file in an editing interface. One avatar is highlighted as the file editor with a green circle and pencil icon.
- The *Editing/Viewing dropdown* — This dropdown allows you to switch between *Editing* and *Viewing* a file.
- The *Interface* buttons — This allows you to easily switch between CloudCannon’s four editing interfaces: the Visual, Content, Data, and Source Editors. You will see between two and four options depending on how your site is configured.
- The *File menu* — Sometimes called the *Context Menu*, this menu contains all your file actions.
- The *Information* button — This opens the *Editing help* modal, which provides a helpful walkthrough for the features of your editing interface.
- The *Save* button — When you are ready to [save the changes to your site](/documentation/user-articles/save-your-changes/), the *Save* button will open the *Review changes* modal. Saving your changes allows you to see them live on your [Testing Domain](/documentation/user-articles/what-is-a-testing-domain/) or [Custom Domain](/documentation/developer-articles/what-is-a-custom-domain/).

On smaller screen sizes, some of these options will collapse into the *File menu*.

## Context Menu

The *Context Menu* in the top right of the editing interface contains your file actions.

![A screenshot of the Context Menu in the top right of the editing interface.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Context-Menu.webp)

These actions include:

- *Open URL* — Open this file’s webpage in another tab, using your [Testing Domain](/documentation/user-articles/what-is-a-testing-domain/) or [Custom Domain](/documentation/developer-articles/what-is-a-custom-domain/). This will only show your [saved changes](/documentation/user-articles/save-your-changes/).
- *Copy output URL* — Copies the output URL for this file to your clipboard.
- *Open Source Folder* — Open the source folder for this file (not available to the [Editors Default Permission Group](/documentation/user-articles/what-are-default-permission-groups/#editors) or [Clients](/documentation/user-articles/what-is-client-sharing/)).
- *Open Collection* — Open the collection folder for this file. The word "collection" will be replaced with the name of your collection.
- *Move to new folder* — Create a new folder inside your current folder, and move this file to that new folder.
- *Clone item* — Create a duplicate copy of this file with "-copy" added to the filename.
- *Rename item* — Opens a pop-up window to edit the name of your file. Renamed files will appear in your browser twice. The file with the new name will have a *New* badge, and the file with the old name will have a *Deleted* badge.
- *Publish to posts* — Moves your current file to the Posts folder (Jekyll only).
- *Discard unsaved changes* — Discard any unsaved changes made to this file.
- *Delete item* — Mark this file for deletion next time you [save your changes](/documentation/user-articles/save-your-changes/). You cannot delete a file until you have discarded any unsaved changes.

You can also access some of these file actions in the collection browser using the *Context Menu* at the top right of a [file card](/documentation/developer-articles/configure-your-card-previews/).

![The collection browser shows a series of files, one with the Context Menu open from the top right of the file card.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-File-Context-Menu.webp)

## Collaborate with your team

Editing in CloudCannon is collaborative, enabling you to create content together with your team. You and your team can edit multiple files across your site concurrently.

For each file, one person can edit the file while any number of people view their edits live. You can switch which team member is *Editing* a file at any time, using the *Editing/Viewing dropdown* or the *Switch to editing* button in the banner at the bottom of the editing interface.

![A screenshot of the Content Editor in read-only mode, with a banner at the bottom to switch to editing.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Viewing-Mode.webp)

While *Editing*, all the changes you make to your file are visible to the rest of your team. While *Viewing*, you can interact with the file in read-only mode. You can switch between *Editing* and *Viewing* as many times as necessary.

CloudCannon will remember any updates you make in-app — your content is safe if you need to switch the editing interface or which team member is editing a file.

> Need to find the file a team member is working on? Click on their avatar to see a list of their open files.

## Split-screen

If you want to see your editing interface and collection browser simultaneously, you can use CloudCannon split-screen. Toggle split-screen using the *Toggle Split-screen* button in the bottom left of the editing interface. Split-screen is only available on screens 1600px or wider.

![The toggle split-screen button in the bottom left of the editing interface.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Split-Screen-Toggle.webp)

To close split-screen, click the *Close Split-screen* button in the top left of your editing interface.

## Close editing interface

When you are ready to leave the editing interface, you can click the *Return to Site* button in the top left of the editing interface.

## File badges in the collection browser

As you make changes, CloudCannon will add a file badge to each [file card](/documentation/developer-articles/configure-your-card-previews/) to summarize the type of changes. These badges are useful for understanding what type of unsaved changes your site has, particularly in the collection or File Browser or the *Review changes* modal when you [save your changes](/documentation/user-articles/save-your-changes/).

Changed files will receive a *New*, *Edited*, or *Deleted* badge to indicate the type of unsaved changes.

![A closeup of the collection browser showing the New, Edited, and Deleted badges on files with unsaved changes.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-File-Card-Badges.webp)

- The *New* badge indicates that this [file was recently uploaded](/documentation/user-articles/add-a-file/) or created.
- The *Edited* badge indicates that this file’s content has been updated.
- The *Deleted* badge indicates that you or a team member have marked this file for deletion. Saving your site will delete this file. You can [restore deleted files](/documentation/user-articles/delete-a-file/#restore-a-deleted-file) any time before you [save your changes](/documentation/user-articles/save-your-changes/) using the context menu in the top right of the file card.

> Renamed files will appear twice; the file with the new name will have a *New* badge, and the file with the old name will have a *Deleted* badge.


---

---
title: Export your form submissions
description: Learn how to export your form submissions in CloudCannon.
url: https://cloudcannon.com/documentation/user-articles/export-your-form-submissions/
content_type: user article
last_modified: 2026-04-02
---

To export your *Inbox* submissions as a `.csv` file:

1. Select the category tab you want to export.
2. Click the *Export* button at the top of the *Inbox*.

CloudCannon will download the submissions for the selected category.

![A screenshot of the Inbox shows a list of form submissions under the All category, with an Export button at the top.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Inbox-All.webp)


---

---
title: Generate new recovery codes
description: Learn how to generate new recovery codes for a CloudCannon account with multi-factor authentication.
url: https://cloudcannon.com/documentation/user-articles/generate-new-recovery-codes/
content_type: user article
last_modified: 2026-04-11
---

You may need to generate new recovery codes if:

- You have used all sixteen codes from your previous set.
- The secure location where you store your codes has been compromised.

> You cannot disable this feature once you enable MFA for your CloudCannon account. For more information about MFA, please contact our [support team](/support/).

To generate new recovery codes:

1. Log in to CloudCannon.
2. Navigate to the *Multi-factor Authentication* page under *Account Settings.*
3. Click the *Generate new recovery codes* button.
4. CloudCannon will generate sixteen recovery codes for your account. Copy these recovery codes and store them in a secure location.
5. Click the *I have saved my recovery codes* button. If you cancel or click away from this modal before clicking this button, your new recovery codes will not overwrite your existing recovery codes. You must explicitly agree that you have saved your recovery codes.

Your new recovery codes are now associated with your account.

> If you have lost your recovery codes, please generate a new set immediately.
> 
> If you can no longer log in to your CloudCannon account because you do not have access to your device, authentication app, or recovery codes, please contact our [support team](/support/) as soon as possible.


---

---
title: How CloudCannon handles failed payments
description: After a failed payment, we try to give you plenty of time to set up a new payment method.
url: https://cloudcannon.com/documentation/user-articles/how-cloudcannon-handles-failed-payments/
content_type: user article
last_modified: 2026-04-11
---

We realize credit cards sometimes decline for unknown reasons, so we try to give you plenty of time to try a new payment method. After a failed payment, we retry the payment four times over the next three weeks. If we’re still unsuccessful during this period, we will pause your subscription.

When your subscription is paused:

- You will not be able to edit your Sites through CloudCannon.
- Your hosted websites will be unavailable.
- You can create and download a backup of your Site files.

For any issues with billing, please reach out to [our support team](/support/). We're always happy to help.


---

---
title: How to pay for CloudCannon
description: We currently accept Visa and Mastercard credit cards for payment for paid plans and invoicing on Enterprise plans.
url: https://cloudcannon.com/documentation/user-articles/how-to-pay-for-cloudcannon/
content_type: user article
last_modified: 2026-04-11
---

### Payment Methods

We currently accept Visa and Mastercard credit cards for payment for paid plans and invoicing on Enterprise plans.

### Upgrading / Downgrading

When upgrading or downgrading your account, we perform the following actions:

1. Calculate the time left on your billing period on your current plan and credit this on your next invoice
2. Calculate the time left on your billing period on your new plan and debit this on your next invoice
3. On your next invoice, you will see these adjustments.


---

---
title: Introduction to Accounts
description: Learn how to manage your CloudCannon account, including billing, Organizations, and Multi-factor Authentication.
url: https://cloudcannon.com/documentation/user-articles/introduction-to-accounts/
content_type: user article
last_modified: 2026-02-18
---

Your CloudCannon account is where you manage your identity, billing, and Organization subscription.

Articles in this section are useful for everyone with a CloudCannon account, *Organization Owners*, and team members responsible for your CloudCannon subscription.

In the Accounts section of our User documentation, we cover:

- CloudCannon Accounts — Learn how to create, manage, and delete your CloudCannon account
- Billing — Learn how to manage your CloudCannon subscription, including payment details and invoices
- Owning an Organization — Learn how to manage and customize your *Organization*
- Multi-factor Authentication — Learn how to protect your CloudCannon account with additional identity authentication

Let's briefly introduce a few of these topics.

## CloudCannon Accounts

To use CloudCannon, you need to have a CloudCannon account (unless you are using [Client Sharing](/documentation/user-articles/what-is-client-sharing/)). Your CloudCannon account allows you to own *Organizations* or be a member of someone else's *Organization*.

For a more in-depth explanation of accounts, please read our documentation:

- [Create a CloudCannon account](/documentation/user-articles/create-a-cloudcannon-account/)

## Billing

> For the most up-to-date information on CloudCannon subscriptions, please see our [pricing page](/pricing/).

CloudCannon subscriptions are based on the plan and usage for each *Organization*. Members of the *Owners* or *Billing* [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/) can manage your subscription, payment details, and invoices through CloudCannon.

For a more in-depth explanation of billing, please read our documentation:

- [How to pay for CloudCannon](/documentation/user-articles/how-to-pay-for-cloudcannon/)
- [Accessing and configuring your invoices](/documentation/user-articles/accessing-and-configuring-your-invoices/)
- [How CloudCannon handles failed payments](/documentation/user-articles/how-cloudcannon-handles-failed-payments/)

## Owning an Organization

You can be the owner of several *Organizations* in CloudCannon, each with its own subscription, **team members**, and **Sites**. Anyone in the *Owners* [Default Permission Group](/documentation/user-articles/what-are-default-permission-groups/) can customize and manage an *Organization*.

For a more in-depth explanation of owning an Organization, please read our documentation:

- [Customize CloudCannon to match your brand](/documentation/user-articles/customizing-cloudcannon-to-match-your-brand/)
- [Recover access to your Organization](/documentation/user-articles/recovering-access-to-your-organization/)
- [Resolve ownership over a Custom Domain](/documentation/user-articles/resolving-ownership-over-a-custom-domain/)

## Multi-factor Authentication

**Multi-factor Authentication** adds an additional identity verification step when you log in to CloudCannon, such as entering a temporary code from an authenticator app. For security or auditing reasons, your *Organization* may require you to use MFA.

For a more in-depth explanation of Multi-factor Authentication, please read our documentation:

- [What is Multi-factor Authentication?](/documentation/user-articles/what-is-multi-factor-authentication/)
- [Generate new recovery codes](/documentation/user-articles/generate-new-recovery-codes/)


---

---
title: Introduction to CloudCannon UI
description: Learn your way around the CloudCannon app, including Sites, Browsers, and Editing Interfaces.
url: https://cloudcannon.com/documentation/user-articles/introduction-to-cloudcannon-ui/
content_type: user article
last_modified: 2026-03-11
---

The CloudCannon **User Interface** is where you manage your website content. Whether you are editing a blog post, adding a new staff member to your "About Us" page, or browsing your **files**, familiarizing yourself with the CloudCannon interface will help you work efficiently.

Articles in this section are a great place for new Users to learn what UI elements are called, where to find specific tools, and how to navigate your content.

In the CloudCannon UI section of our User documentation, we cover:

- Sites — Learn how CloudCannon organizes your website(s)
- Browsers — Learn how to find your website content on a *Site* in CloudCannon, and how to navigate your *Projects*
- Editing Interfaces — Learn about CloudCannon's editing interfaces for updating your website content

Let's briefly introduce a few of these topics.

## Sites

Sites are the main way CloudCannon organizes your content. Each Site connects to a branch of your **Git repository**. The *Site Header* at the top of the screen shows which *Site* you are viewing and provides access to *Site* settings.

For a more in-depth explanation of the Site interface, please read our documentation:

- [What is the Site Header?](/documentation/user-articles/what-is-the-site-header/)
- [What is the Site Navigation?](/documentation/user-articles/what-is-the-site-navigation/)

## Browsers

Browsers in CloudCannon let you find, browse, sort, and open your website files. There are two main types of browsers: the *Collection Browser* for viewing collections of related content (like all your blog posts or all your product pages), and the *File Browser* for viewing your files by their location in your website's folder structure. If your developer has set up a **Project**, the *Project Browser* provides an overview of your *Project* and its *Sites*.

For a more in-depth explanation of these browsers, please read our documentation:

- [What is the File Browser?](/documentation/user-articles/the-file-browser/)
- [What is the Project Browser?](/documentation/user-articles/what-is-the-project-browser/)

## Editing Interfaces

CloudCannon offers four editing interfaces: the **Visual Editor**, **Content Editor**, **Data Editor**, and **Source Editor**. Each provides a different way to edit your content. The Visual Editor lets you click directly on your page; the Content Editor is a rich text editor; the Data Editor shows structured fields; and the Source Editor shows the raw file.

For a more in-depth explanation of the editing interfaces, please read our documentation:

- [What is the Visual Editor?](/documentation/user-articles/what-is-the-visual-editor/)
- [What is the Content Editor?](/documentation/user-articles/what-is-the-content-editor/)
- [What is the Data Editor?](/documentation/user-articles/what-is-the-data-editor/)
- [What is the Source Editor?](/documentation/user-articles/what-is-the-source-editor/)


---

---
title: Introduction to Editing
description: Learn how editing works in CloudCannon, including configuration, collections, editing and saving changes, and content collaboration.
url: https://cloudcannon.com/documentation/user-articles/introduction-to-editing/
content_type: user article
last_modified: 2026-02-18
---

Editing in CloudCannon allows anyone on your team to contribute to your website, regardless of technical expertise.

Articles in this section are useful for anyone who creates, edits, or manages content on your website.

> If this is your first time creating a site on CloudCannon, or you need a refresher, check out our [Editing in CloudCannon](/documentation/user-guides/editing-in-cloudcannon/) guide!

In the Editing section of our User documentation, we cover:

- Manage your files — Learn how to manage your website files through CloudCannon
- Using Inputs — Learn how to edit file data that isn't the main body of content

Let’s briefly introduce a few of these topics.

## Manage your files

Your website is made up of several files, from layout and developer files that control what each page looks like, to content files that control the text and images on a webpage. With CloudCannon, you can update your website content files easily.

For a more in-depth explanation of how to make changes to your content, please read our documentation:

- [Add a file](/documentation/user-articles/add-a-file/)
- [Edit your files](/documentation/user-articles/edit-your-files/)
- [Delete a file](/documentation/user-articles/delete-a-file/)
- [Save your changes](/documentation/user-articles/save-your-changes/)

## Using Inputs

In CloudCannon, you can use Inputs to edit file data that isn't the main body of content (e.g., titles, descriptions, authors, tags, etc.). These Inputs appear in the sidebar of  the **Visual Editor** and **Content Editor**, and in the **Data Editor**. There are 12 types of Inputs, each with its own fields and controls for editing a specific kind of data.

For a more in-depth explanation of how to use Inputs for editing file data, please read our documentation:

- [What are Inputs?](/documentation/user-articles/what-are-inputs/)
- [What is an Array Input?](/documentation/user-articles/what-is-an-array-input/)
- [What is a Boolean Input?](/documentation/user-articles/what-is-a-boolean-input/)
- [What is a Code Input?](/documentation/user-articles/what-is-a-code-input/)
- [What is a Color Input?](/documentation/user-articles/what-is-a-color-input/)
- [What are Date and Time Inputs?](/documentation/user-articles/what-are-date-and-time-inputs/)
- [What is a File Input?](/documentation/user-articles/what-is-a-file-input/)
- [What is a Number Input?](/documentation/user-articles/what-is-a-number-input/)
- [What is an Object Input?](/documentation/user-articles/what-is-an-object-input/)
- [What is a Rich Text Input?](/documentation/user-articles/what-is-a-rich-text-input/)
- [What is a Select Input?](/documentation/user-articles/what-is-a-select-input/)
- [What is a Text Input?](/documentation/user-articles/what-is-a-text-input/)
- [What is a URL Input?](/documentation/user-articles/what-is-a-url-input/)


---

---
title: Introduction to Hosting
description: Learn how hosting works in CloudCannon, including Testing Domains, web hosting, and form submissions.
url: https://cloudcannon.com/documentation/user-articles/introduction-to-hosting/
content_type: user article
last_modified: 2026-02-24
---

**Hosting** is the process of making your website available on the Internet for visitors to view. Hosting through CloudCannon is optional, and your developer may choose to host with a different service. However, CloudCannon offers additional features if you also host your *Site* here.

> Not all *Sites* are hosted on CloudCannon. Please talk to your developer about whether hosting is relevant to your website.

In the Hosting section of our User documentation, we cover:

- Web Hosting — Learn how web hosting works and how CloudCannon or another provider can make your website available to visitors on the Internet
- Testing Domain — Learn how CloudCannon assigns a free *Testing Domain* to each *Site* so you can preview your content before it goes live
- Forms — Learn how CloudCannon collects form submissions from visitors and how you can view them in your *Site Inbox*

Let's briefly introduce a few of these topics.

## Web Hosting

Web hosting is the process by which your website files are made available to visitors on the Internet. To host your website, you will need a web hosting service, such as CloudCannon or another third-party provider.

For a more in-depth explanation of how web hosting works, please read our documentation:

- [What is web hosting?](/documentation/user-articles/what-is-web-hosting/)

## Testing Domain

> This information is specific to *Sites* hosted through CloudCannon.

Every website has a **Domain Name** to allow visitors to access it online. On CloudCannon, every *Site*  is assigned a free **Testing Domain**, for you to see your live content. This is particularly useful if you have a publishing workflow configured, providing each *Branch Site* with a dedicated *Domain*.

For a more in-depth explanation of Testing Domains, please read our documentation:

- [What is a Testing Domain?](/documentation/user-articles/what-is-a-testing-domain/)
- [View your Testing Domain](/documentation/user-articles/view-your-testing-domain/)

## Forms

> This information is specific to *Sites* hosted through CloudCannon, where your developer has configured forms.

If your website has **Forms** — for example, a contact form or newsletter signup — CloudCannon can collect the submissions. You can view submissions in the CloudCannon interface or have them sent to your email **inbox**.

For a more in-depth explanation of forms, please read our documentation:

- [Viewing your form submissions in CloudCannon](/documentation/user-articles/viewing-your-form-submissions-in-cloudcannon/)


---

---
title: Introduction to Sharing
description: Learn how to collaborate with others on CloudCannon, including Permission Groups, Site Sharing, and Client Sharing.
url: https://cloudcannon.com/documentation/user-articles/introduction-to-sharing/
content_type: user article
last_modified: 2026-02-24
---

CloudCannon allows you to collaborate with everyone who needs access to your website. This could include content writers, developers, product managers, finance teams, team leads, clients, project stakeholders, and more. For every person you invite, CloudCannon allows you to control which **Sites** they have access to, and which actions they can take.

Articles in this section are helpful for team leaders who need to manage access to CloudCannon, or for individual users to see what they have access to in CloudCannon.

In the Sharing section of our User documentation, we cover:

- Organizations — Learn about *Organizations*, including how to join or leave one, and add or remove a team member
- Permission Groups — Learn what actions you are permitted to take in CloudCannon, or manage a team members permissions
- Site Sharing — Learn how to share a specific *Site* (or *Sites*) on CloudCannon without inviting someone to your *Organization*
- Client Sharing — Learn how to share your *Site* on CloudCannon with an external collaborator, without them needing a CloudCannon account

Let's briefly introduce a few of these topics.

## Organizations

In CloudCannon, your **Organization** is the highest level of content management on CloudCannon. Each *Organization* has an associated CloudCannon subscription and can contain all your websites, team members, and resources. You can be a member of multiple *Organizations* in CloudCannon.

For a more in-depth explanation of Organizations, please read our documentation:

- [What is an Organization?](/documentation/user-articles/what-is-an-organization/)
- [What is a team member?](/documentation/user-articles/what-is-a-team-member/)
- [Join or leave an Organization](/documentation/user-articles/join-or-leave-an-organization/)
- [Add a team member to your Organization](/documentation/user-articles/add-a-team-member-to-your-organization/)
- [Remove a team member from your Organization](/documentation/user-articles/remove-a-team-member-from-your-organization/)

## Permission Groups

**Permission Groups** determine what actions a team member in your *Organization* can perform. Each *Permission Group* defines exactly what its members are allowed to see, edit, and create. Everyone in your *Organization* is a member of at least one *Permission Group*. CloudCannon provides five **Default Permission Groups** for every *Organization*: Owners, Developers, Technical Editors, Editors, and Billing.

For a more in-depth explanation of Permission Groups, please read our documentation:

- [What are Permission Groups?](/documentation/user-articles/what-are-permission-groups/)
- [What are Default Permission Groups?](/documentation/user-articles/what-are-default-permission-groups/)
- [Manage my permissions](/documentation/user-articles/manage-my-permissions/)
- [Add a team member to a Permission Group](/documentation/user-articles/add-a-team-member-to-a-permission-group/)
- [Remove a team member from a Permission Group](/documentation/user-articles/remove-a-team-member-from-a-permission-group/)

> Some *Sites* may have *Custom Permission Groups* configured. For more information, please read our Developer Documentation on [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/).

## Site Sharing

**Site Sharing** allows you to give someone access to specific *Sites* in your *Organization*. This is useful when you want to collaborate with someone who has a CloudCannon account, without giving them access to all the *Sites* in your *Organization*.

For a more in-depth explanation of Site Sharing, please read our documentation:

- [Share a Site with Site Sharing](/documentation/user-articles/share-a-site-with-site-sharing/)

## Client Sharing

**Client Sharing** allows you to give someone who does not have a CloudCannon account access to a specific *Site* in your *Organization*. *Clients* will log in using a site-specific password and edit or review content through a simplified interface.

For a more in-depth explanation of Client Sharing, please read our documentation:

- [What is Client Sharing?](/documentation/user-articles/what-is-client-sharing/)


---

---
title: Introduction to Syncing & Publishing
description: Learn how CloudCannon syncs your files and how to publish changes from a test copy to your live website.
url: https://cloudcannon.com/documentation/user-articles/introduction-to-syncing-and-publishing/
content_type: user article
last_modified: 2026-03-11
---

CloudCannon uses a technology called **Git**. Git safely stores your website files, lets you revert to previous versions of your **Site** (in case something goes wrong), allows you to maintain multiple copies of your *Site*, and tracks who made which changes and when. Most of the Git side of CloudCannon is managed by your developer, but it's important to know some Git terms for updating content, too.

- **Syncing** is when CloudCannon automatically synchronizes the content of your website stored in your **Git Repository** (the safe place where your developer stores your website files) and your *Site* on CloudCannon. This means that any changes made to your website are reflected in both places: whether it's a content update in CloudCannon or a code change by a developer.
- *Publishing* is when CloudCannon publishes changes from one copy of your website to another, allowing you to test your content updates on a dedicated copy of your website before they go public.

> Not all *Sites* will have a publishing workflow configured. Please talk to your developer about whether publishing is relevant to your website.

In the Syncing & Publishing section of our User documentation, we cover:

- Syncing Paused — Learn how CloudCannon protects your unsaved changes when someone saves changes to the same file
- Branching — Learn how you can work on a *Branch* (your own copy of your website) and update the *Publish Branch* (the main copy of your website)
- Publishing Conflicts — Learn how CloudCannon protects the saved changes on your *Branch* when they conflict with changes from your *Publish Branch*

Let's briefly introduce a few of these topics.

## Syncing Paused

Sometimes, CloudCannon may pause syncing while you have unsaved changes on your **Site**.  This is to protect your unsaved changes from incoming changes made by other people. You can easily resolve this by saving your unsaved changes.

For a more in-depth explanation of syncing paused, please read our documentation:

- [Why is syncing paused?](/documentation/user-articles/why-is-syncing-paused/)
- [Resume syncing](/documentation/user-articles/resume-syncing/)

## Branching

> This information is specific to *Sites* with a publishing workflow.

If your developer has added a publishing workflow to your **Site**, everyone can work on their own copy of your website, called a *Branch*. While editing on your *Branch*, you don't need to worry about your changes going live: only you and anyone you share the link with will see your *Site*.

When you are ready for these changes to go live, you can publish to the main copy of your website, called a *Publish Branch*. Also, if anyone else updates your main *Branch* from another copy of your *Site*, you can easily update your copy of the website from the *Publish Branch*.

If your developer has created a **Project** for your website, you can view all the *Branches* and their publishing relationships in one place.

For a more in-depth explanation of branching, please read our documentation:

- [What is a Project?](/documentation/user-articles/what-is-a-project/)
- [What is a Publish Branch?](/documentation/user-articles/what-is-a-publish-branch/)
- [Update from a Publish Branch](/documentation/user-articles/update-from-a-publish-branch/)

## Publishing Conflicts

> This information is specific to *Sites* with a publishing workflow.

Sometimes, when you try to update from your **Publish Branch**, CloudCannon will warn you about a **Publishing Conflict**. This happens when the saved changes on your *Branch* and the saved changes to the same file on your *Publish Branch* are different. CloudCannon will help you resolve this conflict by allowing you to choose which changes to keep, preventing one set of changes from overwriting the other.

For a more in-depth explanation of publishing conflicts, please read our documentation:

- [What are publishing conflicts?](/documentation/user-articles/what-are-publishing-conflicts/)
- [Resolve publishing conflicts](/documentation/user-articles/resolve-publishing-conflicts/)


---

---
title: Join or leave an Organization
description: Learn how to accept or decline an invitation to join a CloudCannon Organization or leave an Organization you are a member of.
url: https://cloudcannon.com/documentation/user-articles/join-or-leave-an-organization/
content_type: user article
last_modified: 2026-04-11
---

## Join an Organization

To join an [Organization](/documentation/user-articles/what-is-an-organization/) in CloudCannon, [an existing member must invite you](/documentation/user-articles/add-a-team-member-to-your-organization/). When someone invites you, CloudCannon will send you an email invitation with the name of the Organization.

To join an Organization in CloudCannon:

1. Log in to CloudCannon or create an account using the link in your email invitation.
2. Click on your avatar in the bottom left of the app to open the *Account menu* and select *Organizations*. This will open the *Organizations Browser* showing all your current Organizations and pending invitations.
3. Under *Pending invitations*, click the *Accept* button next to the Organization you want to join.

Once you accept an invitation, CloudCannon will add you to the Organization. You will automatically be a member of the [Permission Group(s)](/documentation/user-articles/what-are-permission-groups/) selected by the person who invited you.

![A screenshot of the Organization Browser shows one pending invitation and one Organization card.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Organization-Browser-Pending-Invite.webp)

Alternatively, you can decline an invitation by clicking the *Decline* button. However, once you decline an invitation to an Organization, a current member of that Organization must re-invite you if you want to join at a later date.

## Leave an Organization

To leave an Organization in CloudCannon:

1. Navigate to the *My permissions* page under *Org settings.*
2. Click the *Leave Organization* button in the top right.
3. Confirm that you want to leave this Organization by double clicking the *Leave Organization* button in the confirmation modal.

![A screenshot of the My Permissions page shows one Permission Group and the Leave Organization button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-My-Permissions-Page.webp)

CloudCannon will remove you from this Organization.


---

---
title: Manage my permissions
description: Learn how to review the Permission Groups you belong to and leave a Permission Group.
url: https://cloudcannon.com/documentation/user-articles/manage-my-permissions/
content_type: user article
last_modified: 2026-04-11
---

## Review my current Permission Groups

Permissions control what actions you can perform within your [Organization](/documentation/user-articles/what-is-an-organization/). Your permissions are determined by which [Permission Groups](/documentation/user-articles/what-are-permission-groups/) you belong to.

To view your current permissions:

1. Navigate to the *My permissions* page under *Org settings.*

![A screenshot of the My Permissions page shows which Permission Groups a team member belongs to and the Leave Organization button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-My-Permissions-Page.webp)

## Leave a Permission Group

You can leave a Permission Group at any time. However, you may not have permission to add yourself to a Group. If you accidentally remove yourself from a Permission Group, please contact the appropriate member of your team or read our documentation on [adding team members to a Permission Group](/documentation/user-articles/add-a-team-member-to-a-permission-group/).

> You must be a member of at least one Permission Group in each Organization. If you leave your last Permission Group, this action will also remove you from the Organization.

To leave a Permission Group:

1. Navigate to the *My permissions* tab under *Org settings.*
2. Identify the Permission Group you want to leave and click on the *Context Menu*.
3. Select the *Leave Group* option from the *Context Menu* dropdown.
4. Confirm that you want to leave this Group by clicking the *Leave Group* button in the confirmation modal.

![A screenshot of the My Permissions page shows the Context Menu of a Permission Group with the option to Leave Group.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-My-Permissions-Leave-Group.webp)


---

---
title: Manage spam form submissions
description: Learn how to manage spam form submissions in CloudCannon.
url: https://cloudcannon.com/documentation/user-articles/manage-spam-form-submissions/
content_type: user article
last_modified: 2026-04-02
---

CloudCannon runs your form submissions through a spam filter. Submissions flagged as spam are hidden from your *Sent* category.

To mark a spam submission as not spam:

1. Navigate to the *Spam* category tab in your *Inbox*.
2. Open the context menu for the submission by clicking the three dots.
3. Select *Mark as not spam*.

CloudCannon will move the submission to *Sent*.

To mark a submission as spam:

1. Open the context menu for the submission by clicking the three dots.
2. Select *Mark as spam*.

![A screenshot of the Inbox shows the Spam category with a context menu open on a submission, providing options to manage the submission.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Inbox-Spam.webp)

Marking submissions as spam or not spam helps the spam filter improve over time.


---

---
title: Recovering access to your organization
description: Resolve Organization ownership conflicts.
url: https://cloudcannon.com/documentation/user-articles/recovering-access-to-your-organization/
content_type: user article
last_modified: 2026-04-11
---

Before an Owner leaves your Organization, it is best to upgrade another person to an Owner. If this didn’t happen, contact us, and we will sort something out. Ideally, this is solved by communicating with the original owner.

## Accessing the account through their email

Often organization emails are used when creating an organization account. The email might look like [example@yourcompany.com](mailto:example@yourcompany.com). Someone within the organization might be able to access that account. If that email account has already been deleted, we can try something else. If it still exists, use the [forgotten password form](https://app.cloudcannon.com/users/password/new) to reset the password. Change the owner and remember to be respectful.

## Manual resolution

If CloudCannon needs to to transfer organization ownership manually, we will first validate that the request is valid. If the owner uses a company email, we will validate DNS access to that email. This would give us the confidence that you would add or remove emails for anyone under that domain name. Failing this, we will treat this on a case by case basis.


---

---
title: Remove a team member from a Permission Group
description: Learn how to remove a team member from a Permission Group.
url: https://cloudcannon.com/documentation/user-articles/remove-a-team-member-from-a-permission-group/
content_type: user article
last_modified: 2026-04-11
---

Removing a [team member](/documentation/user-articles/what-is-a-team-member/) from a [Permission Group](/documentation/user-articles/what-are-permission-groups/) will decrease their permissions in your [Organization](/documentation/user-articles/what-is-an-organization/).

> Each team member in your Organization must be a member of at least one [Permission Group](/documentation/user-articles/what-are-permission-groups/). If you remove a team member from the last Permission Group they were a member of, this action will also remove them from your Organization.

There are two ways to remove a team member from a Permission Group. The best method to use will depend on whether you want to:

- Remove a specific team member from multiple Permission Groups.
- Remove multiple team members from a specific Permission Group.

## Remove a specific team member from Permission Groups

To remove a specific team member from one or more Permission Groups:

1. Navigate to the *Team* page under *Org settings*.
2. Under the *Members* tab, click on the member whose permissions you want to update. This will open their *Team member* page.
3. Identify the Permission Group from which you want to remove this team member and click on the *Context Menu*.
4. Select the *Remove from Group* option from the *Context Menu* dropdown.
5. Confirm that you want to remove this team member from this Group by clicking the *Remove from Group* button in the confirmation modal.

![A screenshot of the Team Member page shows the Context Menu for a Permission Group with the option to Remove from Group.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Team-Member-Remove-From-Group.webp)

## Remove team members from a specific Permission Group

To remove a team member from a specific Permission Group:

1. Navigate to the *Team* page under *Org settings*.
2. Click on the *Groups* tab.
3. Under the *Groups* tab, click on the Permission Group from which you want to remove members. This will open the *Permission Group* page.
4. Identify the team member you want to remove from this Group and click on the *Context Menu*.
5. Select the *Remove from Group* option from the *Context Menu* dropdown.
6. Confirm that you want to remove this team member from this Group by clicking the *Remove from Group* button in the confirmation modal.

![A screenshot of the Editors Permission Group page shows the Context Menu for a team member with the option to Remove from Group.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Team-Group-Remove-Member.webp)


---

---
title: Remove a team member from your Organization
description: Learn how to remove a team member from your Organization.
url: https://cloudcannon.com/documentation/user-articles/remove-a-team-member-from-your-organization/
content_type: user article
last_modified: 2026-03-29
---

To remove a [team member](/documentation/user-articles/what-is-a-team-member/) from your [Organization](/documentation/user-articles/what-is-an-organization/):

1. Navigate to the *Team* page under *Org settings*.
2. Under the *Members* tab, click on the team member you want to remove from this Organization.
3. Click the *Remove from Organization* button in the top right of the *Team member* page.
4. Confirm that you want to remove this team member from your Organization by double clicking the *Remove from Organization* button in the confirmation modal.

![A screenshot of the Team Member page shows one Permission Group and the Remove from Organization button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Team-Member-Page.webp)

Alternatively, you can remove a team member from the *Team* page by clicking on the *Context Menu* in the top right of a member card and selecting *Remove from Organization*.

> You can remove multiple people from your Organization at once by deleting a Permission Group. This only works if:
> 
> - You have Custom Permission Groups, AND
> - All the team members you want to remove from your Organization are only members of a single Permission Group.
> 
> For more information, please read our documentation on [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/).


---

---
title: Resend errored form submissions
description: Learn how to resend errored form submissions in CloudCannon.
url: https://cloudcannon.com/documentation/user-articles/resend-errored-form-submissions/
content_type: user article
last_modified: 2026-04-02
---

Sometimes a submission fails to send to one or more targets. These submissions appear in the *Errored* category. A common reason for errored submissions is an incorrectly configured target. For more information, please read our documentation on [connecting your Site to an Inbox](/documentation/developer-articles/connecting-your-site-to-an-inbox/).

To resend an errored submission:

1. Navigate to the *Errored* category tab in your *Inbox*.
2. Open the context menu for the submission by clicking the three dots.
3. Select *Resend*.

![A screenshot of the Inbox shows the Errored category with a context menu open on a submission, displaying the error message and resend option.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Inbox-Errored.webp)


---

---
title: Resolve Publishing Conflicts
description: Learn how to resolve a Publishing Conflict when updating your Site from it's Publish Branch.
url: https://cloudcannon.com/documentation/user-articles/resolve-publishing-conflicts/
content_type: user article
last_modified: 2026-02-10
---

> **Permissions required**
> 
> Members of the Owners, Developers, or Technical Editors [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `site:source-editor:write` and `site:publish:upstream:write` permissions, can resolve Publishing Conflicts.

Publishing conflicts occur when changes to a file on your Site conflict with incoming changes to the same file from your [Publish Branch](/documentation/user-articles/what-is-a-publish-branch/). CloudCannon can detect publishing conflicts after you try to [update your Site from its Publish Branch](/documentation/user-articles/update-from-a-publish-branch/).

> To prevent CloudCannon from detecting publishing conflicts while someone is editing your Site, you cannot attempt to update from your Publish Branch while you have unsaved changes.

CloudCannon will alert you if it detects a Publishing Conflict with the *Conflicts* notification on the *Publish* button in your *Site Navigation*. Clicking on the *Publish* button will take you to the *Publishing* page, where CloudCannon lists all files with incoming changes, including files with conflicts.

![A screenshot of the Publish Button in the Site Navigation shows a Conflicts warning notification in the top right.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Publish-Button-Publishing-Conflict-Notification.webp)

After CloudCannon has detected a Publishing Conflict, you cannot publish to your Publish Branch or save your files until you resolve the conflict by merging the conflicting changes in affected files or abandon the update attempt.

These instructions assume that CloudCannon has detected a Publishing Conflict after you attempted to [update your Site from its Publish Branch](/documentation/user-articles/update-from-a-publish-branch/).

To merge conflicted files:

1. Navigate to the *Publishing* page by clicking the *Publish* button in your *Site Navigation*.
2. Identify which files have conflicts. These files will have the *Conflict* file badge.
3. Click on a conflicted file. CloudCannon will open the *Source Editor* to display the file contents and highlight the conflicted sections. CloudCannon will highlight the changes to the file from your current branch in red and the incoming changes from the Publish Branch in green.
4. Select which changes you want to keep by clicking the *Use current* or *Use incoming* buttons to replace one change with another, or clicking into the *Source Editor* to make a hybrid of the changes manually.
5. (Optional.) Click the *Scroll to next conflict* button to move to the next conflict in a file with multiple conflicts.
6. Click the *Mark resolved* button after resolving all conflicts in a file.
7. Repeat steps 3 - 6 for each conflicted file.
8. Click the *Update from Publish Branch* button when you have resolved all conflicted files.

CloudCannon will complete the update from your Publish Branch, including all resolved and unaffected files.

![A screenshot of the Publishing page shows a conflicted file after attempting to update the Site from the Publish Branch.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Publishing-Page-Publishing-Conflict-Card-Closed.webp)

![A screenshot of the Publishing page shows a conflicted file open in the Source Editor with current and incoming changes highlighted.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Publishing-Page-Publishing-Conflict-Card-Open.webp)

## Abandon an update attempt

You can abandon the update attempt if you do not want to resolve your publishing conflicts immediately. Abandoning an update attempt will allow you to save new changes to your Site and dismiss the warnings about publishing conflicts. However, you will lose all your current unsaved changes.

> We do not recommend editing your files after CloudCannon detects a Publishing Conflict. Please abandon the update attempt to continue editing, or wait until after the conflicts are resolved.

You can abandon a merge attempt at any time. However, you must still resolve all publishing conflicts before you can publish changes from this Site to your Publish Branch. CloudCannon will remind you about any publishing conflicts the next time you try to publish from this Site or update from your Publish Branch.

To abandon the update attempt:

1. Navigate to the *Publishing* page by clicking the *Publish* button in your *Site Navigation*.
2. Click the *Abandon update attempt* button. CloudCannon will open the *Abandon your update attempt?* modal.
3. Confirm your choice by clicking the *Abandon update attempt* button.

CloudCannon will return to the app state before you attempted to update from your Publish Branch.

![A screenshot of the Publishing page shows the Abandon your update attempt? modal and the Abandon update attempt button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Publishing-Page-Publishing-Conflict-Abandon-Modal.webp)

## Publishing Conflicts CloudCannon cannot resolve

In some cases, CloudCannon cannot resolve a Publishing Conflict. If CloudCannon detects a Publishing Conflict that you cannot solve in the *Source Editor* (e.g., a conflict in an image file), a warning notification will appear on the *Publishing* page.

In this case, CloudCannon will immediately abandon the attempt to update your Site from its Publish Branch.

You cannot publish to your Publish Branch until you resolve the conflict in your local development environment.

You can find more information about the conflict in your most recent Syncing log on the *Syncs* tab of the *Status* page.


---

---
title: Resolving ownership over a custom domain
description: Learn how to resolve ownership conflicts when another site claims a Custom Domain.
url: https://cloudcannon.com/documentation/user-articles/resolving-ownership-over-a-custom-domain/
content_type: user article
last_modified: 2026-04-11
---

Sometimes there are unforeseen problems that arise in a team, and domain ownership can fall into the wrong hands. This usually results in a support message to CloudCannon.

When resolving these ownership issues, we do our best to protect all parties involved during these processes. If we are asking for proof of ownership, it is well-intentioned.

Below is the information that is stored with a site:

- Files (Untransferable)
- Domain Name (Transferable)

We can’t transfer the files, but these are hopefully accessible from your end (through storage providers). The domain name can be transferred once the domain ownership is proven.

### Proving domain ownership

Sometimes you can't contact the CloudCannon organization that is using the domain.

In this case, contact support. We'll ask you to demonstrate ownership of the domain by adding a unique TXT DNS record to the root domain. We'll be able to check that you've added this, which will show us that you have control over the domain.

Once your ownership of the domain has been verified, we can remove the domain from the current organization, so that you can add it to your organization.

We'll also contact the current holder of the domain, to let them know what's happening. They'll be given a few days to demonstrate ownership of the domain. If both parties are able to prove ownership, we can't step in.

### Recreating your site

To get your site on your new Organization, add your files and add the domain once transferred. All should be the same. If the old Organization was being used for the same sites, we are happy to sort something out for the costs. This will usually be a coupon for the time remaining on the old Organization.


---

---
title: Resume Syncing
description: Learn how to address conflicting updates in CloudCannon so you can save your changes when two sources attempt to update the same file.
url: https://cloudcannon.com/documentation/user-articles/resume-syncing/
content_type: user article
last_modified: 2026-03-23
---

If an incoming change from your Git repository affects a file with unsaved changes, CloudCannon will [pause Syncing](/documentation/user-articles/why-is-syncing-paused/) to prevent incoming changes from overwriting your unsaved changes.

> Currently, you cannot use CloudCannon to read incoming changes before you resume Syncing. Please speak to your developer to determine the incoming changes to your files.

CloudCannon will notify you about a Syncing Conflict using the *Syncing paused* warning notification above the *Save* button in your *Site Navigation*.

![A screenshot of the Save Button in the Site Navigation shows a Sync Paused warning notification in the top right.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Save-Button-Syncing-Paused-Notification.webp)

Before you can save any changes to unaffected files, you must allow CloudCannon to resume Syncing by saving the files with incoming changes.

To resolve a Syncing Conflict:

1. Click the *Save* button. CloudCannon will open the *Review changes* modal.
2. Select all affected files. These will be highlighted in orange.
3. Click either the *Save selected* or the *Discard selected* button.

CloudCannon will save or discard your unsaved changes, then proceed with updating your files using the incoming changes.

![A screenshot of the Save Changes modal shows a Syncing is paused warning and affected files highlighted in orange.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Save-Changes-Model-Syncing-Paused-Element.webp)

> When you resume Syncing by saving or discarding files with incoming changes, you can also select unaffected files and apply the same action. However, you cannot select only unaffected files. You must save or discard unsaved changes to all files with incoming changes before CloudCannon will allow you to save changes to unaffected files.

In some cases, CloudCannon will be unable to update your Site with the incoming changes even after you try to resume Syncing by saving your changes. For more information, please read our documentation on [resolving Syncing Errors](/documentation/developer-articles/resolve-syncing-errors/).


---

---
title: Save your changes
description: Learn how to save your changes in CloudCannon, see the changes live on your site, and commit to your Git repository.
url: https://cloudcannon.com/documentation/user-articles/save-your-changes/
content_type: user article
last_modified: 2026-03-29
---

Whenever you [edit your files](/documentation/user-articles/edit-your-files/), CloudCannon will remember any updates you make in-app. To see your updates live on your site or commit them to your Git repository, you must save your changes.

Any team member can review and save file changes, even if they did not contribute to those edits.

> It is important to save your changes often, as unsaved changes can prevent other updates to your site. We recommend saving your site after every editing session.

![The Save button with a red notification badge indicating three unsaved changes.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Save-Button-Unsaved-Changes-Notification.webp)

To save your changes:

1. Click the *Save* button in the *Site navigation* sidebar or the top right of your editing interface. CloudCannon will open the *Review changes* modal.
2. Review all unsaved changes and select the files you would like to save. Any file you contributed to will be selected by default.
3. Once you are happy with your selection, click the *Save selected* button.

CloudCannon will rebuild your site and commit your changes to your Git repository. Once the build is complete, your changes will be live on your [Testing Domain](/documentation/user-articles/what-is-a-testing-domain/) and any [Custom Domain connected to your site](/documentation/developer-articles/what-is-a-custom-domain/).

## Review your changes

Clicking the *Save* button will open the *Review changes* modal and provide a comprehensive list of the unsaved changes to your site.

![The Save Changes modal with unsaved changes to three files.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Save-Changes-Modal.webp)

Each file with unsaved changes appears in the *Review changes* modal as a [file card](/documentation/developer-articles/configure-your-card-previews/). Each card shows the title, collection (if applicable), filename, the avatar of each team member who contributed to unsaved changes, and when the file was last updated. The file card will also show a *New*, *Edited*, or *Deleted* [badge](/documentation/user-articles/edit-your-files/#file-badges-in-the-collection-browser) to summarize the unsaved changes to that file.

Each file is grouped into one of three headings: *My changes*, *Other changes*, and *Needs attention*. The *My changes* heading lists all the files where you contributed to unsaved changes. These files are selected by default when you open the *Review changes* modal. The *Other changes* heading lists all the files where you have not contributed to unsaved changes.

You can select as many or as few files as you like using the checkboxes by each heading or file card. The *Save selected* and *Discard selected* buttons at the bottom of the modal allow you to save or discard your selected files as a group. You can also discard unsaved change on individual items using the *Context Menu* in the top right of the file card.

### Needs Attention

In some cases, you may see a *Needs attention* heading. This occurs when an incoming change from outside your *Site* (i.e., from your Developer's coding environment or another connected CloudCannon *Site*) conflicts with your unsaved changes. To protect your unsaved changes, CloudCannon will [pause Syncing](/documentation/user-articles/why-is-syncing-paused/).

![The Review changes modal shows the Needs attention heading with a Syncing is paused warning and an affected file.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Save-Changes-Model-Syncing-Paused-Element.webp)

To resume syncing and save changes to other files on your *Site*, you must save the changes in the affected files or discard those changes. For more information, read our documentation on [resuming Syncing](/documentation/user-articles/resume-syncing/).

### Inputs

Depending on how your developer have configured your *Site*, some file cards may have required input fields before you can save your changes.

![The Save Changes modal with required inputs to save the file.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Save-Changes-Modal-Input-Validation-Element.webp)

Common examples of required inputs are file name, title, and date. Which inputs are required depends on how you have configured your site, particularly the [default path for new files](/documentation/developer-articles/set-the-path-for-new-files/).

### Commit messages

If you or a team member has [configured commit messages](/documentation/developer-articles/configure-your-commit-messages/) for your site, your *Review changes* modal will have a commit message field. This field may be required before you can save your changes.

![The Save Changes modal with a commit message describing the changes made to the site.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Save-Changes-Modal-Commit-Message-Element.webp)

A commit message should summarize the theme of your changes. Good commit messages will help you and other team members in the future by providing a record of why you updated your site. For example:

“Added a profile image and updated the Staff and Contact pages to include our new consultant, Deborah.”

We recommend the following best practices for commit messages:

- Clearly state the purpose of your changes by using verbs (e.g., Added, Updated, Deleted, Fixed, etc.).
- Avoid vague descriptions like “updated code” or “fixed typo”. Be specific.
- Reference any relevant context, such as issue numbers, discussions, or contacts.


---

---
title: Share a Site with Site Sharing
description: Share a single Site with your team members.
url: https://cloudcannon.com/documentation/user-articles/share-a-site-with-site-sharing/
content_type: user article
last_modified: 2026-03-29
---

Site Sharing allows you to invite a [team member](/documentation/user-articles/what-is-a-team-member/) to view, edit, and publish content for a specific Site. With Site Sharing, you can control what a team member can interact with by limiting access to a single Site.

You can share an unlimited number of Sites to a team member.

When you add a team member to a Site in your Organization, CloudCannon will prompt you to add them to a [Permission Group](/documentation/user-articles/what-are-permission-groups/). CloudCannon provides two [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/) per Site for Site Sharing, which have identical permissions to the [Technical Editors](/documentation/user-articles/what-are-default-permission-groups/#technical-editors) and [Editors](/documentation/user-articles/what-are-default-permission-groups/#editors) Groups except with a Site scope. These Permission Groups are named after the Site they allow access to.

> If you want to give someone access to all Sites in your Organization or give them more permissions than a Technical Editor, consider [adding them to a Global Permission Group](/documentation/user-articles/add-a-team-member-to-a-permission-group/).

You can see a list of all the team members invited to a Site on the *Site Sharing* page under *Site Settings.*

![A screenshot of the Site Sharing page shows team members who have access to this site.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Site-Sharing.webp)

Site Sharing Permission Groups will appear under the *Groups* tab on the *Team* page if there is one or more members.

![A screenshot of the Groups tab on the Team page shows a list of Permission Groups.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Team-Groups-Tab.webp)

Team members can see the list of Sites they have access to, [review their permissions](/documentation/user-articles/manage-my-permissions/#review-my-current-permission-groups), and [leave an Organization](/documentation/user-articles/manage-my-permissions/#leave-a-permission-group) through the *My permissions* page under *Org settings*.

## Site Sharing vs. Custom Permission Groups

Using Site Sharing, you can limit access to a single Site in your Organization. You can also achieve this with [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/).

With Custom Permission Groups, you can select which resources to add to each Group, define what actions are allowed for each resource (Read, Write, or Create), alter the scope of a permission, and add file globs and exceptions.

Custom Permission Groups can do everything Site Sharing does and more. For [Team and Enterprise customers](/pricing/), we recommend using Custom Permission Groups rather than Site Sharing for finer control over your content.


---

---
title: Social inputs
description: These inputs are for editing plain text in your data. Each input includes a specific brand icon.
url: https://cloudcannon.com/documentation/user-articles/social-inputs/
content_type: user article
last_modified: 2026-04-11
---

> From July 2024 CloudCannon cannot guarantee support for this input. This is a deprecated input. Please consider using a [Text](/documentation/user-articles/what-is-a-text-input/) or [URL input](/documentation/user-articles/what-is-a-url-input/).

These inputs are for editing plain text in your data. Each input includes a specific brand icon.

## Facebook

Single line input with a Facebook logo for short text values.

Facebook inputs are shown for inputs configured with the type `facebook`, or for input keys matching:

- `facebook`
- `*_facebook`
- `facebook_username`
- `*_facebook_username`
- `facebook_url`
- `*_facebook_url`

![Screenshot of a two Facebook input. The first input uses a Facebook username, and the second input uses a full URL to a Facebook page as values](assets/deprecated/CloudCannon-Documentation-Social-Input-Facebook.png)

File: `Naming convention`

```yaml

facebook: CloudCannon
facebook_username: CloudCannon
facebook_url: 'https://www.facebook.com/CloudCannon'

```

File: `Input configuration`

```yaml

social_handle: CloudCannon
_inputs:
  social_handle:
    type: facebook

```

## Twitter

Single line input with a Twitter logo for short text values.

Twitter inputs are shown for inputs configured with the type `twitter`, or for input keys matching:

- `twitter`
- `*_twitter`
- `twitter_username`
- `*_twitter_username`
- `twitter_url`
- `*_twitter_url`

![Screenshot of three Twitter inputs. The first and third inputs use Twitter usernames, while the second input uses a full URL to a Twitter page as values](assets/deprecated/CloudCannon-Documentation-Social-Input-Twitter.png)

File: `Naming convention`

```yaml

twitter: CloudCannon
twitter_username: CloudCannon
twitter_url: 'https://twitter.com/@jekyllrb'

```

File: `Input configuration`

```yaml

social_handle: CloudCannon
_inputs:
  social_handle:
    type: twitter

```

## Instagram

Single line input with an Instagram logo for short text values.

Instagram inputs are shown for inputs configured with the type `instagram`, or for input keys matching:

- `instagram`
- `*_instagram`
- `instagram_username`
- `*_instagram_username`
- `instagram_url`
- `*_instagram_url`

![Screenshot of two Instagram inputs. The first input uses a full URL to an Instagram page, and the second input uses the name of an Instagram handle as the value](assets/deprecated/CloudCannon-Documentation-Social-Input-Instagram.png)

File: `Naming convention`

```yaml

instagram: purenewzealand
instagram_username: purenewzealand
instagram_url: 'https://www.instagram.com/purenewzealand/'

```

File: `Input configuration`

```yaml

social_handle: CloudCannon
_inputs:
  social_handle:
    type: instagram

```

## GitHub

Single line input with a GitHub logo for short text values.

GitHub inputs are shown for inputs configured with the type `github`, or for input keys matching:

- `github`
- `*_github`
- `github_username`
- `*_github_username`
- `github_url`
- `*_github_url`

![Screenshot of three GitHub username inputs. The first input uses a GitHub username, the second input uses a full URL to a GitHub user, and the third input uses a full URL to a GitHub repository as values](assets/deprecated/CloudCannon-Documentation-Social-Input-GitHub.png)

File: `Naming convention`

```yaml

github: CloudCannon
github_username: CloudCannon
github_url: 'https://github.com/jekyll'
docs_github_url: 'https://github.com/CloudCannon/Documentation'

```

File: `Input configuration`

```yaml

social_handle: CloudCannon
_inputs:
  social_handle:
    type: github

```

## Pinterest

Single line input with a Pinterest logo for short text values.

Pinterest inputs are shown for inputs configured with the type `pinterest`, or for input keys matching:

- `pinterest`
- `*_pinterest`
- `pinterest_username`
- `*_pinterest_username`
- `pinterest_url`
- `*_pinterest_url`

![Screenshot of three Pinterest inputs. The first and second inputs use a Pinterest username, and the third input uses a full URL to Pinterest user](assets/deprecated/CloudCannon-Documentation-Social-Input-Pinterest.png)

File: `Naming convention`

```yaml

pinterest: pinterest
default_pinterest: pinterest
pinterest_url: 'https://www.pinterest.com/pinterest/'

```

File: `Input configuration`

```yaml

social_handle: CloudCannon
_inputs:
  social_handle:
    type: pinterest

```

### Options

Social inputs have the following available options:

**`empty_type`** string

Set how an ‘empty’ value will be saved. Does not apply to existing empty values. Can be one of the following:

- `string` - an empty value for this input will be stored as `""`.
- `null` - an empty value for this input will be stored as a null value (default). This does not apply to TOML files.

## Valid values

Documented below are the valid formats for **facebook**, **twitter**, **instagram**, **github**, and **pinterest** inputs.

The lists of examples are non-exhaustive.

**YAML:**

Empty/null value:

- `social: `

Any valid string (quoted or unquoted):

- `social: ""`
- `social: ''`
- `social: twitter.com/CloudCannon`
- `social: "twitter.com/CloudCannon"`
- `social: 'twitter.com/CloudCannon'`
- `social: "https://twitter.com/CloudCannon"`

Social URLs containing `:` must be surrounded by quotes

**TOML:**

Any valid string:

- `social = ""`
- `social = ''`
- `social = "twitter.com/CloudCannon"`
- `social = 'twitter.com/CloudCannon'`
- `social = "https://twitter.com/CloudCannon"`

**JSON:**

Null value:

- `"social": null`

Any valid string:

- `"social": ""`
- `"social": "twitter.com/CloudCannon"`
- `"social": "https://twitter.com/CloudCannon"`


---

---
title: The File Browser
description: Learn about the CloudCannon File Browser.
url: https://cloudcannon.com/documentation/user-articles/the-file-browser/
content_type: user article
last_modified: 2026-03-29
---

The *File browser* allows you to view all the folder and files in your Site using the same structure as your Git repository. The *File browser* is not filtered by your [Source folder](/documentation/developer-articles/what-is-the-cloudcannon-configuration-file/#the-source-folder), and will show every file in your Git repository, including files for other Sites nested in the same respository.

The *File browser* is similar to a [Collection](/documentation/user-articles/what-is-a-collection/) browser but with fewer restrictions. For this reason, team members must be given [permission](/documentation/user-articles/what-are-permission-groups/) to access the *File browser*, either by being a member of the Technical Editor [default Permission Group](/documentation/user-articles/what-are-default-permission-groups/) or higher, or using the `site:source-editor:read` permission in a [Custom Permission Group](/documentation/developer-articles/what-are-custom-permission-groups/).

You can access the File browser in CloudCannon by clicking *Files* in your *Site Navigation* under the *Developer* heading.

![A screenshot of the Site Navigation shows links to the File Browser and Site Settings.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Navigation-Developer.webp)

The *File browser* shows you all the folders and files in your Site, with each file represented by a Card. These file Cards will show:

- The filename.
- An icon based on the file extension.
- Some metadata associated with that file (e.g., date created, last updated, and file size).
- A preview, if the file is an image.

![A screenshot of the File browser shows several Site files, sort and view dropdowns, the file filter, and the + Add button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-File-Browser.webp)

> Unlike the *Collection browser*, you cannot configure the appearance of file Cards in the *File browser*.

The *Sort* dropdown, the *View* dropdown, and the *File filter* search bar are at the top of the File browser. These tools allow you to customize the order in which your files appear, switch between *List*, *Card*, or *Gallery* view, and search for specific files.

The File also has an *+ Add* button at the top right to add and upload files and subfolders to your Site. You can access additional file actions by opening the *Context Menu* at the top right of any folder or file card.

![A screenshot of the File browser shows the Context Menu open for a folder with several file actions.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-File-Browser-Context-Menu.webp)

Clicking on a file will open it in CloudCannon's [Source Editor](/documentation/user-articles/what-is-the-source-editor/) by default. From your *File browser*, your team members can [add files](/documentation/user-articles/add-a-file/), [edit files](/documentation/user-articles/edit-your-files/), and [delete files](/documentation/user-articles/delete-a-file/).

As you make changes to your files, CloudCannon will help you keep track of those changes by adding a New, Edited, or Deleted *File Badge* to your file Cards. When you [save your changes](/documentation/user-articles/save-your-changes/), CloudCannon will update your Git repository and remove the *File Badges*.


---

---
title: Update from a Publish Branch
description: Learn how to update your branch to match upstream changes on your Publish Branch.
url: https://cloudcannon.com/documentation/user-articles/update-from-a-publish-branch/
content_type: user article
last_modified: 2026-03-29
---

CloudCannon will detect when you or a team member has updated your [Publish Branch](/documentation/user-articles/what-is-a-publish-branch/). You should update your current Site whenever updates are available, particularly if you have long-lived branches or are working on the same files across different branches.

When updates from your Publish Branch are available, a notification icon will appear next to the *Publishing* page link in your *Site navigation*.

![A screenshot of the Publish button shows that one update is available from the Publish Branch.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Publish-Button-Update-Publish-Branch-Notification.webp)

> Updating your Site from its Publish Branch is important to see keep your content consistent with changes from other branches, especially if your team separates projects onto different branches that contribute to the same Publish Branch.

To update your site from its Publish Branch:

1. Click on the *Publish* button in the *Site navigation*. CloudCannon will open the *Publishing* page.
2. On the *Updates available from your Publish Branch* notification, click the *Update this site* button and click again to confirm.

CloudCannon will attempt to update your Site from its Publish Branch.

![A screenshot of the Publishing page shows the Updates available from your Publish Branch notification and the Update this site button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Publishing-Page-Update-Publish-Branch-Notification.webp)

In some cases, CloudCannon cannot immediately update your Site from its Publish Branch, such as when it detects a Publishing Conflict. For more information, please read our documentation on [Publishing Conflicts](/documentation/user-articles/what-are-publishing-conflicts/) and how to [resolve publishing conflicts](/documentation/user-articles/resolve-publishing-conflicts/).


---

---
title: View your form submissions
description: Learn how to view your form submissions in CloudCannon.
url: https://cloudcannon.com/documentation/user-articles/view-your-form-submissions/
content_type: user article
last_modified: 2026-04-02
---

Once you have [connected an Inbox to your Site](/documentation/developer-articles/connecting-your-site-to-an-inbox/), it appears under *Inboxes* in your *Site Navigation*. If you have multiple forms, each *Inbox* appears as a separate item.

To view your form submissions:

1. Click on the *Inbox* name under *Inboxes* in your *Site Navigation*.
2. Click on a submission to view its details. CloudCannon will open a modal with the submission data and target information.

![A screenshot of the Inbox shows a list of form submissions under the All category, with an Export button at the top.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Inbox-All.webp)

![A screenshot of the submission details modal shows the form data, including the sender, subject, and submitted fields.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Inbox-Form-Submission-Modal-Data-Tab.webp)

The details modal has two tabs: *Data* and *Targets*. The *Data* tab shows the form fields submitted by the visitor. The *Targets* tab shows the delivery status for each target integration.

![A screenshot of the submission details modal shows the form data, including the sender, subject, and submitted fields.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Inbox-Form-Submission-Modal-Targets-Tab.webp)

Each submission also has a context menu with more options. Open it by clicking the three dots on the submission.

![A screenshot of the Inbox shows a context menu open on a submission, providing options to manage the submission.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Inbox-Context-Menu.webp)

### Categories

Your *Inbox* is organized into categories, displayed as tabs near the top of the page:

- **All** — Every submission in the *Inbox*
- **Sent** — Submissions that were successfully sent to all targets
- **Pending** — Submissions that are currently being processed
- **Spam** — Submissions flagged as spam by the spam filter
- **Errored** — Submissions that failed to send to one or more targets

For more information, please read our documentation on [managing spam submissions](/documentation/user-articles/manage-spam-form-submissions/), [resending errored submissions](/documentation/user-articles/resend-errored-form-submissions/), and [exporting submissions](/documentation/user-articles/export-your-form-submissions/).


---

---
title: View your Testing Domain
description: Learn about the free .cloudvent.net Testing Domain.
url: https://cloudcannon.com/documentation/user-articles/view-your-testing-domain/
content_type: user article
last_modified: 2026-02-10
---

A Testing Domain is a free *.cloudvent.net* URL that CloudCannon assigns to every Site. You can see your Testing Domain any time after your first successful [Site build](/documentation/developer-articles/what-is-a-site-build/).

To view the home page of your Site on your Testing Domain:

1. Open the Site you want to view in CloudCannon.
2. Click the *Live Site Preview* button the header of your *Site Navigation*.

CloudCannon will open the home page of your Site on your Testing Domain in another tab.

![A screenshot of the Site Header shows a link to the Testing Domain, which appears after your first successful Site build.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Header-Tools-Post-Build.webp)

If the file has an output URL, you can also view specific pages on your Testing Domain.

To view a specific file on your Testing Domain:

1. Open the Site you want to view in CloudCannon.
2. Navigate to the *Collection browser* that contains your file.
3. Identify the file card for your file and click the *Context Menu* icon in the top right of the card. Alternatively, you can open the file in an editing interface by clicking on the card and then click the *Context Menu* icon in the top right of the editing interface.
4. Select the the *Open URL* option in the file *Context Menu*.

CloudCannon will open the page on your Testing Domain in another tab.

![A screenshot of the Collection browser shows the open Context Menu with the Open URL here option.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-Edited-File-Context-Menu.webp)

![A screenshot of the Content Editor shows the open Context Menu with the Open URL here option.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Edited-File-Context-Menu.webp)


---

---
title: What are Date and Time inputs?
description: Learn about Date and Time inputs for editing structured data, including how they work in CloudCannon.
url: https://cloudcannon.com/documentation/user-articles/what-are-date-and-time-inputs/
content_type: user article
last_modified: 2026-03-29
---

Date and Time inputs are editing interfaces for date and time values. You can use these inputs in the Data Editor, Content Editor, or Visual Editor to edit structured data in data files or front matter.

There are three types of Date and Time inputs:

- Datetime
- Date
- Time

## Date and Time input types

### Datetime

The Datetime input provides an editing interface for date and time values.

You can edit the value of a Datetime input by clicking the date or time text field. Clicking on the date text field will open a calendar for selecting dates.

![A screenshot of the Datetime input in the Data Editor shows two text fields for date and time values.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Datetime-Input-Closed.webp)

![A screenshot of the Datetime input in the Data Editor shows an open calendar widget under the date text field.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Datetime-Input-Open.webp)

The Timezone for your Datetime input appears above the input text field.

### Date

The Date input provides an editing interface for date values only.

You can edit the value of a Date input by clicking the date text field. Clicking on the date text field will open a calendar for selecting dates.

![A screenshot of the Date input in the Data Editor shows a text field for a date value.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Date-Input-Closed.webp)

![A screenshot of the Date input in the Data Editor shows an open calendar widget under the date text field.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Date-Input-Open.webp)

The Timezone for your Date input appears above the input text field.

### Time

The Time input provides an editing interface for time values only.

You can edit the value of a Datetime input by typing into the time text field.

![A screenshot of the Time input in the Data Editor shows a text field for a time value.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Time-Input.webp)

## Date and Time input appearance and behavior

You can customize the label, comment, documentation link, and context box for all inputs regardless of type.

![A screenshot of the Datetime Input in the Data Editor with a Context Box underneath the text field.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Datetime-Input-Datetime-With-Context.webp)

Depending on how your developer configured the input, your Date or Time input may have a different Timezone.

![A screenshot of the Datetime Input shows it is using the America/New_York timezone.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Datetime-Input-Datetime-Timezone.webp)

### Input validation

Your Date or Time input may also have input validation, which requires the value to match predefined criteria before you can save your changes.

CloudCannon will show a red `*` next to the name of your Date or Time input if a value is required.

![A screenshot of the Datetime input in the Data Editor shows that no value is causing an input validation error.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Datetime-Input-Datetime-Required.webp)

If you enter a value before the earliest allowed date or after the latest allowed date, CloudCannon will display an error message in red text under the input field.

![A screenshot of the Date input in the Data Editor shows that the current value does not meet validation criteria.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Datetime-Input-Datetime-Start-From.webp)

For more information on configuration options, valid input values, and unconfigured input behavior, please read our developer documentation on [configuring a Date or Time input](/documentation/developer-articles/configure-a-date-or-time-input/) .

## Misconfigured Date and Time inputs

You will see an orange warning box if your Date or Time input is misconfigured.

![A screenshot of a misconfigured Date input in the Data Editor shows an orange warning box.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Datetime-Input-Date-Misconfigured.webp)

Date and Time inputs are misconfigured if:

- The value of a Datetime or Date is not a valid [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
- The value of a Time input is not a string.

For more information on how to fix a misconfigured Date or Time input, please read our developer documentation on [configuring a Date or Time input](/documentation/developer-articles/configure-a-date-or-time-input/).


---

---
title: What are Default Permission Groups?
description: Learn about the default permission groups in every Organization. Permission groups determine what permissions your team members have.
url: https://cloudcannon.com/documentation/user-articles/what-are-default-permission-groups/
content_type: user article
last_modified: 2026-03-29
---

CloudCannon provides several Default [Permission Groups](/documentation/user-articles/what-are-permission-groups/), allowing you to select which level of access is appropriate for each team member. Each Group has a defined scope and set of permissions. These  Groups are:

- Five Permission Groups with Global scope (Owners, Developers, Technical Editors, Editors, and Billing).
- Two Permission Groups per Site, each with a Site scope for Site Sharing (Technical Editors and Editors).
- One Permission Group per Site with Site scope for Client Sharing.

This article will cover the five Default Permission Groups with Global scope. For more information on the Default Permission Groups with a Site scope, please read our documentation on [Site Sharing](/documentation/user-articles/share-a-site-with-site-sharing/) and [Client Sharing](/documentation/user-articles/what-is-client-sharing/).

Four of the Default Permission Groups with Global scope are hierarchical: Owners, Developers, Technical Editors, and Editors. This means that each Group contains the permissions of all the Groups below it in the hierarchy, with the Owners Group containing all permissions and the Editors Group containing the smallest subset of permissions.

The last Default Permission Group, Billing, contains a specific set of permissions to enable its members to manage your CloudCannon subscription. Because you can be a member of multiple Permission Groups, team members of any technical level can be part of the Billing Permission Group.

For a description of every resource available in CloudCannon, please read our [permissions](/documentation/developer-reference/permissions/) reference documentation. To see which resources are enabled for a particular Permission Group in CloudCannon, click on the permission card under the *Settings* tab on any *Group* page.

![A screenshot of the Developers Permission Group page shows one permission under the Settings tab.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Team-Default-Group-Settings-Tab.webp)

## Editors

The Editors Permission Group has the lowest level of access in your Organization. This Group is perfect for team members who want to edit content on your Sites, but not worry about any of the technical aspects.

Members of the Editors Permission Group can:

- Create a Site by branching an existing one.
- See the details and activity history for each Site.
- Edit, add, and delete files from Sites.
- See the build history, build deploy history, and sync status for each Site.
- Publish content through Pull Requests or Immediate Merge.
- Upload to DAMs connected to your Sites.
- Manage responses in your Site inboxes.
- See the details for Permission Groups they belong to.
- View basic details about your Projects and Organization.

## Technical Editors

The Technical Editors Permission Group is similar to the Editors Groups, except members have more detailed technical information about the Sites they update.

Members of the Technical Editors Permission Group can do everything Editors can do, as well as:

- Edit files using the Source Editor.
- Trigger builds, syncs, and build deploys for each Site, and view logs associated with these functions.
- View analytics, including the bandwidth and build time usage for each Site.
- Create a downloadable backup for each Site.

## Developers

The Developers Permission Group provides access to most of your Organization. This Permission Group is ideal for team members you trust to handle all the elements of web design and development.

Members of the Developers Permission Group can do everything Editors, and Technical Editors can do, as well as:

- See and edit Base Domain settings.
- Create new Sites and delete existing ones, independently of branching and publishing workflows.
- Manage settings for each Site, including enabling Site Sharing and Client Sharing, Site Mounting, adding DAMs and forms, configuring authentication, and more.
- Manage Permission Groups, including adding and removing team members and editing which Permission Groups a team member belongs to.
- Add and remove team members from your Organization.
- Create, delete, and edit the settings for Projects, including details and Git repository settings.
- Manage Organization settings, including branding, SSL certificates, Git repository settings, connecting new DAMs, creating new inboxes, and managing transfer requests for transferring Sites between Organizations.

## Owners

The Owners Permission Group has complete control over everything in your Organization.

Members of the Owners Permission Group can do everything Editors, Technical Editors, and Developers can do, as well as:

- Manage billing settings, including subscription details, payment methods, and invoices, as well as view the bandwidth and build time usage reports for the entire Organization.
- Delete an Organization.
- If you have [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/), Owners can also create new Groups.

When you create an Organization, your account is automatically added to the Owners permission group. There must always be at least one team member in the Owners permission group.

## Billing

The Billing Permission Group has a specific set of permissions, ideal for team members who need to manage the financial side of CloudCannon.

Members of the Billing Permission Group can:

- View and edit all Billing details, including bandwidth, build time usage, subscription details, payment methods, and invoices.


---

---
title: What are inputs?
description: Learn about inputs in CloudCannon, including the twelve types of inputs.
url: https://cloudcannon.com/documentation/user-articles/what-are-inputs/
content_type: user article
last_modified: 2026-03-29
---

An input is an editing interface for structured data in your data files or the front matter of markup files. Inputs appear in the [Data Editor](/documentation/user-articles/what-is-the-data-editor/) and the sidebar or data panels in the [Content Editor](/documentation/user-articles/what-is-the-content-editor/) and [Visual Editor](/documentation/user-articles/what-is-the-visual-editor/).

- **Structured data** — Data organized in a clear, predefined, and consistent format. This can be quantitative (e.g., numbers) or qualitative (e.g., text, links, or file paths).
- **Front matter** — Structured data that precedes the main content in a markup file (e.g., a Markdown or MDX file). This data contains information about the file that should not be in the content body, such as the file title, author, or SEO information.

An input could be a text field for the description of your file, a date field for the day a blog was published, a select field with predefined tags for your content, or more.

![A close up of an email input in the Data Editor shows a label, comment, text field, and context dropdown.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Email-Input-With-Context.webp)

Inputs allow your team to edit structured data in their files without using the Source Editor. By configuring each input, you can control its appearance and functionality, creating a custom editing interface for the variables your team needs.

You can configure inputs at any level of the configuration cascade, allowing you to define a default configuration for use anywhere in the Site and then override that default for specific Collections or files. In this way, you can control the scope and priority for a given input configuration.

For more information, please read our documentation on the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/) and [configuring your inputs](/documentation/user-articles/what-are-inputs/).

## Basic input configuration

Every input has some basic configuration: the label, comment, context, and type. The label, comment, and context allow you to describe the intended purpose of the input, while the type determines its functionality.

CloudCannon supports twelve types of inputs.

- [Boolean](/documentation/user-articles/what-is-a-boolean-input/) — Define a true or false value using a checkbox or a switch.
- [Code](/documentation/user-articles/what-is-a-code-input/) — Add a code editor.
- [Color](/documentation/user-articles/what-is-a-color-input/) — Add a color using a color picker with spectrum and transparency controls.
- [Date and Time](/documentation/user-articles/what-are-date-and-time-inputs/) — Define a date and/or time.
- [File](/documentation/user-articles/what-is-a-file-input/) — Upload a file, such as an image or a document, and store the file path.
- [Number](/documentation/user-articles/what-is-a-number-input/) — Add a number using a text box or a range slider.
- [Object](/documentation/user-articles/what-is-an-object-input/) — Group inputs under a single Object.
- [Array](/documentation/user-articles/what-is-an-array-input/) — Create a list of inputs or input groups.
- [Select and Multiselect](/documentation/user-articles/what-is-a-select-input/) — Select one or more options from a predefined list.
- [Text](/documentation/user-articles/what-is-a-text-input/) — Write plain text content.
- [Rich Text](/documentation/user-articles/what-is-a-rich-text-input/) — Write and format markup content in HTML or Markdown.
- [URL](/documentation/user-articles/what-is-a-url-input/) — Add a relative or absolute URL.

Each type of input has additional configuration options. For more information, please read our documentation on each input type.

## Input validation

For some inputs, you may want to ensure that content creators have entered a value before they save their changes, or that a value meets a list of prerequisite criteria. By configuring input validation, CloudCannon will prevent you from saving an input with an invalid value.

In some cases, the CloudCannon UI will change to prevent you from adding invalid input values. For example, CloudCannon will disable the *Add* button on an Array input to prevent you from exceeding the maximum allowed number of items, or prevent you from selecting a date outside of the allowed range in a Datetime input.

For more information on what validation methods are available, please read our documentation on each input type.

## Default behavior for unconfigured inputs

If you have not configured your inputs, CloudCannon will attempt to determine the correct editing interface for your data using the input value and key name.

The value of an unconfigured input can help CloudCannon determine its type. For example, CloudCannon will interpret a key with a `true` or `false` value as a Boolean input and a string value as a Text input. CloudCannon can use this method to determine [Boolean](/documentation/user-articles/what-is-a-boolean-input/), [Number](/documentation/user-articles/what-is-a-number-input/), [Object](/documentation/user-articles/what-is-an-object-input/), [Array](/documentation/user-articles/what-is-an-array-input/), and [Text inputs](/documentation/user-articles/what-is-a-text-input/).

Most input types also have a naming convention that allows CloudCannon to determine the input type by the key name. For example, CloudCannon will interpret any key name ending in `_color` or `_hex` as a Color input and any key name ending in `_path` or `_image` as a File input. Each input type has multiple naming conventions. CloudCannon can use this method to determine [Code](/documentation/user-articles/what-is-a-code-input/), [Color](/documentation/user-articles/what-is-a-color-input/), [Date and Time](/documentation/user-articles/what-are-date-and-time-inputs/), [File](/documentation/user-articles/what-is-a-file-input/), [Number](/documentation/user-articles/what-is-a-number-input/), [Select and Multiselect](/documentation/user-articles/what-is-a-select-input/), [Text](/documentation/user-articles/what-is-a-text-input/), [Rich Text](/documentation/user-articles/what-is-a-rich-text-input/), and [URL inputs](/documentation/user-articles/what-is-a-url-input/).

Using these methods, you can add inputs to your files without the need for configuration. This behavior is convenient if you have simple inputs or do not want to configure inputs. It is also beneficial for new websites on CloudCannon where you have yet to create any CloudCannon-specific configuration.

The default input behavior may not be suitable for you if:

- Your value or key name is not specific enough for CloudCannon to determine your desired input type.
- You want to customize the user experience for your input.

We recommend [configuring your inputs](/documentation/user-articles/what-are-inputs/) to overcome these limitations and for greater control over their functionality and appearance.


---

---
title: What are Permission Groups?
description: Learn about Permission Groups in CloudCannon and how they determine what actions your team can perform.
url: https://cloudcannon.com/documentation/user-articles/what-are-permission-groups/
content_type: user article
last_modified: 2026-03-29
---

In CloudCannon, permissions control what actions your [team members](/documentation/user-articles/what-is-a-team-member/) can perform within your [Organization](/documentation/user-articles/what-is-an-organization/). The Permission Groups a team member belongs to determine their permissions.

A Permission Group defines a set of permissions for each member of that Group. Every team member in your Organization must be a member of at least one Group. When you [invite a team member to your Organization](/documentation/user-articles/add-a-team-member-to-your-organization/), CloudCannon will prompt you to select a Permission Group to add them to.

![A screenshot of the Groups tab on the Team page shows Default, Custom, and Site Share Permission Groups.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Team-Groups-Tab.webp)

![A screenshot of the Developers Permission Group page shows one permission under the Settings tab.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Team-Default-Group-Settings-Tab.webp)

All Permission Groups consist of a list of resources and the scopes those resources apply to.

- **Resource** — Something you can interact with in CloudCannon. A resource could be an individual Site, Pull Request settings, billing information, and more.
- **Scope** — Define how broadly a permission is applied. There are five levels of scope (Global, Project, Site, Group, and Base Domain). How many levels of scope are available will depend on whether you are using [Default](/documentation/user-articles/what-are-default-permission-groups/) or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/).

Each resource in a Permission Group has one or more associated actions: Read, Write, or Create.

- **Read** — The capacity to see a resource and open it to view its contents. Read is the most basic level of a resource. If you do not have Read for a particular resource, that resource will not appear in your CloudCannon interface.
- **Write** — The capacity to edit a resource. If you have Write for a particular resource, CloudCannon will automatically allow you to Read.
- **Create** — The capacity to create more instances of a resource. Create only applies to a few resources. When you create an instance of a resource, CloudCannon will automatically give you permission to Read and Write that instance.

> You can only set Create at a Global scope for most resources with the Create action (except `site-branch`). This is relevant if you want to add Custom Permission Groups.

![A screenshot of the View permission modal shows the scope, target, and resource options for a permission in a Default Permission Group.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Team-View-Permission-Modal.webp)

Let’s walk through an example.

The Default Permission Group [Editors](/documentation/user-articles/what-are-default-permission-groups/#editors) contains the permissions for `site:write` and `site:create`, both with a Global scope. Members of this Permission Group can open and edit any Site in this Organization (because permission to Write includes permission to Read) and create new Sites that they can then edit.

The Editors Group does not contain the permission `site:source-editor:read`, which means members of this Group cannot open any files in [the Source Editor](/documentation/user-articles/what-is-the-source-editor/). The option to open a file in the Source Editor will not appear in the CloudCannon interface, including in:

- The file [*Context Menu*](/documentation/user-articles/edit-your-files/#context-menu) in the File Browser and editing interface.
- The [*Interface* buttons](/documentation/user-articles/edit-your-files/#editing-interface-navigation) at the top right of any editing interface.

For a complete list of resources and their associated actions, please read our [permissions](/documentation/developer-reference/permissions/) reference documentation.

## Default Permission Groups

CloudCannon provides several [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/) on all pricing plans, including four Groups with Global scope (Owners, Developers, Technical Editors, and Editors) and another three Groups per Site with Site scope for [Site Sharing](/documentation/user-articles/share-a-site-with-site-sharing/) and [Client Sharing](/documentation/user-articles/what-is-client-sharing/). Each of these Groups has a defined set of permissions so that you can select the appropriate level of control for each team member.

You cannot edit the resources or scope of Default Permission Groups. Members of the Owners or Developers Permission Group can [invite team members to your Organization](/documentation/user-articles/add-a-team-member-to-your-organization/) and [update which Permission Group team members belong to](/documentation/user-articles/add-a-team-member-to-a-permission-group/).

For more information, please read our documentation on [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/).

## Custom Permission Groups

For [Team and Enterprise plan customers](/pricing/), CloudCannon allows you to create [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/). Custom Permission Groups give you fine-grained control over the permissions in your Organization.

Using Custom Groups, you can add multiple permissions to a Group and alter the scope of each permission from Global to Project, Site, Group, or Base Domain. You can also define file globs and exceptions for each Group for more precise permissions.

For more information, please read our documentation on [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/).

## Multiple Permission Groups

You can be a member of multiple Permission Groups.

Permission Groups are always additive. In other words, permissions from one Group do not negate permissions from another. CloudCannon will allow an action if a team member has permission from at least one source.

Let’s walk through an example.

Heather is a member of Permission Group A, allowing her to access [the Source Editor](/documentation/user-articles/what-is-the-source-editor/) editing interface. She is also a member of Permission Group B, which does not include permission to use the Source Editor. In this example, CloudCannon will allow Heather to use the Source Editor because she has permission to do so as a member of Permission Group A.

The additive nature of Permission Groups is less relevant for Default Permission Groups, as all Default Groups are hierarchical (meaning that each Group also contains the permissions of all Groups below it in the hierarchy). However, for Custom Permission Groups, this also extends to any [exceptions](/documentation/developer-articles/what-are-custom-permission-groups/#exceptions) defined in a Group. If one Group allows an action, an exception in a second Permission Group does not prevent access to that resource.

## Partner Permission Groups

The [CloudCannon Partner Program](/partner-program/) allows agencies or freelancers specializing in web design/development to set up their clients in CloudCannon.

CloudCannon will automatically add Owners from a Partner Organization to their Client Organizations as members of a special Partners Permission Group. Partner Organization Owners can add team members to a Client Organization, allowing them to give developers from their agency access to their Client's Sites.

Partner Organization members in a Client Organization do not contribute to the [maximum number of team members allowed per Organization](/pricing/) and, therefore, do not affect billing for the Client Organization.


---

---
title: What are Publishing Conflicts?
description: Learn about Publishing Conflicts in CloudCannon and how they occur.
url: https://cloudcannon.com/documentation/user-articles/what-are-publishing-conflicts/
content_type: user article
last_modified: 2026-04-11
---

In CloudCannon, a Publishing Conflict occurs when there are two versions of the same file on two different but connected branches, one on your CloudCannon Site and one on your [Publish Branch](/documentation/user-articles/what-is-a-publish-branch/).

> A [Publish Branch](/documentation/user-articles/what-is-a-publish-branch/) the branch immediately "upstream" of the branch you are working on, and is the copy of your website to which you want to publish your changes. Publishing Conflicts can occur if you [connect a Publish Branch](/documentation/developer-articles/connect-a-publish-branch/) to your Site.

When you attempt to [update your Site from its Publish Branch](/documentation/user-articles/update-from-a-publish-branch/), CloudCannon can detect if incoming changes conflict with the changes saved to your current Site. To prevent one version of the file from overwriting the other, CloudCannon will pause your update attempt and alert you to the Publishing Conflict.

- **Publishing Conflict** — When incoming changes to a file from your [Publish Branch](/documentation/user-articles/what-is-a-publish-branch/) conflict with changes to the same file on your Site.
- **Incoming changes** — These are changes to your Site files originating from outside the branch you are working on, such as from a different branch, CloudCannon Site, or your git repository. All incoming changes are made by a member of your team.

> Publishing Conflicts aren't dangerous to your content or website — they're CloudCannon's way of letting you know that there are two versions of your file, and that you need to choose how to proceed.

CloudCannon will notify you about a Publishing Conflict using the *Conflicts* warning notification next to the *Publishing* page link in your *Site Navigation*.

![A screenshot of the Publish Button in the Site Navigation shows a Conflicts warning notification in the top right.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Publish-Button-Publishing-Conflict-Notification.webp)

You must resolve the Publishing Conflict before CloudCannon will allow you to save any changes to files on your Site. For more information, please read our documentation on [resolving publishing conflicts](/documentation/user-articles/resolve-publishing-conflicts/).

## Example

Let's go through an example of how a Publishing Conflict can occur.

![A diagram of a branching workflow shows three project branches publish to the Staging Branch, which publishes to the Live Website branch.](assets/diagrams/CloudCannon-Documentation-Branching-Workflow-Diagram.png)

We want to remove a product page from our website. We create a new Site branch to work on our changes without affecting the live Site. On our Site, we delete the product page and edit the `products.html` page to remove the link to the page we just deleted from the list of all our available products. We save these changes to our Site.

Coincidentally, another team member is also updating the `products.html` file at the same time. Our team member is changing our main website navigation and wants to rename the `/products/` page to `/services/`. This effectively deletes the `products.html` file and replaces it with the `services.html` file.

Before we can publish our changes to the Publish Branch (i.e., the "Staging website"), our team member publishes their changes to the same Publish Branch.  CloudCannon detects that someone has updated the Publish Branch and notifies us that updates are available for our Site. When we try to update from our Publish Branch, CloudCannon detect the conflicting versions of the `products.html` file.

We have updated the file's contents by removing a link, and our team member has deleted the file entirely and replaced it with `services.html`.

CloudCannon will notify us about the Publishing Conflict on the *Publish* button and on the *Publishing* page.

Before we can save any changes to files on our Site or complete the update from our Publish Branch, we need to resolve the Publishing Conflict for `products.html` by choosing which version of the file to keep: the changes on our current Site, the incoming changes from the Publish Branch, or a hybrid of the two. In this example, we want to create a hybrid of the two commits (remove the link from the new `services.html` file and delete the `products.html` file) and let CloudCannon complete the update from our Publish Branch.


---

---
title: What is a Boolean input?
description: Learn about Boolean inputs for editing structured data, including how they work in CloudCannon.
url: https://cloudcannon.com/documentation/user-articles/what-is-a-boolean-input/
content_type: user article
last_modified: 2026-02-10
---

A Boolean input is an editing interface for true or false values. You can use this input to edit structured data in data files or front matter using the [Data Editor](/documentation/user-articles/what-is-the-data-editor/), or data panels and the sidebar in the [Content Editor](/documentation/user-articles/what-is-the-content-editor/) or [Visual Editor](/documentation/user-articles/what-is-the-visual-editor/).

There are two types of Boolean input:

- Checkbox
- Switch

## Boolean input types

### Checkbox

The Checkbox Boolean input provides an editing interface for true or false values. True values have a checked box, while false values have an unchecked box.

You can change the value of a Checkbox input by clicking on the checkbox.

![A screenshot of the Checkbox Boolean input in the Data Editor shows a true value.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Boolean-Input-Checkbox-True.webp)

![A screenshot of the Checkbox Boolean input in the Data Editor shows a false value.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Boolean-Input-Checkbox-False.webp)

### Switch

The Switch Boolean input provides an editing interface for true or false values. True values show the switch to the right with the text "ON", while false values show the switch to the left with the text "OFF".

You can change the value of a Switch input by clicking on the switch.

![A screenshot of the Switch Boolean input in the Data Editor shows a true value.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Boolean-Input-Switch-True.webp)

![A screenshot of the Switch Boolean input in the Data Editor shows a false value.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Boolean-Input-Switch-False.webp)

## Boolean input appearance and behavior

You can customize the label, comment, documentation link, and context box for all inputs regardless of type.

![A screenshot of the Checkbox Boolean input in the Data Editor shows the label, comment, and context general configuration options.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Boolean-Input-Checkbox-With-Context.webp)

Boolean inputs are simple. You cannot configure additional input behavior besides the general configuration options.

For more information on configuration options, valid input values, and unconfigured input behavior, please read our developer documentation on [configuring a Boolean input](/documentation/developer-articles/configure-a-boolean-input/) .

## Misconfigured Boolean inputs

You will see an orange warning box if your Boolean input is misconfigured.

![A screenshot of a misconfigured Checkbox Boolean input in the Data Editor shows an orange warning box.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Boolean-Input-Checkbox-Misconfigured.webp)

Boolean inputs are misconfigured if:

- The value is not `true` or `false`.

For more information on how to fix a misconfigured Boolean input, please read our developer documentation on [configuring a Boolean input](/documentation/developer-articles/configure-a-boolean-input/).


---

---
title: What is a Code input?
description: Learn about Code inputs for editing structured data, including how they work in CloudCannon.
url: https://cloudcannon.com/documentation/user-articles/what-is-a-code-input/
content_type: user article
last_modified: 2026-02-10
---

A Code input is an editing interface for code or mono-spaced plain text. You can use this input in the Data Editor, Content Editor, or Visual Editor to edit structured data in data files or front matter.

There is only one type of Code input:

- Code

## Code input types

### Code

The Code input provides an editing interface for code or mono-spaced plain text content.

You can edit the value of a Code input by typing in the code area.

![A screenshot of the Code Input in the Data Editor shows code in a text area with syntax highlighting.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Code-Input-Ruby-Codeblock.webp)

## Code input appearance and behavior

You can customize the label, comment, documentation link, and context box for all inputs regardless of type.

![A screenshot of the Code Input in the Data Editor with a Context Box underneath the code area.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Code-Input-With-Context.webp)

Depending on how your developer configured the input, your Code input may have a different height for the code area, tab size, theme color, gutter visibility, or syntax highlighting.

![A screenshot of the Code Input when configured to show a single line of text.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Code-Input-Single-Line.webp)

![A screenshot of the Code Input in the Data Editor shows a theme color applied to the text area.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Code-Input-With-Theme.webp)

### Input validation

Your Code input may have input validation, which requires the input value to meet predefined criteria before you can save your changes. CloudCannon will warn you if your input value is invalid and provide directions on how to fix it.

CloudCannon will show a red `*` next to the name of your Code input if a value is required.

![A screenshot of the Code input in the Data Editor shows that no value is causing an input validation error.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Code-Input-Required-Validation.webp)

If you enter a value under the minimum or over the maximum character count, CloudCannon will display an error message in red text under the input field.

![A screenshot of the Code Input in the Data Editor shows an error message as the value is too few characters.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Code-Input-Min-Length-Validation.webp)

If your developer has configured a pattern for your input value, CloudCannon will warn you when the value does not match the pattern. CloudCannon will show any error messages underneath the code area in red.

![A screenshot of the Code Input in the Data Editor shows an error message as the value does not match the configured pattern.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Code-Input-Pattern-Validation.webp)

For more information on configuration options, valid input values, and unconfigured input behavior, please read our developer documentation on [configuring a Code input](/documentation/developer-articles/configure-a-code-input/) .

## Misconfigured Code inputs

You will see an orange warning box if your Code input is misconfigured.

![A screenshot of a misconfigured Code input in the Data Editor shows an orange warning box.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Code-Input-Misconfigured.webp)

Code inputs are misconfigured if:

- The value is not a string.

For more information on how to fix a misconfigured Code input, please read our developer documentation on [configuring a Code input](/documentation/developer-articles/configure-a-code-input/).


---

---
title: What is a Collection?
description: Learn about Collections in CloudCannon, your home for content files.
url: https://cloudcannon.com/documentation/user-articles/what-is-a-collection/
content_type: user article
last_modified: 2026-03-29
---

A Collection is a group of related files with a similar format (e.g., a folder of pages, blog posts, or data files). Collections are a core part of your CloudCannon CMS experience.

By default, CloudCannon automatically detects your Collections when you first create your [CloudCannon configuration file](/documentation/developer-articles/what-is-the-cloudcannon-configuration-file/) by searching your files for folders of similar content. You can [configure your Collections]() when you first create your Site or at any time by opening your CloudCannon configuration file in the [Data Editor](/documentation/user-articles/what-is-the-data-editor/) or [Source Editor](/documentation/user-articles/what-is-the-source-editor/).

In CloudCannon, your Collections appear in the *Site Navigation* for easy access. Each Collection has a name and icon.

![A screenshot of the Site Navigation shows links to the Collections on this Site, organized into groups.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Navigation-Collections.webp)

Clicking on a Collection will open the *Collection browser*. The *Collection browser* shows you all the files in your Collection, with each file represented by a Card. Depending on how you have configured your Site, these file Cards will show:

- The title of your file.
- An icon.
- Some metadata associated with that file (e.g., the output URL).
- An image within the file or a preview screenshot of the webpage to which the file outputs.

This allows your team members to see all your content at a glance.

![A screenshot of the Collection browser shows previews of several blog files, sort and view dropdowns, the collection filter, and the + Add button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser.webp)

> For more information on configuring how your files look in the *Collection browser*, please read our documentation on [configuring your card previews](/documentation/developer-articles/configure-your-card-previews/).

The *Sort* dropdown, the *View* dropdown, and the *Collection filter* search bar are at the top of the Collection browser. These tools allow you to customize the order in which your files appear, switch between *List*, *Card*, or *Gallery* view, and search for specific files.

By default, Collections also has an *+ Add* button at the top right to add files and subfolders to your Collection. You can access additional file actions by opening the *Context Menu* at the top right of a file card.

![A screenshot of the Collection browser shows the Context Menu open for a file with several file actions.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-Edited-File-Context-Menu.webp)

From your *Collection browser*, your team members can [add files](/documentation/user-articles/add-a-file/), [edit files](/documentation/user-articles/edit-your-files/), and [delete files](/documentation/user-articles/delete-a-file/). Clicking on a file will open it in one of CloudCannon's four editing interfaces: the [Visual Editor](/documentation/user-articles/what-is-the-visual-editor/), the [Content Editor](/documentation/user-articles/what-is-the-content-editor/), the [Data Editor](/documentation/user-articles/what-is-the-data-editor/), or the [Source Editor](/documentation/user-articles/what-is-the-source-editor/).

As you make changes to your files, CloudCannon will help you keep track of those changes by adding a New, Edited, or Deleted *File Badge* to your file Cards. When you [save your changes](/documentation/user-articles/save-your-changes/), CloudCannon will update your Git repository and remove the *File Badges*.

![A screenshot of the Collection browser shows four file cards, three of which have a New, Edited, or Deleted File Badge.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-File-Card-Badges.webp)

You can configure your Collections in multiple ways to create an intuitive editing experience for your team members. This includes configuring the Collection name and icon, adding a description or documentation link, changing how new files are created, or adding a file glob or Schema.

For more information, please read our documentation on [configuring your Collections](/documentation/developer-articles/configure-your-collections/).


---

---
title: What is a Color input?
description: Learn about Color inputs for editing structured data, including how they work in CloudCannon.
url: https://cloudcannon.com/documentation/user-articles/what-is-a-color-input/
content_type: user article
last_modified: 2026-02-10
---

A Color input is an editing interface for color information. You can use this input in the Data Editor, Content Editor, or Visual Editor to edit structured data in data files or front matter.

There is only one type of Color input:

- Color

## Color input types

### Color

The Color input provides an editing interface for color values.

You can edit the value of a Color input by typing in the input text field.

![A screenshot of the Color input in the Data Editor shows a HEX value in the text field.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Color-Input-HEX-Open.webp)

## Color input appearance and behavior

You can customize the label, comment, documentation link, and context box for all inputs regardless of type.

![A screenshot of the Color Input in the Data Editor with a Context Box underneath the text field.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Color-Input-With-Context.webp)

Depending on how your developer configured the input, your Color input may have a different color format or color transparency controls.

![A screenshot of the Color input in the Data Editor shows a RGBA value in the text field.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Color-Input-RGBA-Open.webp)

### Input validation

Your Color input may also have input validation, which requires the value to match predefined criteria before you can save your changes.

CloudCannon will show a red `*` next to the name of your Color input if a value is required.

![A screenshot of the Color input in the Data Editor shows that no value is causing an input validation error.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Color-Input-Required-Validation.webp)

If you enter a value under the minimum or over the maximum character count, CloudCannon will display an error message in red text under the input field.

![A screenshot of the Color input in the Data Editor shows that the value does not meet maximum length requirements.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Color-Input-Max-Length-Validation.webp)

For more information on configuration options, valid input values, and unconfigured input behavior, please read our developer documentation on [configuring a Color input](/documentation/developer-articles/configure-a-color-input/) .

## Misconfigured Color inputs

You will see an orange warning box if your Color input is misconfigured.

![A screenshot of a misconfigured Color input in the Data Editor shows an orange warning box.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Color-Input-Misconfigured.webp)

Color inputs are misconfigured if:

- The value is not a string.

For more information on how to fix a misconfigured Color input, please read our developer documentation on [configuring a Color input](/documentation/developer-articles/configure-a-color-input/).


---

---
title: What is a File input?
description: Learn about File inputs for editing structured data, including how they work in CloudCannon.
url: https://cloudcannon.com/documentation/user-articles/what-is-a-file-input/
content_type: user article
last_modified: 2026-03-29
---

A File input is an editing interface for file paths, allowing you to upload a file to your repository or [DAM](/documentation/developer-articles/integrating-your-dam-with-cloudcannon/), select a previously uploaded file, or add a link to an external file. You can use this input in the Data Editor, Content Editor, or Visual Editor to edit structured data in data files or front matter.

There are three types of File input:

- File
- Document
- Image

## File input types

### File

The File input provides an editing interface for uploading files to your repository or DAM and browsing existing assets.

![A screenshot of an empty File Input in the Data Editor shows a text field, a plus button, and a drag-and-drop area.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-File-Input-Empty.webp)

You can upload a file by dragging and dropping it from your local storage over the File input, or by clicking the *Add file* button at the top right of the input and selecting the *Upload a new file* option. CloudCannon will upload your file to your repository or [DAM](/documentation/developer-articles/integrating-your-dam-with-cloudcannon/).

![A screenshot of the Add file dropdown on a File Input shows the Upload a new file and Select an existing file options.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-File-Input-Dropdown-Open.webp)

You can select an existing file by selecting the Select existing files option. CloudCannon will open the *Files browser* to the upload folder in your repository or [DAM](/documentation/developer-articles/integrating-your-dam-with-cloudcannon/).

![A screenshot of the File Input File Browser shows the default upload location for files, with three files you can select as the Input value.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-File-Input-File-Browser.webp)

When you select a file from your repository or DAM, the File input will display a preview of the image if it is an image file, or file metadata if it is a document file.

![A screenshot of the File Input in the Data Editor shows the preview and metadata for the selected CSS file.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-File-Input.webp)

Alternatively, you can link to an externally hosted file by pasting the file URL into the text field of the File input. CloudCannon will display the title, description, and image for the URL.

![A screenshot of the File Input in the Data Editor shows an external URL value with a preview of the URL image, title, and subtitle.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-File-Input-External-URL.webp)

You can edit the file path of an internal or external file by typing in the text field. To clear the selected file, you can click the *Clear* button at the top right of the input.

### Document

The Document input provides an editing interface for uploading document files to your repository or DAM and browsing existing assets.

![A screenshot of the Document Input in the Data Editor shows the preview and metadata for the selected PDF file.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Document-Input.webp)

> Document Inputs are similar to File Inputs, except they have different defaults and configuration options. For more information, please read our developer documentation on [configuring a File Input](/documentation/developer-articles/configure-a-file-input/).

You can use a Document input in the same way as a File input. When you select a document file from your repository or DAM, the Document input will display the metadata of the document file, including the name, last updated time, and file size.

### Image

The Image input provides an editing interface for uploading image files to your repository or DAM and browsing existing assets.

![A screenshot of the Image Input in the Data Editor shows a preview for the selected image file.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Image-Input.webp)

> Image Inputs are similar to File Inputs, except they have different defaults and configuration options. For more information, please read our developer documentation on [configuring a File Input](/documentation/developer-articles/configure-a-file-input/).

You can use an Image input in the same way as a File input. When you select an image file from your repository or DAM, the Image input will display a preview of the image.

## File input appearance and behavior

You can customize the label, comment, documentation link, and context box for all inputs regardless of type.

![A screenshot of the File Input in the Data Editor with a Context Box underneath the text area.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-File-Input-With-Context.webp)

Depending on how your developer configured the input, your File input may have a different default location for uploading new files or browsing existing files. You might also be limited to uploading or selecting a specific file type.

For Image inputs, CloudCannon may prompt you to crop or resize your image when you upload or select one.

CloudCannon may also create additional copies of an image of different sizes when you upload or select an image using Image input.

### Input validation

Your File input may also have input validation, which requires the value to match predefined criteria before you can save your changes.

CloudCannon will show a red `*` next to the name of your File input if a value is required.

![A screenshot of the File input in the Data Editor shows that no value is causing an input validation error.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-File-Input-Required.webp)

If you enter a value under the minimum or over the maximum character count, CloudCannon will display an error message in red text under the input field.

![A screenshot of the File input in the Data Editor shows that the value does not meet maximum length requirements.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-File-Input-Max-Length.webp)

If you select a file that exceeds the maximum file size limit, CloudCannon will display an error message in red text under the input field.

![A screenshot of the File input in the Data Editor shows that the uploaded file does not meet file size requirements.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-File-Input-Max-File-Size.webp)

If your developer has configured a pattern for your input value (such as specific file extensions), CloudCannon will warn you when the value does not match the pattern. CloudCannon will show any error messages underneath the input field in red.

![A screenshot of the File Input in the Data Editor shows an error message as the value does not match the configured pattern.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-File-Input-Pattern.webp)

For more information on configuration options, valid input values, and unconfigured input behavior, please read our developer documentation on [configuring a File input](/documentation/developer-articles/configure-a-file-input/) .

## Misconfigured File inputs

You will see an orange warning box if your File input is misconfigured.

![A screenshot of a misconfigured File input in the Data Editor shows an orange warning box.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-File-Input-Misconfigured.webp)

File inputs are misconfigured if:

- The value is not a string.

For more information on how to fix a misconfigured File input, please read our developer documentation on [configuring a File input](/documentation/developer-articles/configure-a-file-input/).


---

---
title: What is a Number input?
description: Learn about Number inputs for editing structured data, including how they work in CloudCannon.
url: https://cloudcannon.com/documentation/user-articles/what-is-a-number-input/
content_type: user article
last_modified: 2026-03-29
---

A Number input is an editing interface for numeric values. You can use this input in the Data Editor, Content Editor, or Visual Editor to edit structured data in data files or front matter.

There are two types of Number input:

- Number
- Range

## Number input types

### Number

The Number input provides an editing interface for numeric values.

You can edit the value of a Number input by typing in the text field or clicking the up and down arrows to the right of the text field.

![A screenshot of the Number Input in the Data Editor shows a text field and arrows to increase or decrease the value.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Number-Input.webp)

### Range

The Range input provides a slider interface for selecting a numeric value.

You can edit the value of a Range input by typing in the text field or clicking and dragging the circle left or right along the bar.

![A screenshot of the Range Input in the Data Editor shows a bar with a draggable circle.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Range-Input.webp)

## Number input appearance and behavior

You can customize the label, comment, documentation link, and context box for all inputs regardless of type.

### Input validation

Your Number input may also have input validation, which requires the value to match predefined criteria before you can save your changes.

CloudCannon will show a red `*` next to the name of your Number input if a value is required.

![A screenshot of the Number input in the Data Editor shows that no value is causing an input validation error.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Number-Input-Required.webp)

If you enter a value under the minimum or over the maximum allowed number, CloudCannon will display an error message in red text under the input field.

![A screenshot of the Number input in the Data Editor shows that the value does not meet maximum length requirements.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Number-Input-Max.webp)

For more information on configuration options, valid input values, and unconfigured input behavior, please read our developer documentation on [configuring a Number input](/documentation/developer-articles/configure-a-number-input/) .

## Misconfigured Number inputs

You will see an orange warning box if your Number input is misconfigured.

![A screenshot of a misconfigured Number input in the Data Editor shows an orange warning box.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Number-Input-Misconfigured.webp)

Number inputs are misconfigured if:

- The value is not a number.
- The `max`, `min`, or `step` configuration keys are not defined for a Range Input.

For more information on how to fix a misconfigured Number input, please read our developer documentation on [configuring a Number input](/documentation/developer-articles/configure-a-number-input/).


---

---
title: What is a Project?
description: Learn about Projects in CloudCannon, including how to group Sites and set up branching workflows.
url: https://cloudcannon.com/documentation/user-articles/what-is-a-project/
content_type: user article
last_modified: 2026-03-29
---

> **Some features are only available on our [Team and Enterprise plans](/pricing/).**
> 
> Want to chat about whether this feature is right for you? Our support team is always [happy to hear from you](mailto:success@cloudcannon.com?subject=A%20question%20about%20Projects).

A **Project** is a way to group multiple **Sites** from the same **Git Repository**. By creating a *Project* on CloudCannon, you can designate a **Main Branch**, define branching rules that allow your team members to create their own *Sites*, and set up publishing workflows that control how content moves between branches.

You can access the *Projects Browser* using the *Projects* link in the *App Sidebar*.

## Why use a Project?

*Projects* are useful when you want multiple team members to work on content independently without affecting the live website. Common scenarios include:

- **Create a Staging workflow** — Maintain a Production branch and a Staging branch. Team members create their own branch *Sites* from the Staging *Site*, then merge it back into Staging for review before publishing changes go live to Production.
- **Make content changes in parallel** — Multiple team members can create branch *Sites* from your *Main Branch*, work on changes independently, and merge them back when ready.
- **Control branch defaults** — Determine the default publishing method, authentication settings, and permissions for all branched *Sites* in your *Project*.

Without a *Project*, you would need to manage branches and publishing manually through your *Git Provider*.

## How branching works

*Branching* is the process of copying information from an existing *Site* to a new *Site*, including content, code, and CloudCannon settings. When you create a branched *Site* in CloudCannon, an identical branch is created in your *Git Repository* even if you don't have access to the *Git Provider*.

By copying the CloudCannon settings, each branched *Site* has the same publishing method, authentication rules, permissions, and build settings as its parent, so team members can start editing content immediately.

Changes on each branch *Site* do not affect any other *Site* until explicitly published to its [Publish Branch](/documentation/user-articles/what-is-a-publish-branch/) (the *Publish Branch* does not have to be the same as the parent branch). CloudCannon handles the Git operations and, by default, automatically deletes the branch *Site* after changes are published to keep your *Project* clean.

You can designate a *Main Branch* for your team members to copy (e.g., your Staging branch), or allow team members to branch from any *Site* in your *Project*.

### The *Main Branch*

When you create a *Project*, you can designate one branch in your *Git Repository* as the *Main Branch*. This is most likely your Production or Staging branch (i.e., the most correct and up-to-date branch of your website), but it could be any branch you want your team members to iterate on.

The *Main Branch* determines which *Site* CloudCannon will copy to your branched *Site* when you click the *Create a Site* button on the *Project Sites Browser*.

### Allow all branching

By default, team members can only create branch *Sites* from the *Main Branch*. This keeps your workflow simple and linear. However, if you need a more flexible workflow, you can enable the *Allow all branching* feature to allow team members to branch from any *Site* in your *Project*.

For a tour of the *Project* interface, including the *Projects Browser*, *Project Sites Browser*, *Publishing* tab, and *Project Settings* tab, please read our documentation on [the Project Browser](/documentation/user-articles/what-is-the-project-browser/).


---

---
title: What is a Publish Branch?
description: Learn about Publish Branches in CloudCannon and how connecting one to your Site can benefit your workflow.
url: https://cloudcannon.com/documentation/user-articles/what-is-a-publish-branch/
content_type: user article
last_modified: 2026-04-11
---

CloudCannon is a Git-based CMS, and one of the most useful elements of Git workflows is the capacity to create branches of your website.

- **Branch** — A copy of your website that allows you to update your files without affecting your live content. When you are happy with your changes, you can publish your branch to the "main" copy of your Site.

A Publish Branch the branch immediately "upstream" of the branch you are working on, and is the copy of your website to which you want to publish your changes.

Let's go through an example.

![A diagram of a branching workflow shows three project branches publish to the Staging Branch, which publishes to the Live Website branch.](assets/diagrams/CloudCannon-Documentation-Branching-Workflow-Diagram.png)

The diagram above shows a common Git workflow, with five branches (also known as Sites in CloudCannon). In this example, content creators or developers on your team make a branch to work on each discrete project. This could be writing a new blog post, updating your product catalog by removing a page, or changing your website navigation. These task happen on separate branches so that each team member can work in parallel, with complete control over their project and no risk of accidentally showing incomplete work on your live website.

When a team member is done, they can publish their changes to the Publish Branch. In this example, the three branches "Write a new blog", "Remove a product page", and "Update site navigation" share a Publish Branch: "Staging Website". The Staging Website branch is a great place to see all your team's work together, and review your changes as a whole before making it public.

The Staging Website also has a Publish Branch: the Live Website. When you are ready for your changes to go public, you can publish to the Live Website.


---

---
title: What is a Rich Text input?
description: Learn about Rich Text inputs for editing structured data, including how they work in CloudCannon.
url: https://cloudcannon.com/documentation/user-articles/what-is-a-rich-text-input/
content_type: user article
last_modified: 2026-03-29
---

A Rich Text input is an editing interface for markup content. You can use this input in the Data Editor, Content Editor, or Visual Editor to edit structured data in data files or front matter.

Rich Text inputs have a text area for your content and a WYSIWYG toolbar for formatting your content. You can configure the WYSIWYG toolbar for a Rich Text input in the same way you configure the toolbar for the [Content Editor](/documentation/user-articles/what-is-the-content-editor/). For more information, please read our documentation on [configuring your Rich Text editors](/documentation/developer-articles/configure-your-rich-text-editors/).

There are two types of Rich Text input:

- HTML
- Markdown

> Are you looking for [What is a Text input?](/documentation/user-articles/what-is-a-text-input/)
> 
> Rich Text and Text inputs are similar, except Text inputs are designed for plain text content.

## Rich Text input types

> From a content creator's perspective, the HTML and Markdown Rich Text inputs have the same functionality. The only difference is the format CloudCannon uses to store your data. Whether you use an HTML or Markdown input only depends on your developer's preference.

### HTML

The HTML Rich Text input provides an editing interface for HTML markup content.

You can edit the value of an HTML input by typing in the text area, and apply styles to your text using tools in the WYSIWYG toolbar.

![A screenshot of the HTML input in the Data Editor shows a text field and a WYSIWYG toolbar.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-HTML-Input.webp)

### Markdown

The Markdown Rich Text input provides an editing interface for Markdown markup content.

You can edit the value of an Markdown input by typing in the text area, and apply styles to your text using tools in the WYSIWYG toolbar.

![A screenshot of the Markdown input in the Data Editor shows a text field and a WYSIWYG toolbar.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Markdown-Input.webp)

## Rich Text input appearance and behavior

You can customize the label, comment, documentation link, and context box for all inputs regardless of type.

![A screenshot of the Markdown Input in the Data Editor with a Context Box underneath the text area.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Markdown-Input-With-Context.webp)

Depending on how your developer configured the input, your Rich Text input may have different options in the WYSIWYG toolbar, a different height text area, or allow you to resize the text area.

### Input validation

Your Rich Text input may have input validation, which requires the input value to meet predefined criteria before you can save your changes. CloudCannon will warn you if your input value is invalid and provide directions on how to fix it.

CloudCannon will show a red `*` next to the name of your Rich Text input if a value is required.

![A screenshot of the Markdown input in the Data Editor shows that no value is causing an input validation error.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Markdown-Input-Required.webp)

If you enter a value under the minimum or over the maximum character count, CloudCannon will display an error message in red text under the input field.

![A screenshot of the Markdown input in the Data Editor shows that the value does not meet maximum length requirements.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Markdown-Input-Max-Length.webp)

If your developer has configured a pattern for your input value, CloudCannon will warn you when the value does not match the pattern. CloudCannon will show any error messages underneath the text area in red.

![A screenshot of the Markdown Input in the Data Editor shows an error message as the value does not match the configured pattern.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Markdown-Input-Pattern.webp)

For more information on configuration options, valid input values, and unconfigured input behavior, please read our developer documentation on [configuring a Rich Text input](/documentation/developer-articles/configure-a-rich-text-input/) .

## Misconfigured Rich Text inputs

You will see an orange warning box if your Rich Text input is misconfigured.

![A screenshot of a misconfigured Markdown input in the Data Editor shows an orange warning box.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Markdown-Input-Misconfigured.webp)

Rich Text inputs are misconfigured if:

- The value is not a string.

For more information on how to fix a misconfigured Rich Text input, please read our developer documentation on [configuring a Rich Text input](/documentation/developer-articles/configure-a-rich-text-input/).


---

---
title: What is a Select input?
description: Learn about Select inputs for editing structured data, including how they work in CloudCannon.
url: https://cloudcannon.com/documentation/user-articles/what-is-a-select-input/
content_type: user article
last_modified: 2026-03-29
---

Select inputs are editing interfaces for selecting values from predefined lists. You can use these inputs in the Data Editor, Content Editor, or Visual Editor to edit structured data in data files or front matter.

There are four types of Select inputs:

- Select
- Multiselect
- Choice
- Multichoice

## Select input types

### Select

The Select input provides an editing interface for data with multiple predefined options. This input has the same function as a Choice input but a different appearance.

Select inputs only allow one value.

You can edit the value of a Select input by clicking on the text field and selecting an option from the dropdown menu. Alternatively, you can type into the text field to filter the options in the dropdown menu.

![A screenshot of the Select Input in the Data Editor shows a text field and a dropdown menu.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Select-Input-Dropdown-Open.webp)

### Multiselect

The Multiselect input provides an editing interface for data with multiple predefined options. This input has the same function as a Multichoice input but a different appearance.

Multiselect inputs allow several values.

You can edit the value of a Multiselect input by clicking on the text field and selecting an option from the dropdown menu. Alternatively, you can type into the text field to filter the options in the dropdown menu.

![A screenshot of the Multiselect Input in the Data Editor shows a text field and a dropdown menu.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Multiselect-Input-Dropdown-Open.webp)

### Choice

The Choice input provides an editing interface for data with multiple predefined options.  This input has the same function as a Select input but a different appearance.

Choice inputs only allow one value.

You can edit the value of a Choice input by clicking the button for the value you want.

![A screenshot of the Choice Input in the Data Editor shows three buttons.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Choice-Input.webp)

### Multichoice

The Multichoice input provides an editing interface for data with multiple predefined options. This input has the same function as a Multiselect input but a different appearance.

Multichoice inputs allow several values.

You can edit the value of a Multichoice input by clicking the button for each value you want.

![A screenshot of the Multichoice Input in the Data Editor shows three buttons.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Multichoice-Input.webp)

## Select input appearance and behavior

You can customize the label, comment, documentation link, and context box for all inputs regardless of type.

![A screenshot of the Select Input in the Data Editor with a Context Box underneath the text area.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Multiselect-Input-With-Context.webp)

Depending on how your developer configured the input, your Select inputs may allow you to create new values.

Depending on how your developer configured the input, your Choice, Multichoice, and Multiselect inputs may have a custom preview appearance for Cards and buttons, including the text, subtext, icon, icon color, icon background color, or image.

![A screenshot of the Choice Input in the Data Editor shows an icon, icon color, and subtext.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Choice-Input-Preview.webp)

![A screenshot of the Multiselect Input in the Data Editor shows an icon, icon color, and subtext.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Multiselect-Input-Preview.webp)

### Populating a Select input

All Select inputs need a method for defining the list of available value options. Depending on how your developer has configured the input, the value options for your Select input will come from one of three places: a fixed data set, a [Collection](/documentation/user-articles/what-is-a-collection/), or a data file.

If your Select input uses a fixed data set, these options are probably defined in the [CloudCannon Configuration File](/documentation/developer-articles/what-is-the-cloudcannon-configuration-file/) or somewhere in the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/). Your developer may use a fixed data set when the value options for a Select input do not change often, or they do not want non-technical users updating the list of available options.

If your Select input uses a Collection, you can edit the list of available value options by adding or removing files from the Collection to which your Select Input is connected. Select Inputs connected to Collections are great for referencing other pages on your website.

If your Select input uses a data file, you can edit the list of available value options by changing the content of the data file to which your Select input is connected.

For more information, please read our developer documentation on [populating a Select input](/documentation/developer-articles/populate-a-select-input/).

### Input validation

Your Select inputs may have input validation, which requires the input value to meet predefined criteria before you can save your changes. CloudCannon will warn you if your input value is invalid and provide directions on how to fix it.

CloudCannon will show a red `*` next to the name of your Text input if a value is required.

![A screenshot of the Select input in the Data Editor shows that no value is causing an input validation error.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Select-Input-Required.webp)

If you select a number of options under the minimum or over the maximum item number in a Multiselect or Multichoice input, CloudCannon will display an error message in red text under the input field.

![A screenshot of the Multichoice Input in the Data Editor shows an error message as the value contains too many items.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Multichoice-Input-Max-Items.webp)

If your Select input allows you to create new values and you enter a value under the minimum or over the maximum character count, CloudCannon will display an error message in red text under the input field.

![A screenshot of the Select Input in the Data Editor shows an error message as the value is too many characters.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Select-Input-Max-Length.webp)

For more information on configuration options, valid input values, and unconfigured input behavior, please read our developer documentation on [configuring a Select input](/documentation/developer-articles/configure-a-select-input/) .

## Misconfigured Select inputs

You will see an orange warning box if your Select input is misconfigured.

![A screenshot of a misconfigured Choice input in the Data Editor shows an orange warning box.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Choice-Input-Misconfigured.webp)

Select inputs are misconfigured if:

- The value of a Select or Choice input is not a string.
- The value of a Multiselect or Multichoice input is not an array of strings.

For more information on how to fix a misconfigured Select input, please read our developer documentation on [configuring a Select input](/documentation/developer-articles/configure-a-select-input/).


---

---
title: What is a team member?
description: Learn about team members in CloudCannon and what they can do for your Organization.
url: https://cloudcannon.com/documentation/user-articles/what-is-a-team-member/
content_type: user article
last_modified: 2026-04-11
---

Team members are people you have invited to your [Organization](/documentation/user-articles/what-is-an-organization/). Your team members will help you edit and review your content, maintain your Sites, and manage your Organization. Each team member has their own CloudCannon account and an individual history of all the changes they have made to your Sites. When you [invite a team member to your Organization](/documentation/user-articles/add-a-team-member-to-your-organization/), CloudCannon will ask you to assign them to a [Permission Group](/documentation/user-articles/what-are-permission-groups/).

In CloudCannon, permissions control what actions your team members can perform within your Organization. The Permission Groups a team member belongs to determine their permissions. Each Permission Group contains a set of permissions that apply to all the members of that Group. Every team member in your Organization must be a member of at least one Permission Group.

The maximum number of team members allowed per Organization will depend on your [pricing plan](/pricing/). If you need to exceed this number, you can pay to add extra users to your Organization.

> If you want to give someone permission to access an individual Site without making them a member of your Organization, you can use Site Sharing or Client Sharing. For more information, read our documentation on [Site Sharing](/documentation/user-articles/share-a-site-with-site-sharing/) and [Client Sharing](/documentation/user-articles/what-is-client-sharing/).


---

---
title: What is a Testing Domain?
description: Learn about the free .cloudvent.net Testing Domain.
url: https://cloudcannon.com/documentation/user-articles/what-is-a-testing-domain/
content_type: user article
last_modified: 2026-02-10
---

A Testing Domain is a free *.cloudvent.net* URL that CloudCannon assigns to every Site. Each Testing Domain uses a randomly generated adjective and noun separated by a hyphen (i.e., [grey-grouse.cloudvent.net](https://grey-grouse.cloudvent.net/) or [brave-submarine.cloudvent.net](https://brave-submarine.cloudvent.net/)).

Testing Domains are useful for seeing your content live after a successful [Site build](/documentation/developer-articles/what-is-a-site-build/). If you use a [publishing workflow](/documentation/developer-guides/staging-workflow-guide/), your Testing Domain will allow you to see the content for each branch on its own domain.

You can [view your Testing Domain](/documentation/user-articles/view-your-testing-domain/) any time after your first successful Site build.

![A screenshot of the Site Header shows a link to the Testing Domain, which appears after your first successful Site build.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Header-Tools-Post-Build.webp)

> To stop serving content on your Testing Domain, you can [set a password](/documentation/developer-articles/enable-password-authentication/) to prevent unauthorized visitors, enable [Headless Mode](/documentation/developer-articles/what-is-headless-mode/), or contact our friendly [support team](/support/).

You can use your CloudCannon Testing Domain as your primary domain; however, we don't recommend doing this for two reasons.

One, you cannot change the automatically generated domain name without creating a new Site on CloudCannon. The automatically generated domain may not be right for you or your Site. You can generate a new one by creating a new Site with the same files, but this can be inefficient.

Two, by default, CloudCannon automatically de-indexes Testing Domains so that they do not appear in search engines. CloudCannon does this by serving a *robots.txt* file on all Testing Domains.

File: `robots.txt`

```

User-agent: *
Disallow: /
noindex: /

```

## Custom Testing Domains

> **This feature is available on specific plans.** Custom Testing Domains are only available on our [Team and Enterprise plans](/pricing/) and for members of our [Partner Program](/partner-program/).

Custom Testing Domain lets you choose the domain name for your `.cloudvent.net` URL. Choosing your Testing Domain improves your branding if you are sharing the URL outside of your Organization (e.g., sending a test Site to a client).

For access to this feature, please contact our friendly [support team](/support/). We'll set you up with a unique handle for your Organization. This handle will become the suffix for all Testing Domains (e.g., `prefix-company-name.cloudvent.net`).

Whenever you create a new Site, the *Create a Site* page will ask you to enter a unique prefix to prepend to your custom Testing Domain.

![The Site creation form shows an input field for Testing Domain Prefix, and shows that it will be prepended to '-company-name.cloudvent.net'.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Custom-Testing-Domain-Prefix.webp)

Take care when adding a custom Testing Domain to a new Site. Each full domain can only be used once, so you will never be able repeat that combination of "prefix" and "suffix".


---

---
title: What is a Text input?
description: Learn about Text inputs for editing structured data, including how they work in CloudCannon.
url: https://cloudcannon.com/documentation/user-articles/what-is-a-text-input/
content_type: user article
last_modified: 2026-03-29
---

A Text input is an editing interface for plain text content. You can use this input in the Data Editor, Content Editor, or Visual Editor to edit structured data in data files or front matter.

There are three types of Text input:

- Text
- Textarea
- Email

> Are you looking for [What is a Rich Text input?](/documentation/user-articles/what-is-a-rich-text-input/)
> 
> Text and Rich Text inputs are similar, except Rich Text inputs are designed for markup text content and contain a WYSIWYG toolbar.

## Text input types

### Text

The Text input provides a simple editing interface for plain text.

You can edit the value of an Text input by typing in the text area.

![A screenshot of the Text Input in the Data Editor shows a text field.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Text-Input.webp)

### Textarea

The Textarea input provides an editing interface for plain text.

You can edit the value of an Textarea input by typing in the text area, and new lines with the *Enter* key, and resize the text area.

![A screenshot of the Text Input in the Data Editor shows a multiline text field.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Textarea-Input.webp)

### Email

The Email input provides an editing interface for plain text with an email icon for context.

You can edit the value of an Email input by typing in the text area.

![A screenshot of the Email Input in the Data Editor shows a text field and email icon.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Email-Input.webp)

## Text input appearance and behavior

You can customize the label, comment, documentation link, and context box for all inputs regardless of type.

![A screenshot of the Text Input in the Data Editor with a Context Box underneath the text area.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Text-Input-With-Context.webp)

Depending on how your developer configured the input, your Textarea input may have a character counter in the top right of the text area.

![A screenshot of the Text Input in the Data Editor shows a character counter in the top right of the text field.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Textarea-Input-Show-Count.webp)

### Input validation

Your Text input may have input validation, which requires the input value to meet predefined criteria before you can save your changes. CloudCannon will warn you if your input value is invalid and provide directions on how to fix it.

CloudCannon will show a red `*` next to the name of your Text input if a value is required.

![A screenshot of the Text input in the Data Editor shows that no value is causing an input validation error.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Text-Input-Required.webp)

If you enter a value under the minimum or over the maximum character count, CloudCannon will display an error message in red text under the input field.

![A screenshot of the Text Input in the Data Editor shows an error message as the value is too many characters.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Text-Input-Max-Length.webp)

If your developer has configured a pattern for your input value, CloudCannon will warn you when the value does not match the pattern. CloudCannon will show any error messages underneath the text area in red.

![A screenshot of the Text Input in the Data Editor shows an error message as the value does not match the configured pattern.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Text-Input-Pattern.webp)

For more information on configuration options, valid input values, and unconfigured input behavior, please read our developer documentation on [configuring a Text input](/documentation/developer-articles/configure-a-text-input/) .

## Misconfigured Text inputs

You will see an orange warning box if your Text input is misconfigured.

![A screenshot of a misconfigured Text input in the Data Editor shows an orange warning box.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Text-Input-Misconfigured.webp)

Text inputs are misconfigured if:

- The value is not a string.

For more information on how to fix a misconfigured Text input, please read our developer documentation on [configuring a Text input](/documentation/developer-articles/configure-a-text-input/).


---

---
title: What is a URL input?
description: Learn about URL inputs for editing structured data, including how they work in CloudCannon.
url: https://cloudcannon.com/documentation/user-articles/what-is-a-url-input/
content_type: user article
last_modified: 2026-03-29
---

A URL input is an editing interface for relative, absolute, and fully qualified URLs. You can use this input in the Data Editor, Content Editor, or Visual Editor to edit structured data in data files or front matter.

There is only one type of URL input:

- URL

## URL input types

### URL

The URL input provides an editing interface for relative, absolute, and fully qualified URLs.

You can edit the value of a URL input by typing in the text field. To clear the selected file, you can click the *Clear* button at the top right of the input.

![A screenshot of an empty URL Input in the Data Editor shows a text field, a plus button, and a drag-and-drop area.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-URL-Input-Empty.webp)

You can link to existing files in your repository or DAM, pages on your website, or email addresses, using the dropdown menu from the *Add URL* button at the top right. You can also upload a file to your repository or [DAM](/documentation/developer-articles/integrating-your-dam-with-cloudcannon/) by selecting the *Upload a new file* option.

![A screenshot of the Add URL dropdown on a URL Input shows the several options.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-URL-Input-Dropdown-Open.webp)

When you link to an external URL, the URL input will display the title, description, and image for the URL.

![A screenshot of the URL Input in the Data Editor shows an external URL value with a preview of the URL image, title, and subtitle.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-URL-Input.webp)

When you link to a relative URL (i.e., a page on your website), the URL input will show a preview screenshot of the page's output URL, the title, and the output path.

![A screenshot of the URL Input in the Data Editor shows an local URL value with a preview of the URL screenshot, title, and output path.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-URL-Input-Local-URL.webp)

## URL input appearance and behavior

You can customize the label, comment, documentation link, and context box for all inputs regardless of type.

![A screenshot of the URL Input in the Data Editor with a Context Box underneath the text area.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-URL-Input-With-Context.webp)

Depending on how your developer configured the input, your URL input may have different options in the *Add URL* button dropdown menu.

### Input validation

Your URL input may also have input validation, which requires the value to match predefined criteria before you can save your changes.

CloudCannon will show a red `*` next to the name of your URL input if a value is required.

![A screenshot of the URL input in the Data Editor shows that no value is causing an input validation error.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-URL-Input-Required.webp)

If you enter a value under the minimum or over the maximum character count, CloudCannon will display an error message in red text under the input field.

![A screenshot of the URL input in the Data Editor shows that the value does not meet maximum length requirements.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-URL-Input-Max-Length.webp)

If you select a file that exceeds the maximum file size limit, CloudCannon will display an error message in red text under the input field.

![A screenshot of the URL input in the Data Editor shows that the uploaded file does not meet file size requirements.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-URL-Input-Max-File-Size.webp)

If your developer has configured a pattern for your input value (such as specific file extensions), CloudCannon will warn you when the value does not match the pattern. CloudCannon will show any error messages underneath the input field in red.

![A screenshot of the URL Input in the Data Editor shows an error message as the value does not match the configured pattern.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-URL-Input-Pattern.webp)

For more information on configuration options, valid input values, and unconfigured input behavior, please read our developer documentation on [configuring a URL input](/documentation/developer-articles/configure-a-url-input/) .

## Misconfigured URL inputs

You will see an orange warning box if your URL input is misconfigured.

![A screenshot of a misconfigured URL input in the Data Editor shows an orange warning box.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-URL-Input-Misconfigured.webp)

URL inputs are misconfigured if:

- The value is not a string.

For more information on how to fix a misconfigured URL input, please read our developer documentation on [configuring a URL input](/documentation/developer-articles/configure-a-url-input/).


---

---
title: What is an Array input?
description: Learn about Array inputs for editing structured data, including how they work in CloudCannon.
url: https://cloudcannon.com/documentation/user-articles/what-is-an-array-input/
content_type: user article
last_modified: 2026-03-29
---

An Array input is an editing interface for lists of inputs or input groups. You can use this input in the Data Editor, Content Editor, or Visual Editor to edit structured data in data files or front matter. Array inputs can contain nested inputs of any type, including other Arrays and Objects. There is no limit to how many nested layers you can create within an Array.

There is only one type of Array input:

- Array

## Array input types

### Array

The Array input provides a user interface for lists of inputs or input groups. Each item in an Array is sometimes called an "entry". Entries in an Array can be a single value, an input, or an Object containing several inputs. Array inputs appear as a series of cards in the Data Editor or sidebar of the Visual or Content Editor. For entries that use a key name (i.e., Objects, Arrays, or single inputs), the card will preview some of the content within the key. This can include images, strings, and key names. You can configure the preview settings for these cards.

![A screenshot of the Array Input in the Data Editor shows a two preview cards in a list.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Array-Input.webp)

Simpler entries with no key name, such as text, number, or boolean values, do not use cards. Instead, they appear as editable inline fields.

![A screenshot of the Array Input in the Data Editor shows a several inline cards in a list.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Array-Input-Inline.webp)

Array inputs can contain a mixture of inline fields and cards simultaneously.

You can reorder, clone, add, and delete new entries in the list using the *Context Menu*. You can also add new entries using the *+ Add* button below the Array — the text on this button will differ depending on the key name of your Array input.

![A screenshot of the Context Menu on an Array Input shows several entry options.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Array-Input-Dropdown-Open.webp)

When you click on a card in the Array, it will open to show the nested inputs within that Array entry. The *Back* button at the top of the entry will return you to the parent scope.

![A screenshot of the nested content within an Array Input in the Data Editor.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Array-Input-Open.webp)

Depending on how your developer has configured the Array input, clicking the *+ Add* button will either clone the last entry in the Array, allow you to choose from predefined [Structures](/documentation/developer-articles/what-is-a-structure/), or add an entry that matches the Entry Input Type.

## Array input appearance and behavior

You can customize the label, comment, documentation link, and context box for all inputs regardless of type.

![A screenshot of the Array Input in the Data Editor with a Context Box underneath the text area.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Array-Input-Context.webp)

Depending on how your developer configured the input, your Array input may have a custom preview appearance for entry Cards, including the text, subtext, icon, icon color, icon background color, or image.

![A screenshot of the Array Input in the Data Editor shows an icon, icon color, and subtext.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Array-Input-Preview.webp)

### Populating an Array input

Array inputs need a method for populating new entries. Depending on how your developer has configured the input, when you click the *+ Add* button to add a new entry, CloudCannon will populate new entries in one of three ways: cloning another Array item, using a [Structure](/documentation/developer-articles/what-is-a-structure/), or using an entry Input type.

If your Array input uses the cloning method, clicking the *+ Add* button will clone the format of the most recent entry in the Array and remove the data content. This method is the simplest and allows you to maintain the format of your Array entries, but has some drawbacks. One, you can't use multiple formats for different entries and, two, your input needs at least one entry to clone.

If your Array input uses a Structure, you can select a predefined template to populate a new entry. This method allows you to have many entry templates that are as complex as you require.

If your Array input uses an entry Input type, clicking the *+ Add* button will add an Input of a predefined type as your new entry. This method is suitable for simple Arrays where each entry should be the same Input type.

For more information, please read our developer documentation on [populating an Array input](/documentation/developer-articles/populate-an-array-input/).

### Input validation

Your Array inputs may have input validation, which requires the input value to meet predefined criteria before you can save your changes. CloudCannon will warn you if your input value is invalid and provide directions on how to fix it.

CloudCannon will show a red `*` next to the name of your Array inputs if a value is required.

![A screenshot of the Array input in the Data Editor shows that no value is causing an input validation error.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Array-Input-Required.webp)

CloudCannon will warn you that errors need attention when an input nested within an Array fails input validation.

![A screenshot of the Array input in the Data Editor shows that one or more nested inputs have a validation error.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Array-Input-Invalid.webp)

![A screenshot of the invalid nested inputs within an Array input in the Data Editor.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Array-Input-Invalid-Children.webp)

If you select a number of options under the minimum or over the maximum item number, CloudCannon will display an error message in red text under the input field.

![A screenshot of the Array Input in the Data Editor shows an error message as the value contains too few items.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Array-Input-Min-Items.webp)

If your input requires unique values, CloudCannon will warn you when two or more values are not unique.

![A screenshot of the Array Input in the Data Editor shows an error message as there are non-unique values.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Array-Input-Unique.webp)

For more information on configuration options, valid input values, and unconfigured input behavior, please read our developer documentation on [configuring an Array input](/documentation/developer-articles/configure-an-array-input/).

## Misconfigured Array inputs

You will see an orange warning box if your Array input is misconfigured.

![A screenshot of a misconfigured Array input in the Data Editor shows an orange warning box.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Array-Input-Misconfigured.webp)

Array inputs are misconfigured if:

- The value is not an array of strings, numbers, booleans, or keys.
- There is no value, and you have not configured a Structure or entry input type to populate the Array.

For more information on how to fix a misconfigured Array input, please read our developer documentation on [configuring an Object input](/documentation/developer-articles/configure-an-array-input/).


---

---
title: What is an Object input?
description: Learn about Object inputs for editing structured data, including how they work in CloudCannon.
url: https://cloudcannon.com/documentation/user-articles/what-is-an-object-input/
content_type: user article
last_modified: 2026-03-29
---

An Object input is an editing interface for structured data. You can use this input in the Data Editor, Content Editor, or Visual Editor to edit structured data in data files or front matter.

Object inputs can contain nested inputs of any type, including other Objects and Arrays. There is no limit to how many nested layers you can create within an Object. Grouping inputs under an Object is useful for organizing your data or hiding complicated or infrequently edited data.

Unlike other input types, the Object input has one type but three subtypes:

- Object
- Tabbed Object
- Mutable Object

## Object input subtypes

### Object

The Object input provides a user interface for a group of inputs.

Object inputs appear as [Cards](/documentation/developer-articles/configure-your-card-previews/) in the Data Editor or sidebar of the Visual or Content Editor, previewing some of the content they contain.

![A screenshot of the Object Input in the Data Editor shows a card previewing the nested title, description, and image.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Object-Input-Closed.webp)

When you click on the Object card, it will open to show the nested inputs within that Object. The *Back* button at the top of the input will return you to the parent scope.

![A screenshot of the nested content within an Object Input in the Data Editor.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Object-Input-Open.webp)

### Tabbed Object

The Tabbed Object input provides a user interface for a group of inputs with two or more layers of nested keys. Tabbed Objects are useful if you want to display Objects with two or more layers of nested keys in a more intuitive manner.

The Object input appears as a Card in the Data Editor or sidebar of the Visual or Content Editor.

![A screenshot of the Tabbed Object Input in the Data Editor shows a card previewing the nested title, description, and image.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Tabbed-Object-Input-Closed.webp)

Clicking on the Object Card shows each first-level nested key as a tab at the top of the input, as well as all nested inputs within your first-level keys.

![A screenshot of the nested content within a Tabbed Object Input in the Data Editor.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Tabbed-Object-Input-First-Tab.webp)

![A screenshot of the nested content within a Tabbed Object Input in the Data Editor.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Tabbed-Object-Input-Second-Tab.webp)

### Mutable Object

The Mutable Object input provides a user interface for a group of inputs. Rather than clicking on the Object input card to view the nested keys, such as in an Object or Tabbed Object input, all the nested keys in a Mutable Object are visible at the top scope of the input.

You can edit the value of a Mutable Object input by adding, deleting, cloning, renaming, and reordering nested keys. Mutable Objects function similarly to [Array inputs](/documentation/user-articles/what-is-an-array-input/), except they do not allow multiple nested keys with the same name.

## Object input appearance and behavior

You can customize the label, comment, documentation link, and context box for all inputs regardless of type.

![A screenshot of the Object Input in the Data Editor with a Context Box underneath the card.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Object-Input-With-Context.webp)

Depending on how your developer configured the input, your Object input may have groups for nested inputs, including headings, comments, and links, or a custom preview appearance for Object Cards.

![A screenshot of the nested content within an Object Input in the Data Editor shows groups, heading, documentation links, and comments.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Object-Input-Groups.webp)

### Input validation

Your Object input may also have input validation, which requires the value to match predefined criteria before you can save your changes.

CloudCannon will show a red `*` next to the name of your Object input if a value is required.

![A screenshot of the Object input in the Data Editor shows that no value is causing an input validation error.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Object-Input-Required.webp)

CloudCannon will warn you that errors need attention when an input nested within an Object fails input validation.

![A screenshot of the Object input in the Data Editor shows that one or more nested inputs have a validation error.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Object-Input-Invalid.webp)

![A screenshot of the invalid nested inputs within an Object input in the Data Editor.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Object-Input-Invalid-Children.webp)

For more information on configuration options, valid input values, and unconfigured input behavior, please read our developer documentation on [configuring an Object input](/documentation/developer-articles/configure-an-object-input/) .

## Misconfigured Object inputs

You will see an orange warning box if your Object input is misconfigured.

![A screenshot of a misconfigured Object input in the Data Editor shows an orange warning box.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Object-Input-Misconfigured.webp)

Object inputs are misconfigured if:

- The value is not a nested key(s).

For more information on how to fix a misconfigured Object input, please read our developer documentation on [configuring an Object input](/documentation/developer-articles/configure-an-object-input/).


---

---
title: What is an Organization?
description: Organizations help you organize your team, Sites, and resources in one place.
url: https://cloudcannon.com/documentation/user-articles/what-is-an-organization/
content_type: user article
last_modified: 2026-02-24
---

Organizations help you organize your team, Sites, and resources in one place. It allows a team to be defined and permissions to be granted at different levels.

You can create and be a part of multiple Organizations.


---

---
title: What is Client Sharing?
description: Learn how to share a site with your Clients without them needing to create a CloudCannon account.
url: https://cloudcannon.com/documentation/user-articles/what-is-client-sharing/
content_type: user article
last_modified: 2026-04-07
---

Client Sharing allows you to invite someone from outside your [Organization](/documentation/user-articles/what-is-an-organization/) (called a Client) to view, edit, and publish content for a specific Site. Clients do not need to have a CloudCannon account. Instead, they log into CloudCannon using a site-specific password.

Clients will log in using a [password you set for your Site](/documentation/developer-articles/turn-on-client-sharing-for-a-site/) and a dedicated Client Login Page. By default, the URL for the Login Page is the Site domain with the suffix "/update" (e.g., www.example.com/update). CloudCannon will use your [.cloudvent.net test domain](/documentation/user-articles/what-is-a-testing-domain/) if your Site does not have a custom domain. If you want to change the URL subpath, you can [configure the URL for the Login Page](/documentation/developer-articles/configure-the-client-login-page/).

![A screenshot of the Client Login page with a field for the site-specific password and a Sign In button.](/assets/external_screenshots/client-login-page.png)

> **Client Sharing and Headless Mode**
> 
> [Headless Mode](/documentation/developer-articles/what-is-headless-mode/) disables building and hosting for your Site, so [Testing Domains](/documentation/user-articles/what-is-a-testing-domain/) are not available. CloudCannon will forward clients trying to login to a headless Site using the .cloudvent.net link to the appropriate app.cloudcannon.com/update link.

Once a Client has logged in to your Site, they can access a simple version of the CloudCannon Site Dashboard. You can [configure the links in the *Site Navigation* of the Client Dashboard](/documentation/developer-articles/configure-the-client-dashboard-support-links/) to support your Clients.

![A screenshot of the Client Sharing Site Dashboard shows a simplified navigation and support links.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Client-Sharing-Dashboard-Summary-Tab.webp)

Clients count towards the number of team members in your Organization. Your Organization's maximum number of team members will depend on your [pricing plan](/pricing/).

> Although an unlimited number of people can use a Client Sharing password to log in to a Site, we do not recommend giving a Client Sharing password to multiple people. If multiple people share a password, you cannot determine which Client was responsible for which changes.

There is one [Permission Group](/documentation/user-articles/what-are-permission-groups/) per Site for Client Sharing, scoped to the Site you want to share.

[Team and Enterprise customers](/pricing/) can customize the permissions in the Client Sharing Permission Group for each Site.

You can see a list of all Sites with Client Sharing enabled on the *Client Shares* page under *Organization Settings*. To manage the *Client Sharing* settings for a specific card, click on the Site card or navigate to the *Client Sharing* page in your *Site Settings*.

![A screenshot of the Client Shares page shows one Site with Client Sharing enabled.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Client-Shares-Page.webp)


---

---
title: What is multi-factor authentication?
description: Learn about multi-factor authentication and how it improves the security of your CloudCannon account.
url: https://cloudcannon.com/documentation/user-articles/what-is-multi-factor-authentication/
content_type: user article
last_modified: 2026-04-11
---

Multi-factor authentication (MFA) provides an extra layer of security to your CloudCannon account. By enabling MFA, you can require someone logging into your CloudCannon account to provide multiple forms of identity authentication before they can access your account.

Logging in with MFA enabled relies on something you know (your account password) and something you have (e.g., a device with your authentication app, a secure token, a biometric). This reduces the chances of someone else gaining access to your CloudCannon account.

## Third-party authentication apps

[Multi-factor authentication in CloudCannon](/documentation/developer-articles/enable-multi-factor-authentication/) uses a third-party authentication app. Authentication apps generate one-time passcodes, which you can use to log in to CloudCannon. These passcodes regenerate often (normally every thirty seconds), meaning that someone trying to log in to your account would need the device with your authentication app to be successful.

Common authentication apps include:

- 1Password
- Authy
- Microsoft Authenticator

You should do your own research on these third-party apps and choose the one that is best for you.


---

---
title: What is the Content Editor?
description: Learn about the Content Editor, a rich text interface for editing content-heavy files.
url: https://cloudcannon.com/documentation/user-articles/what-is-the-content-editor/
content_type: user article
last_modified: 2026-03-29
---

The Content Editor is a rich text editor for clean, distraction-free editing of content-heavy files. This editing interface is most useful for Markdown and MDX files, with or without front matter.

![A screenshot of the Content Editor, an editing interface for content-heavy markup files.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor.webp)

> Depending on your SSG and site configuration, you may not have access to the Content Editor for all files. An editing interface may not be available because:
> 
> - The file you want to open is not a markup file (e.g. YAML, TOML, JSON, CSS, etc.).
> - A Developer on your team has [specified which editing interfaces are enabled](/documentation/developer-articles/set-a-default-editing-interface/) for a particular [collection](/documentation/user-articles/what-is-a-collection/) or [schema.](/documentation/developer-articles/what-is-a-schema/)

## Content Editor features

The Content Editor might remind you of other rich text editors, like Google Docs or Microsoft Word. Writing the next piece of content for your website, and adding images, links, and other content blocks is easy. The Content Editor is a WYSIWYG editor, meaning that the way you format the content in the editor will resemble the way it will look on your website page (WYSIWYG is an acronym for What-You-See-Is-What-You-Get).

For more information about the *Editing interface navigation* and the *Context Menu* at the top of the Content Editor, read our documentation on [editing your files](/documentation/user-articles/edit-your-files/).

### The WYSIWYG toolbar

![A closeup of the WYSIWYG toolbar, including tools for formatting rich text.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-WYSIWYG-Toolbar.webp)

The *WYSIWYG toolbar* is found at the top of all rich text editors in CloudCannon (i.e., the Content Editor and [rich text inputs](/documentation/user-articles/what-is-a-rich-text-input/)). This toolbar is populated with tools to help you format your content. This might include adding images, links, and lists, changing the alignment of your text, or simple tools such as bolding, italicizing, or underlining text.

To use these tools, click to place your cursor in the content area of the editor (or, in some cases, highlight your existing text) and then click the icon for the tool you want to use. The number of tools available in your *WSYIWYG toolbar* will depend on how your site is configured.

For more information on how to customize your *WYSIWYG toolbar*, read our documentation on [configuring your rich text editors](/documentation/developer-articles/configure-your-rich-text-editors/).

### The sidebar

![A closeup of the Content Editor sidebar, showing the front matter fields of a blog file.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Sidebar.webp)

The Content Editor sidebar allows you to edit the front matter content of your file. Front matter fields contain data that does not appear in the main body of the content.

For example, a blog post might have the content of the blog in the main body of the file, and fields for title, author, and date in the front matter. You or your developer can use front matter data to populate other areas of your webpage, outside of the main body of content.

You can open or close the sidebar using the arrow button on the right of the panel.

> The sidebar in the [Visual](/documentation/user-articles/what-is-the-visual-editor/) and Content Editor shows the same information as the [Data Editor](/documentation/user-articles/what-is-the-data-editor/).

For more information on how to customize your front matter fields, read our documentation on [inputs](/documentation/user-articles/what-are-inputs/).

### Snippets

![The Content Editor shows a YouTube snippet in the rich text content with its data panel open for editing.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-YouTube-Snippet-Edit-Panel.webp)

A [snippet](/documentation/developer-articles/what-is-a-snippet/) is a structured component that complements your rich text content. Snippets can accomplish a variety of tasks, such as adding a video link, a highlighted section of text, or a code block. Adding snippets to your content is a great way to build complex, rich text documents without the need for team members to touch the underlying code.

Once you have configured your snippets, you can add them to your rich text files using the *Insert snippet* tool in the *WYSIWYG toolbar*. Snippets appear as inline or paragraph-level blocks in the Content Editor.

For more information on snippets, please read our documentation on [snippets](/documentation/developer-articles/what-is-a-snippet/).


---

---
title: What is the Data Editor?
description: Learn about the Data Editor, an editing interface for structured data or front matter in your markup files.
url: https://cloudcannon.com/documentation/user-articles/what-is-the-data-editor/
content_type: user article
last_modified: 2026-03-31
---

The Data Editor offers a simple way to manage structured data files and the front matter of markup files. The Data Editor is most useful for YAML, TOML, JSON, CSV, and TSV file types, and Markdown or MDX files with front matter.

This editing interface also doubles as the sidebar and data panels in the [Visual](/documentation/user-articles/what-is-the-visual-editor/) and [Content Editors](/documentation/user-articles/what-is-the-content-editor/).

![A screenshot of the Data Editor, an editing interface for structured data files and markup file front matter.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Data-Editor.webp)

> Depending on your SSG and site configuration, you may not have access to the Data Editor for all files. An editing interface may not be available because:
> 
> - The file you want to open does not contain structured data (e.g., Markdown or MDX files with no front matter).
> - A developer on your team has [specified which editing interfaces are enabled](/documentation/developer-articles/set-a-default-editing-interface/) for a particular [collection](/documentation/user-articles/what-is-a-collection/) or [schema.](/documentation/developer-articles/what-is-a-schema/)

### What is front matter?

Front matter is structured data that precedes the main content in a markup file (e.g., a Markdown or MDX file).

Front matter data contains information about the file. This information can range from simple data like file title and author to SEO information to custom variables created by you or your team. Front matter is useful for providing context to your file's content.

For most SSGs, front matter is stored at the top of a file between two sets of triple-dash characters (`---`), although this can vary.

## Data Editor features

The Data Editor is a simple interface for editing the values of your structured data through [inputs](/documentation/user-articles/what-are-inputs/). Each input in the Data Editor corresponds to a key in your front matter or data file, providing an editing interface for those values.

For example, you could use the Data Editor to edit:

- Array inputs in your site navigation file, updating the URLs of the pages you want to list.
- Image inputs in the front matter of your blog post, updating the thumbnail image.

For more information about the types of inputs available in CloudCannon, read our documentation on [inputs](/documentation/user-articles/what-are-inputs/).

> By default, you cannot add or delete inputs in the Data Editor. You can configure this functionality using [mutable objects](/documentation/user-articles/what-is-an-object-input/#mutable-object).

For more information about the *Editing interface navigation* and the *Context Menu* at the top of the Data Editor, read our documentation on [editing your files](/documentation/user-articles/edit-your-files/).

### The sidebar in the Visual or Content Editor

![A screenshot of the Content Editor, with the sidebar showing the front matter fields of a blog file.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor.webp)

You can edit the front matter and content of markup files in the same editing interface using the [Visual](/documentation/user-articles/what-is-the-visual-editor/) or [Content Editor](/documentation/user-articles/what-is-the-content-editor/). Data from the front matter of your file will appear in the editor sidebar. The sidebar is the same interface as the Data Editor, just smaller.

You can open or close the sidebar using the arrow button on the right of the panel.

### Data panels in the Visual or Content Editor

![A screenshot of the Visual Editor,  with the open data panel showing the inputs of a page component.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Visual-Editor-Data-Panel.webp)

Data panels appear in the Visual and Content Editors.

In the Visual Editor, you can edit page components using the data panels if you have [visual data bindings](/documentation/developer-articles/what-are-visual-data-bindings/) and [previews](/documentation/developer-articles/what-are-visual-data-previews/) configured. You can see your changes as you edit. CloudCannon will update the page in the Visual Editor each time you alter the input values in a data panel.

In the Content Editor, you can edit images and links using their data panels. The image data panel contains fields for alternate and title text, while the link data panel has fields for title and other attributes.

You can move the data panel around the screen by clicking and dragging the panel header.


---

---
title: What is the Project Browser?
description: Learn about the Projects Browser and the Project Sites Browser in CloudCannon.
url: https://cloudcannon.com/documentation/user-articles/what-is-the-project-browser/
content_type: user article
last_modified: 2026-03-11
---

> **Some features are only available on our [Team and Enterprise plans](/pricing/).**
> 
> Want to chat about whether this feature is right for you? Our support team is always [happy to hear from you](mailto:success@cloudcannon.com?subject=A%20question%20about%20Projects).

A **Project** is a way to group multiple **Sites** from the same **Git Repository**. CloudCannon provides several pages for working with *Projects*: the *Projects Browser* lists all your *Projects*, the *Project Sites Browser* shows the *Sites* within a single *Project*, and the *Publishing* and *Project Settings* tabs let you visualize and configure your *Project*.

## The Projects Browser

![A screenshot of the Projects Browser showing a list of Project cards.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Projects-Browser.webp)

The *Projects Browser* lists all the *Projects* in your *Organization*. You can access the *Projects Browser* by clicking the *Projects* link in the *App Sidebar*.

From the *Projects Browser*, you can:

- View all your *Projects* at a glance
- Sort and filter *Projects* by name, URL, or last synced date
- Click a *Project Card* to open the *Project Sites Browser*
- Create a new *Project* using the *Create a Project* button

## The Project Sites Browser

![A screenshot of the Project page showing the Sites tab with multiple Sites connected to different branches.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Project-Sites-Browser-With-Links.webp)

The *Project Sites Browser* is the main page for an individual *Project*. It shows all the *Sites* connected to your *Project* and provides access to the *Publishing* and *Project Settings* tabs.

For each *Site*, the *Project Sites Browser* shows:

- The *Site* name and branch name
- The domain or testing URL
- The build and sync status
- Which branch the *Site* publishes to (e.g., "publishes to main")

You can switch between card and list views, and use the *Create a Site* button to [add a new Site to your Project](/documentation/developer-articles/add-a-site-to-your-project/).

## The Publishing tab

![A screenshot of the Publishing tab showing the relationship between branch Sites and the main branch.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Project-Publishing-Tab.webp)

The *Publishing* tab on your *Project* page gives you a visual overview of how your *Sites* relate to each other. It displays a graph showing each *Site*, which branch it is connected to, and which branch it publishes to. This makes it easy to see the full publishing workflow at a glance.

This is especially helpful for *Projects* with multiple levels of branching, where it can be difficult to remember the publishing relationships between *Sites*.

For more information on configuring publishing behavior for individual *Sites*, please read our documentation on [connecting a Publish Branch](/documentation/developer-articles/connect-a-publish-branch/).

## The Project Settings tab

![A screenshot of the Project Settings tab showing the Details section with fields for Project Name, Display URL, Description, and Related Links.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Project-Settings-Details.webp)

The *Project Settings* tab allows you to manage your *Project* across four sections:

- **Details** — Update your *Project Name*, *Display URL*, *Description*, and *Related Links*.
- **Repository** — View or change the connected *Git Provider* and *Repository*, toggle *Allow all branching*, and [set the Main Branch](/documentation/developer-articles/set-the-main-branch-for-your-project/).
- **Branch Defaults** — Configure default settings for new branch *Sites*, including the publishing method, authentication, and permissions.
- **Danger** — Delete your *Project*. This does not delete the *Sites* within it.


---

---
title: What is the Site Header?
description: Learn about your Site Header in CloudCannon.
url: https://cloudcannon.com/documentation/user-articles/what-is-the-site-header/
content_type: user article
last_modified: 2026-02-27
---

At the top of your Site is your **Site Header** in gray. This UI element displays key information about your Site on the left, such as Site icon, name, branch, and project, and important tools on the right, including the *Avatar* list, **Testing Domain** link, **Configuration Mode switch**, and **Save button**.

![A screenshot of the Site Header shows the Site icon, name, branch, Avatar list, Testing Domain, and Save button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Header-Post-Build.webp)

Some of these sections may not appear depending on your *Site's* configuration.

## *Site Header* sections

### Site details

On the left of your *Site Header* are your *Site* details, including the *Site Icon*, *Site Name*, *Branch*, and *Project* (if configured).

The *Site Icon* and *Site Name* enable you to identify the site you have open and help you distinguish between sites in the *Sites Browser*. The *Branch* tells you which branch of your **Git repository** this *Site* is connected to.

If your *Site* is part of a **Project**, the *Branch* and *Project* name will become a link. Clicking on the *Project* name will open the *Project pop-up*, allowing you to navigate to your *Project* page easily. For more information about the *Projects*, please read our documentation on [Projects](/documentation/developer-articles/create-a-project/).

### The *Avatar list*

The first tool on the right side of your Site Header in the *Avatar list* displays the avatars for any [team members](/documentation/user-articles/what-is-a-team-member/) active on your *Site*. Clicking on an avatar will display a list of files they have open, with an eye icon indicating files they are viewing and a pencil icon indicating files they are editing.

### The *Testing Domain link*

If your *Site* has a successful [build](/documentation/developer-articles/what-is-a-site-build/), a link to your *Testing Domain* will appear in the *Site Header*. If you have a **Custom Domain** as well, the *Open URL dropdown* will appear instead, allowing you to choose which domain you want to open. For more information about hosting on a domain, please read our documentation on [Testing Domains](/documentation/user-articles/what-is-a-testing-domain/) and [Custom Domains](/documentation/developer-articles/what-is-a-custom-domain/).

### The *Configuration Mode switch*

If you want to customize the appearance and functionality of your Site, you can turn on *Configuration Mode* using the *Configuration Mode switch* in the *Site Header*. This will reveal purple *Edit Configuration buttons* that enable you to add content to your *CloudCannon Configuration File*. For more information, please read our documentation on [Configuration Mode](/documentation/developer-articles/what-is-configuration-mode/).

### The *Save* *button*

The *Save button* on the right of the *Site Header* allows you to save changes to your files. The *Save button* is also in the same place when you have any editing interface. For more information, please read our documentation on [Saving your Changes](/documentation/user-articles/save-your-changes/).


---

---
title: What is the Site Navigation?
description: Learn about your Site Navigation in CloudCannon.
url: https://cloudcannon.com/documentation/user-articles/what-is-the-site-navigation/
content_type: user article
last_modified: 2026-02-11
---

Site Navigation is one of the main UI elements on each Site in CloudCannon. It is located on the left of the *Site*, just in from the *App Sidebar*.

![A screenshot of the Site Navigation shows links to pages for managing your Site content.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Navigation.webp)

The primary purpose of your *Site Navigation* is to provide links to all the pages you'll need to manage your website content. If you have many navigation items, the *Site Navigation* is scrollable.

The *Site Navigation* will always have a link to your *Site Dashboard* at the top, your *Collections* in the middle, and links to *Developer* pages like *File Browser* and *Site Settings* at the bottom. Depending on your configuration, it can also show links to the *Publishing* page and any *Inboxes* connected to your *Site*.

## *Site Navigation* Sections

### *Dashboard*, *Publishing*, and *Inboxes*

![A screenshot of the Site Navigation shows links to the Dashboard, Publishing, and Inbox pages.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Navigation-Dashboard-Publishing-Inbox.webp)

At the top of your *Site Navigation* are links to your *Site Dashboard*, *Publishing* page, and *Inboxes* (if configured).

The *Site Dashboard* is the hub for key information about your *Site*. The *Dashboard* is broken down into several tabs, including *Summary*, *Activity*, *Syncs*, *Builds*, *Build Deploys*, and *Guides*. You can click on these tabs to navigate between them.

The *Publishing* page is where you will find information about your publishing workflow, if you have one configured (i.e., your *Site* is connected to a [Publish Branch](/documentation/user-articles/what-is-a-publish-branch/)). The *Publishing* page has several tabs: *Summary*, *Commits*, and *Changes*.

The *Inbox* page is where you will find all your visitor submissions from a CloudCannon form, if you have one configured. If you have multiple forms, each inbox will appear as a separate item in your *Site Navigation* under the *Inboxes* heading. For more information about *Inboxes*, please read our documentation on [forms](/documentation/developer-articles/what-is-a-form/).

### *Collections*

![A screenshot of the Site Navigation shows links to the Collections on this Site, organized into groups.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Navigation-Collections.webp)

In the middle of your *Site Navigation* are links to each *Collection* on your *Site*. *Collections* are groups of files you want to edit in CloudCannon, such as a folder of pages, blog posts, product descriptions, or data files. Clicking on one of these links in your *Site Navigation* will open the *Collection Browser* for that collection of files.

For more information about *Collections*, please read our documentation on [Collections](/documentation/user-articles/what-is-a-collection/) in general.

### *Developer*

> The *Developer* section of your *Site Navigation* is only visible to members of the Owners, Developers, or Technical Editors [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `site:source-editor` permission.

![A screenshot of the Site Navigation shows links to the File Browser and Site Settings.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Navigation-Developer.webp)

At the bottom of your *Site Navigation* are links to your *File Browser* and *Site Settings*. These links are under a pinned and collapsable *Developer* heading. These links are important for managing the *Site* itself, rather than its content.

The *File Browser* allows you to see all the website files CloudCannon has synced from your Git provider. You can browse, sort, and filter these files, as well as open them directly in the Source Editor. For more information about the *File Browser*, please read our documentation on the [File Browser](/documentation/user-articles/the-file-browser/).

The *Site Settings* page contains all the settings for your *Site*, including your builds, hosting, sharing, and more.


---

---
title: What is the Source Editor?
description: Learn about the Source Editor, an editing interface for in-browser code changes to your files.
url: https://cloudcannon.com/documentation/user-articles/what-is-the-source-editor/
content_type: user article
last_modified: 2026-03-29
---

The Source Editor is an in-browser code editor that is great for making minor changes to the source code of your files. This editing interface is useful for all text-based files.

![A screenshot of the Source Editor, an in-browser code editor.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Source-Editor.webp)

> Depending on your site configuration, you may not have access to the Source Editor for all files. An editing interface may not be available because:
> 
> - Some Permission Groups cannot access the Source Editor (e.g., unavailable to the [Editors Default Permission Group](/documentation/user-articles/what-are-default-permission-groups/#editors) or to [Clients](/documentation/user-articles/what-is-client-sharing/)).

## Source Editor features

The Source Editor displays the raw content of text-based files. Syntax highlighting in the Source Editor is automatically detected based on the file extension.

For more information about the *Editing interface navigation* and the *Context Menu* at the top of the Source Editor, read our documentation on [editing your files](/documentation/user-articles/edit-your-files/).

### Appearance and behavior

You can configure the appearance and behavior of the Source Editor using the `source_editor` key in your [CloudCannon configuration file](/documentation/developer-articles/create-your-cloudcannon-configuration-file/).

![A screenshot of the Source Editor, with the tab size, gutter, and theme customized.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Source-Editor-Custom-Theme.webp)

File: `cloudcannon.config.yml`

```YAML

source_editor:
  tab_size: 2
  show_gutter: false
  theme: eclipse

```

The Source Editor has the following configuration options available:

**`source_editor`** Object

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

- `tab_size`
- `show_gutter`
- `soft_wrap`
- `theme`

This key has no default.

**`source_editor.tab_size`** Integer

This key defines the auto-indentation of each line and how many spaces a tab indentation counts as.

By default, this key is `2`.

**`source_editor.show_gutter`** Boolean

This key toggles the gutter on the left of the editing interface, displaying line numbers and code folding controls.

By default, this key is `true`.

**`source_editor.soft_wrap`** Boolean

This key toggles whether the Source Editor should wrap long lines of text.

By default, this key is `true`.

**`source_editor.theme`** String

This key defines the color theme for syntax highlighting in the Source Editor.

Value can be one of the following: `atomone` `basic_light` `basic_dark` `darcula` `dracula` `duotone_light` `duotone_dark` `eclipse` `github_dark` `github_light` `gruvbox_dark` `gruvbox_light` `material_dark` `material_light` `solarized_dark` `solarized_light` `sublime` `tokyo_night` `tokyo_night_day` `tokyo_night_storm` `tomorrow_night_blue` `vscode_dark` `vscode_light` `xcode_dark` `xcode_light`

By default, this key is `basic_dark`.


---

---
title: What is the Visual Editor?
description: Learn about the Visual Editor, an editing interface for editing content directly ona preview of your webpage.
url: https://cloudcannon.com/documentation/user-articles/what-is-the-visual-editor/
content_type: user article
last_modified: 2026-03-29
---

The Visual Editor provides a user-friendly way of updating your website files on an interactive preview of your webpage. In the Visual Editor, you can navigate around your website preview using links/buttons, as you would on the live version, and edit your content inline on the page, or with the data panel or sidebar.

The primary benefit of visual editing is that what you see in CloudCannon it what your website visitors will see on your live webpages, so you can make editing decisions in context with surrounding page elements.

[Video: The Visual Editor with editable regions](https://player.vimeo.com/progressive_redirect/playback/1124969057/rendition/1080p/file.mp4?loc=external&signature=18a05ed71665768fa94851c72a31cf574e4079284b8ce0579885d8f3b47c4a8d)

The Visual Editor requires some configuration before you can use it, including a successful [Site build](/documentation/developer-articles/what-is-a-site-build/) and visual editing configuration with [Editable Regions](/documentation/developer-articles/what-are-editable-regions/) or Bookshop. We recommend reading our [Set up Visual Editing](/documentation/developer-guides/set-up-visual-editing/) guide if you have not yet enabled visual editing on your *Site*.

> Depending on your SSG and site configuration, you may not have access to the Visual Editor for all files. An editing interface may not be available because:
> 
> - A Developer on your team has [specified which editing interfaces are enabled](/documentation/developer-articles/set-a-default-editing-interface/) for a particular [collection](/documentation/user-articles/what-is-a-collection/) or [schema.](/documentation/developer-articles/what-is-a-schema/)

## Visual Editor features

Editing your content is easy. With the Visual Editor, you can instantly see what your content updates will look like live; the Visual Editor will automatically re-render to show you an accurate preview without needing to save your changes.

For more information about the tools in your *Editing Interface Header* at the top of the Visual Editor, please read our documentation on [editing your files](/documentation/user-articles/edit-your-files/).

### Inline editing

If your *Site* uses *Editable Regions* for visual editing, you will be able to see yellow boxes around content on your webpage preview. You can click into any of these yellow *Editable Regions* to edit inline. You can update plain or rich text, reorder array items, and click on images to open a data panel.

[Video: Array Editable Regions in the Visual Editor](https://player.vimeo.com/progressive_redirect/playback/1127384254/rendition/1080p/file.mp4?loc=external&signature=2a13816e5104cb323e411f0d83f84fe060f24975a7dc81fe5fe80155591af1a7)

> Inline editing is only available if your Visual Editor uses [Editable Regions](/documentation/developer-articles/what-are-editable-regions/). For more information, please contact your developer or our friendly [support team](/support/).

### The sidebar

The Visual Editor sidebar allows you to edit structured data in your file. When you edit a value in the sidebar, the webpage preview will update live to reflect the new value.

![A screenshot of the Visual Editor displays a webpage preview on the right and a sidebar with input fields on the left.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Visual-Editor-Bookshop-Sendit-Home.webp)

The sidebar contains an [Input](/documentation/user-articles/what-are-inputs/) for each piece of structured data in your file, providing an appropriate editing interface for the type of data (e.g., a text area for text, a upload area for picking an image, a dropdown when you want to select from a list of values, etc).

The sidebar in the Visual Editor shows the same information as the [Data Editor](/documentation/user-articles/what-is-the-data-editor/), and the sidebar in the [Content Editor](/documentation/user-articles/what-is-the-content-editor/). You can open or close the sidebar using the arrow button on the right of the panel.

### The data panel

In the Visual Editor, you can click on parts of your webpage to open a data panel, containing inputs for a specific section of structured data in your file. This could be image details like link, title, and alt text, or a single content block with text, images, or buttons.

Data panels are useful for editing data within a specific scope, or data that is not visible on the page (e.g., the URL for a link). Whatever data you update in a data panel, the preview of your webpage will automatically update to match.

![A screenshot of the Visual Editor displays a webpage preview with a data panel containing inputs open over top.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Visual-Editor-Bookshop-Sendit-Home-Data-Panel.webp)


---

---
title: What is web hosting?
description: Learn the basics of web hosting, and the option to host your Site through CloudCannon or an external service.
url: https://cloudcannon.com/documentation/user-articles/what-is-web-hosting/
content_type: user article
last_modified: 2026-04-11
---

Web hosting is where, after a successful [build](/documentation/developer-articles/what-is-a-site-build/), all your files are stored on a web server and made available to the public on the Internet. You can host your Site through CloudCannon or an external service.

Hosting your website requires a Domain Name, which you can purchase from any Domain Registrar.

- **Domain Name** — The address used to access a website (e.g., [cloudcannon.com](https://cloudcannon.com/)).
- **Domain Registrar** — A third-party company that handles the reservation of domain names and assigns IP addresses to domain names. Most CloudCannon users purchase a domain name from a Registrar (e.g., [Cloudflare Registrar](https://www.cloudflare.com/en-gb/products/registrar/), [NameCheap](https://www.namecheap.com/)).

The Domain Name of your website appears in the URL.

![A diagram of a URL shows labels for protocol, subdomain, domain, top-level domain, subdirectory, slug, and path.](assets/diagrams/CloudCannon-Documentation-URL-Structure-Diagram.png)

CloudCannon automatically assigns a free Domain Name to each Site, which you can use to preview your Site content live and share it with team members. However, most users also have a personal or business Domain Name that they connect to their Site. For more information, please read our documentation on [Testing Domains](/documentation/user-articles/what-is-a-testing-domain/) and [Custom Domains](/documentation/developer-articles/what-is-a-custom-domain/).

## Hosting on CloudCannon

To set up hosting on CloudCannon, you will need to:

- Connect a [Custom Domain](/documentation/developer-articles/what-is-a-custom-domain/).
- Configure a [DNS](/documentation/developer-articles/what-is-dns/) provider (either [CloudCannon DNS](/documentation/developer-articles/configure-cloudcannon-dns) or [external DNS](/documentation/developer-articles/configure-external-dns/)).
- Add an [SSL certificate](/documentation/developer-articles/what-is-an-ssl-certificate/) (either an [auto-generated SSL certificate](/documentation/developer-articles/add-an-auto-generated-ssl-certificate/) or a [custom SSL certificate](/documentation/developer-articles/add-a-custom-ssl-certificate/)).

Setting up your Custom Domain, DNS, and SSL certificate can be a circular process, requiring you to go back and forth as you configure your settings. To make it easier, here's a quick guide.

### Do you want to host on CloudCannon?

Hosting your Site on CloudCannon might be right for you if you want to keep your hosting settings on the same platform you use to edit your content.

CloudCannon uses a Cloudflare Content Delivery Network (CDN) for all Sites hosted on CloudCannon. A CDN is a globally distributed network of servers that improves your Site's loading time by caching your content. Visitors to your Site can then access a cached copy from a geographically closer server.

Whenever you update your Site, your hosting provider must also update these caches to prevent visitors from seeing out-of-date content. CloudCannon uses cache busting so that every time you update the content on your Site, CloudCannon will refresh all the cached copies as well.

If you don't want to host your Site on CloudCannon, you can use an external provider without interrupting your ability to edit your content in CloudCannon.

> If you want to host your Site externally, you can also disable builds on CloudCannon. For more information, please read our documentation on [Headless Mode](/documentation/developer-articles/what-is-headless-mode/).

### Which combination of DNS provider and SSL certificate is right for your Site?

Unless you are familiar with web hosting, we recommend reading our documentation [What is DNS?](/documentation/developer-articles/what-is-dns/) and [What is an SSL certificate?](/documentation/developer-articles/what-is-an-ssl-certificate/) before selecting a DNS provider or SSL certificate type.

DNS and SSL often work hand-in-hand. The correct combination of DNS provider and SSL certificate will depend on your desired Site configuration. Here are a few common examples:

1. **CloudCannon DNS and an auto-generated wildcard SSL certificate** (recommended) — Manage your domain settings and website security in the same place as your content: CloudCannon! Keep your DNS records up to date and protect all your domains and subdomains with a wildcard certificate.
2. **External DNS and an auto-generated wildcard SSL certificate** — Manage your domain settings through a trusted third-party service (e.g., Cloudflare) and generate your SSL certificate through CloudCannon. This option is good if you have existing DNS infrastructure.
3. **CloudCannon DNS and a custom SSL certificate** — Manage your domain settings through CloudCannon and generate your SSL certificate through a trusted third-party service.
4. **External DNS and a custom SSL certificate** — Manage your domain settings and generate your SSL certificate through a trusted third-party service. This option is good if you have existing DNS infrastructure and security policies that require you to have an SSL certificate from an internally approved authority.

For help setting up web hosting on CloudCannon, please contact our friendly [support team](/support/).


---

---
title: Why is Syncing paused?
description: Learn about Publishing Conflicts in CloudCannon and how they occur.
url: https://cloudcannon.com/documentation/user-articles/why-is-syncing-paused/
content_type: user article
last_modified: 2026-02-10
---

CloudCannon is constantly monitoring your branch in your Git repository. When someone saves a change to your branch, CloudCannon will sync that change to all CloudCannon Sites connected to that branch by overwriting the version of your file on your Site with the version from your Git repository. This behavior keeps your CloudCannon Site up to date with your Git repository.

To prevent incoming changes from overwriting your unsaved changes, CloudCannon will pause Syncing if an incoming change from your Git repository affects a file with unsaved changes.

- **Incoming changes** — These are changes to your Site files originating from outside the branch you are working on, such as from a different CloudCannon Site or your git repository. All incoming changes are made by a member of your team.

CloudCannon will notify you about a Syncing Conflict using the *Syncing paused* warning notification above the *Save* button in your *Site Navigation*.

![A screenshot of the Save Button in the Site Navigation shows a Sync Paused warning notification in the top right.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Save-Button-Syncing-Paused-Notification.webp)

> Incoming changes from your Git repository can affect multiple files. CloudCannon will pause Syncing for all files if one or more files have unsaved changes.

Before you can save any changes to unaffected files, you must allow CloudCannon to resume Syncing by saving the files with incoming changes. For more information, please read our documentation on [resume Syncing](/documentation/user-articles/resume-syncing/).

### Example

Let's go through an example.

We want to update the copy on our About webpage, so we open the `about.md` file in CloudCannon and start making changes. Coincidentally, another team member is also updating the `about.md` file at the same time. Our team member is a developer who is fixing some broken [inputs](/documentation/user-articles/what-are-inputs/) on several webpages, including the About page, using their local development environment.

> There are two ways to edit the same branch without being on the same CloudCannon Site.
> 
> One, you could connect the same branch to more than one CloudCannon Site. Normally, each branch in your Git repository is connected to one Site in CloudCannon. However, you can connect multiple CloudCannon Sites to a single branch if that suits your workflow (e.g., you have multiple websites in a single Git repository, or "monorepo").
> 
> Two, you could edit the same branch using a CloudCannon Site, your local development environment, or directly through your Git provider simultaneously. It's common for content creators to use CloudCannon to update their website, while developers use their local development environment or Git provider.

Before we can finish making our changes, our team member saves their changes to our website's Git repository. Our Git provider alerts CloudCannon that someone has updated several files and that CloudCannon should sync the new version of those files available on our Git repository to all connected CloudCannon Sites.

Because we have the About page open with unsaved changes, CloudCannon will pause Syncing notify us about the Syncing Conflict on the *Save* button and in the *Review changes* modal.

Before we can save any changes to other files or complete the sync to update all our files with incoming changes, we need to save or discard our changes to `about.md`. In this example, we want to save our unsaved changes and let CloudCannon complete the sync.


---

---
title: About Developer Articles
description: Learn about CloudCannon's Developer Documentation articles for customizing the UI, settings, and file management.
url: https://cloudcannon.com/documentation/developer-articles/
content_type: developer article
last_modified: 2026-02-24
---

Welcome to CloudCannon's Developer Documentation. These articles cover everything you need to know about customizing CloudCannon.

A Developer is anyone who customizes CloudCannon for their **team members** or clients by configuring the **UI**, settings, file management, **hosting**, and more. A Developer can also be a **User**, and even if you don't use CloudCannon, it is often helpful to understand the **CMS** experience from the User's perspective (see our [User Articles](/documentation/user-articles/)).

As a Developer, you can work in the CloudCannon web app ([https://app.cloudcannon.com/](https://app.cloudcannon.com/)) or your local development environment, whichever you prefer. For some settings, you will need to use CloudCannon's UI. The articles in this section of our documentation are designed to explain how CloudCannon works and provide instructions for configuring your CMS experience.

If you need any more help with your CloudCannon website, please don't hesitate to contact our friendly [support team](/support/).

## Syncing

Articles in the [Syncing](/documentation/developer-articles/introduction-to-syncing/) section cover how to connect your **Git Repository** to CloudCannon and manage the two-way sync between your source files and CloudCannon. Learn how to connect repositories from GitHub, GitLab, or Bitbucket, configure syncing for your **Sites**, and understand how CloudCannon tracks changes using **Git**. These articles are essential for setting up your development workflow and ensuring your team can collaborate effectively while maintaining version control.

## Sites

Articles in the [Sites](/documentation/developer-articles/introduction-to-sites/) section teach you how to create and configure **Sites** in CloudCannon. Learn how to create new Sites, configure initial Site settings, and manage Site configurations. These articles help you establish the foundation for your content management workflow and organize your Sites effectively.

## Editing

Articles in the [Editing](/documentation/developer-articles/introduction-to-editing/) section explain how to customize the CloudCannon editing experience for your **team members**. Learn how to configure editing interfaces, configure your **rich text editors** and **input types**, set up **Structures** and **Schemas** for content modeling, and add **editable regions** to your HTML to enable visual editing. These articles enable you to create an intuitive editing experience tailored to your team's needs.

## Assets

Articles in the [Assets](/documentation/developer-articles/introduction-to-assets-and-dams/) section cover how to manage large **files** and media assets using an external Digital Asset Manager (**DAMs**). Learn why storing assets outside your **Git Repository** can improve performance, how to integrate DAMs like S3, Cloudinary, Azure Blob Storage, and others with CloudCannon, and how to configure your **Sites** to use external asset storage. These articles are helpful for Sites with many images or large media files, as they help optimize **build** times and repository size.

## Publishing

Articles in the [Publishing](/documentation/developer-articles/introduction-to-publishing/) section cover how to set up publishing workflows for your **Sites**. Learn how to set up a **Project** to manage multiple **Sites** from the same repository, connect a **Publish Branch** to enable staging workflows, configure merging and **pull requests** , and manage how changes flow from branch Sites to your main Site. These articles are essential for teams that want to test changes before publishing them live, or for developers who need to review content changes before they go live.

## Sharing

Articles in the [Sharing](/documentation/developer-articles/introduction-to-sharing/) section cover how you can collaborate with others on CloudCannon. Learn how to create **Custom Permission Groups** to control exactly what resources each **team member** can access, configure **SSO/SAML** authentication, and manage how your team shares **Sites** and **Organizations**. These articles are useful for Developers who need to configure access controls and ensure team members have the appropriate level of permissions.

## Building

Articles in the [Building](/documentation/developer-articles/introduction-to-building/) section cover how to configure and extend the **build** process for your **Sites**. Learn how to set up your first build, configure build settings like environment variables and command-line options, extend builds with hooks, schedule builds manually or automatically, and use **Site Mounting** to share **files** between Sites. These articles are relevant for Sites that build on CloudCannon (building is optional).

## Hosting

Articles in the [Hosting](/documentation/developer-articles/introduction-to-hosting/) section cover the features available when you host your website on CloudCannon. Learn how to access your free **Testing Domain**, configure a **Custom Domain**, set up **DNS** (either CloudCannon DNS or external DNS), add SSL certificates, configure **routing** and redirects, and enable **authentication** methods to control visitor access. These articles are relevant for websites where you want to host your **Site** through CloudCannon and need to configure domain, security, and routing settings.

## Accounts

Articles in the [Accounts](/documentation/developer-articles/introduction-to-accounts/) section teach you everything you need to know about managing **Organizations** in CloudCannon. Learn how to create new Organizations, transfer **Sites** between Organizations, configure Multi-factor Authentication, and manage Organization-level settings. These articles are useful for Developers who need to organize multiple Sites or manage client Organizations with separate billing and access controls.


---

---
title: Add a Custom Domain to your Site
description: Learn how to add a Custom Domain name to your Site on CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/add-a-custom-domain-to-your-site/
content_type: developer article
last_modified: 2026-03-31
---

> **Permissions required**
> 
> Members of the Developers and Owners [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `site:settings:hosting:write` permission, can add a Custom Domain to a Site.

A Custom Domain is a unique address used to identify a website (e.g., [cloudcannon.com](https://cloudcannon.com)). If you have [connected a Custom Domain to your Organization](/documentation/developer-articles/connect-a-custom-domain-to-your-organization/), you can host your website content at that web address by adding the Custom Domain to your Site.

You can host a CloudCannon Site on the base domain (e.g., example.com), a subdomain (e.g., docs.example.com), or a subpath (e.g., example.com/staff/).

![A diagram of a URL shows labels for protocol, subdomain, domain, top-level domain, subdirectory, slug, and path.](assets/diagrams/CloudCannon-Documentation-URL-Structure-Diagram.png)

> You can configure both a subdomain and a subpath for each Site on CloudCannon, if your configuration requires them.

These instructions assume you have [connected a Custom Domain to your Organization](/documentation/developer-articles/connect-a-custom-domain-to-your-organization/) and, if you want to host on a subdomain or subpath, that you already have a Site hosted on your base domain.

To add a Custom Domain to your Site:

1. Click the *Sites* button in the *App Sidebar*. CloudCannon will open the *Sites browser*.
2. Identify the Site to which you want to add a Custom Domain and click on the *Site* card. CloudCannon will open the *Dashboard* for that Site.
3. Navigate to the *Custom Domain* page under *Site Settings*.
4. Select the Custom Domain you want to add using the *Base Domain* dropdown.
5. (Optional.) If you want to host your Site on a subdomain or subpath of your Custom Domain, enter the subdomain in the *Subdomain* text field, or the subpath in the *Subpath* text field. Leave these fields blank if you do not want to configure a subdomain or subpath for your Site.
6. Click the *Add a Domain* button.

CloudCannon will begin hosting your website content on your Custom Domain.

![A screenshot of the Custom Domain page under Site Settings shows the Base Domain dropdown to select a connected domain.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Custom-Domain-Domain-Dropdown.webp)

![A screenshot of the Custom Domain page under Site Settings shows the Base Domain dropdown and two text fields for Subdomain and Subpath.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Custom-Domain-Add-Domain.webp)

You can manage your Custom Domain settings, including subdomains and subpaths, on your Custom Domain's dedicated *Domain* page. To see you Custom Domain's *Domain* page, click on the card for your Custom Domain in the *Domains browser*.

To stop hosting your Site on a Custom Domain, please read our documentation on [removing a Custom Domain from your Site](/documentation/developer-articles/remove-a-custom-domain-from-your-site/).

We also recommend adding an [SSL certificate](/documentation/developer-articles/what-is-an-ssl-certificate/) to your Site. For more information, please read our documentation on [adding an auto-generated SSL certificate](/documentation/developer-articles/add-an-auto-generated-ssl-certificate/) or [adding a custom SSL certificate](/documentation/developer-articles/add-a-custom-ssl-certificate/).


---

---
title: Add a custom SSL certificate
description: Learn how to add custom PEM-encoded SSL certificates to your Site in CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/add-a-custom-ssl-certificate/
content_type: developer article
last_modified: 2026-04-11
---

> Managing your SSL certificate on CloudCannon requires you to host your **Site** through CloudCannon. If you are hosting your *Site* through an external service, please review their documentation on SSL certification.

You can purchase a custom SSL certificate from a trusted third-party provider.

You need the following details to add your custom SSL certificate to a **Custom Domain** on CloudCannon.

- Name (i.e., Domain Name)
- Expires (formatted as YYYY-MM-DD)
- Public Key
- Private Key
- Certificate Chain

> Your private key should only be given to your **DNS** provider. Do not write down your private key in a publicly accessible or insecure place. If you think the security of your private key has been compromised, please generate a new SSL certificate.

SSL certificates last for about a year and should be renewed at yearly intervals to maintain your website's security. You can renew your SSL certificate more often, but most websites do not require this level of security.

Before you add an SSL certificate to your *Site*, you must [add a Custom Domain](/documentation/developer-articles/add-a-custom-domain-to-your-site/) to your **Organization**.

> If you have recently added your *Custom Domain* to your *Site*, CloudCannon may need a few minutes to fetch your domain details before you can add an SSL certificate. If this process takes more than a few minutes, please contact our friendly [support team](/support/).

To add a custom SSL certificate:

1. Navigate to the *Domains Browser* by clicking *Domains* in the *App Sidebar*.
2. Select the domain to which you want to add a certificate.
3. Under the *Subdomains* heading, click the card for the subdomain to which you want to add the certificate.
4. Click the *Configure* button under the *SSL* heading. CloudCannon will open the *Configure SSL* modal.
5. Select a version number from the *Minimum TLS Version* dropdown.
6. Select the *New custom SSL certificate* option from the *Custom SSL Certificate* dropdown. CloudCannon will open the *Add SSL Certificate* modal.
7. Enter the details for *Name*, *Expires*, *Public Key*, *Private Key*, and *Certificate Chain*.
8. Click the *Add SSL Certificate* button.
9. Click the *Update SSL* button.

CloudCannon will apply your custom SSL certificate to the selected subdomain.

![A screenshot of the Add SSL Certificate modal showing fields for Name, Expires, Public Key, Private Key, and Certificate Chain.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Custom-Domain-Add-SSL-Certificate-Modal.webp)

Alternatively, you can leave the *Custom SSL Certificate* dropdown blank, and CloudCannon will autogenerate an SSL certificate for you.

> All certificates must use PEM encoding. The placeholder text indicates the correct start and end headers.

## Redirect HTTP to HTTPS

Once your SSL certificate is enabled, users can visit your *Site* on the more secure [HTTPS](/documentation/developer-articles/what-is-an-ssl-certificate/#http-vs-https) URL. CloudCannon will redirect any users who request the **HTTP** URL. For more information on redirects, please read our documentation on [configuring HTTP redirects](/documentation/developer-articles/configure-http-redirects/).


---

---
title: Add a Site Dashboard README
description: Learn how to add and edit a README file on your Site Dashboard in CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/add-a-site-dashboard-readme/
content_type: developer article
last_modified: 2026-03-29
---

The [Site Dashboard README](/documentation/developer-articles/what-is-the-site-dashboard-readme/) file displays custom Markdown content on the *Summary* tab of your *Site Dashboard*, giving your team immediate access to project information.

You can add a README to your *Site Dashboard* from the *Site Dashboard* using **Configuration Mode**, or by creating the file directly in your **Local Development Environment**.

## Add a README from the *Site Dashboard*

To add a README using *Configuration Mode*:

1. Navigate to the *Summary* tab on your *Site Dashboard*.
2. Click the *Configuration Mode* switch on the right of the *Site Header* to turn it on.
3. Click the *Add README* button. CloudCannon will create a `.cloudcannon/README.md` file and open it in the **Content Editor**.
4. Add your content.

CloudCannon will automatically display your README content on the *Summary* tab of the *Site Dashboard*. When you are happy with your content, save your file back to your *Git Repository*.

![A screenshot of the Site Dashboard with Configuration Mode on shows a purple + Add README button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Dashboard-No-README-Config-On.webp)

## Add a README from your IDE

To add a README directly in your repository:

1. Create a file at `.cloudcannon/README.md` in your Git repository.
2. Add your Markdown content and commit the file *Git Repository*.

CloudCannon will automatically sync the changes to your *Git Repository* and display your README content on the *Summary* tab of the *Site Dashboard*.

> The file path is case-insensitive. CloudCannon recognizes `.cloudcannon/README.md`, `.cloudcannon/readme.md`, and other case variations.

## Edit your README

You can edit your README file in CloudCannon using the [Content Editor](/documentation/user-articles/what-is-the-content-editor/). To open your README for in the *Content* *Editor*, turn on *Configuration Mode* and click the *Edit README* button on the *Site Dashboard*.

You can also edit the file directly in your *IDE* or through the *File Browser* in CloudCannon.

![A screenshot of the Site Dashboard with Configuration Mode on shows a purple Edit README button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Dashboard-README-Config-On.webp)


---

---
title: Add a Site to your Project
description: Learn how to add Sites to your CloudCannon Project, including connecting existing branches and creating new branch Sites.
url: https://cloudcannon.com/documentation/developer-articles/add-a-site-to-your-project/
content_type: developer article
last_modified: 2026-03-11
---

> **Some features are only available on our [Team and Enterprise plans](/pricing/).**
> 
> Want to chat about whether this feature is right for you? Our support team is always [happy to hear from you](mailto:success@cloudcannon.com?subject=A%20question%20about%20Projects).

Once you have [created a Project](/documentation/developer-articles/create-a-project/), you can add **Sites** to it. There are two ways to add a *Site* to your **Project**: connect an existing branch from your repository, or create a new branch *Site* through CloudCannon.

![A screenshot of the Project page showing the Sites tab with multiple Sites connected to different branches.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Project-Sites-Browser-With-Links.webp)

## Connect an existing branch

If you already have a branch in your **Git Repository** that you want to add to your *Project* as a *Site*, this is the best option. This includes connecting your main branch or any other pre-existing branch.

1. Click the *Projects* button in the *App Sidebar*. CloudCannon will open the *Projects Browser*.
2. Select the *Project* to which you want to add a *Site* by clicking on the *Project Card*. CloudCannon will open the *Project Sites Browser*.
3. Click the *+ Create a Site* button. CloudCannon will open the *Create a Site* page.
4. Enter a name for your *Site* in the *New Site name* field. The branch will automatically receive the same name.
5. Select the *Use an existing branch* option.
6. Select the branch you want to connect using the *Branch* dropdown. CloudCannon automatically populates this using the branches in your *Git Repository*.
7. Click the *Create Site* button.

CloudCannon will create a new *Site* in your *Project*.

![A screenshot of the Create a Site page within a Project, showing the repository, branch selection, and Site name fields.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Project-Create-a-Site-From-Existing-Branch.webp)

## Create a new branch Site

> **This feature is available on our** [**Team and Enterprise plans**](/pricing/)**.**

You can create a new branch *Site* from an existing *Site* in your *Project*. By allowing your team members to create *Sites* via branching in CloudCannon, you can enable them to work more independently and limit the number of people that require access to your *Git Provider*.

### Branching from the *Main Branch*

To use this branching method, you must have set a **Main Branch** for your *Project*. For more information, please read our documentation on [setting the Main Branch](/documentation/developer-articles/set-the-main-branch-for-your-project/).

1. Click the *Projects* button in the *App Sidebar*. CloudCannon will open the *Projects Browser*.
2. Select the *Project* to which you want to add a *Site* by clicking on the *Project Card*. CloudCannon will open the *Project Sites Browser*.
3. Click the *+ Create a Site* button. CloudCannon will open the *Create a Site* page.
4. Enter a name for your *Site* in the *New Site name* field. The branch will automatically receive the same name.
5. Select the *Create a new branch* option. CloudCannon will automatically populate the *Source branch* field with your *Main Branch*.
6. (Optional.) Enter a name for your new branch in the *New branch name* field, if it should be different to the *Site* name.
7. Click the *Create Site* button.

CloudCannon will create a new *Site* in your *Project*. Once you have made changes on the branch *Site*, you can publish them back to the main branch. For more information, read our documentation on [merging and Pull Requests](/documentation/developer-articles/merging-and-pull-requests/).

![A screenshot of the Create a Site page within a Project, showing the branch setup with the main branch selected as the source branch.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Project-Create-a-Site-From-Main-Branch.webp)

### Branching from another Site

You can also create a branch from another branched *Site*. When the branch *Site* is published, the changes will push back into the *Site* it was branched from. This option requires *Allow all branching* to be enabled.

To branch from an existing *Site*:

1. Click the *Projects* button in the *App Sidebar*. CloudCannon will open the *Projects Browser*.
2. Select the *Project* to which you want to add a *Site* by clicking on the *Project Card*. CloudCannon will open the *Project Sites Browser*.
3. Find the *Site* you want to branch from in the *Project Sites Browser* and open the **Context Menu** by clicking the three-dot icon on the top right *Site* card.
4. Select the *Branch Site* option from the *Context Menu*. CloudCannon will open the *Create a Site* page.
5. Enter a name for your *Site* in the *New Site name* field. The branch will automatically receive the same name.
6. Select the *Create a new branch* option. CloudCannon will automatically populate the *Source branch* field with the *Site* you wanted to branch from.
7. (Optional.) Enter a name for your new branch in the *New branch name* field, if it should be different to the *Site* name.
8. Click the *Create Site* button.

CloudCannon will create a new *Site* in your *Project*.

![A screenshot of the Project Sites Browser showing the context menu open on a Site card, with the Branch Site option visible.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Project-Sites-Browser-Context-Menu.webp)


---

---
title: Add a team member to Site Sharing
description: Learn how to add team members to Site Sharing.
url: https://cloudcannon.com/documentation/developer-articles/add-a-team-member-to-site-sharing/
content_type: developer article
last_modified: 2026-03-06
---

**Site Sharing** allows you to manage which team members have access to your **Site** and control their permissions. You can add existing team members from your **Organization** or invite new users by email.

To add a team member to your *Site*:

1. Navigate to the *Site Sharing* page under *Site Settings* in the *App Sidebar*.
2. Click the *+ Add members* button to open the *Invite team members to your Site* modal.
3. Enter the name of the team members you want to add to this *Site*. You can also enter the email addresses of new users you want to invite to your *Organization*.
4. Select the **Permission Group** to which you want to add these team members.
5. Click the *Add members* button.

CloudCannon will add the selected team members to your *Site* with the chosen *Permission Group*.

![A screenshot of the Invite Team Members to Site modal shows two fields, one for names and one for Permission Groups.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Site-Sharing-Invite-Modal.webp)


---

---
title: Add an auto-generated SSL certificate
description: Learn how to enable an auto-generated SSL certificate for your site, update DNS records, and redirect HTTP links to HTTPS.
url: https://cloudcannon.com/documentation/developer-articles/add-an-auto-generated-ssl-certificate/
content_type: developer article
last_modified: 2026-03-29
---

> Managing your SSL certificate on CloudCannon requires you to host your **Site** through CloudCannon. If you are hosting your *Site* through an external service, please review their documentation on SSL certification.

By default, CloudCannon will automatically generate an SSL certificate for all *Sites* hosted on CloudCannon through ZeroSSL and Cloudflare. This can be a wildcard SSL certificate or a single-domain SSL certificate. These certificates renew every 90 days automatically, so your *Site* is never insecure.

- **Wildcard SSL certificate** — A certificate that protects a single domain and all its subdomains (e.g., example.com and its subdomains blog.example.com, support.example.com, app.example.com, etc.).
- **Single-domain SSL certificate** — A certificate that protects a single domain. This is useful if you only have one CloudCannon *Site*, which is hosted on a subdomain.

> Wildcard SSL certificates are not available for [Sites hosted on a subdomain](/documentation/developer-articles/add-a-custom-domain-to-your-site/). If you have a CloudCannon *Site* hosted on your base domain, add a wildcard SSL certificate to that *Site*.

After adding an auto-generated SSL certificate, CloudCannon serves your *Site* over HTTPS. You can also redirect any users trying to access your website through the HTTP URL to the correct HTTPS URL.

Before you add an SSL certificate to your *Site*, you must [add a Custom Domain](/documentation/developer-articles/add-a-custom-domain-to-your-site/) to your **Organization**.

> If you have recently added your **Custom Domain** to your *Site*, CloudCannon may need a few minutes to fetch your domain details before you can add an SSL certificate. If this process takes more than a few minutes, please contact our friendly [support team](/support/).

To add an auto-generated SSL certificate to your *Site*:

1. Navigate to the *Domains Browser* by clicking *Domains* in the *App Sidebar*.
2. Select the domain to which you want to add a certificate.
3. Under the *Subdomains* heading, click the card for the subdomain to which you want to add the certificate.
4. Click the *Configure* button under the *SSL* heading. CloudCannon will open the *Configure SSL* modal.
5. Select a version number from the *Minimum TLS Version* dropdown.
6. Select the *DNS Text Record* option from the *Validation Method* dropdown.
7. (Optional) If you are adding an SSL certificate to a *Site* hosted on your base domain, ensure the *Generate a wildcard certificate to enable SSL on *example.com* checkbox is ticked. This option is not available for *Sites* hosted on a subdomain.
8. Click the *Update SSL* button.

CloudCannon will add an auto-generated SSL certificate to your domain.

![A screenshot of the SSL settings modal shows fields for Minimum TLS Version, Validation Method, and a wildcard certificate checkbox.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Configure-SSL-Auto-Generated-Modal-Element.webp)

To switch between a wildcard SSL certificate and a single domain SSL, untick the *Generate a wildcard certificate to enable SSL on *example.com* checkbox and click the *Update SSL* button.

## Add TXT DNS records

> This step is only required if you are using an [external DNS provider](/documentation/developer-articles/configure-external-dns/) and a CloudCannon auto-generated SSL certificate.

[TXT record validation](/documentation/developer-articles/what-is-an-ssl-certificate/#validation-method) is a method of authenticating ownership of your domain, so unauthorized individuals cannot add an SSL certificate to your domain.

**DNS** TXT Records demonstrate control over a domain, as only authorized individuals should be able to update the records stored by your DNS provider. If you are using [CloudCannon DNS](/documentation/developer-articles/configure-cloudcannon-dns/), you do not need to add a TXT record, as CloudCannon will handle validation for you. If you are using an [external DNS provider](/documentation/developer-articles/configure-external-dns/), you will need to add the two TXT records provided by CloudCannon to your DNS provider.

To use TXT record validation through an external DNS provider:

1. Navigate to the *Domains Browser* by clicking *Domains* in the *App Sidebar*.
2. Select the domain for which you want to add TXT records.
3. Under the *Subdomains* heading, click the card for the subdomain to which the SSL certificate applies.
4. Copy the two TXT records provided by CloudCannon.
5. Log in to your third-party DNS provider.
6. Add two TXT records to your DNS provider.

CloudCannon will validate your SSL certificate once the new DNS records propagate from your DNS provider. This could take up to 24 hours.

![A screenshot of the Custom Domain subdomain page shows the SSL status is pending.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Custom-Domain-Subdomain-SSL-Pending.webp)

## Redirect HTTP to HTTPS

Once your SSL certificate is enabled, users can visit your *Site* on the more secure [HTTPS](/documentation/developer-articles/what-is-an-ssl-certificate/#http-vs-https) URL. CloudCannon will redirect any users who request the **HTTP** URL. For more information on redirects, please read our documentation on [configuring HTTP redirects](/documentation/developer-articles/configure-http-redirects/).


---

---
title: Add Files with Direct Upload
description: Need to test a site without Syncing? Learn how to directly upload files your source files.
url: https://cloudcannon.com/documentation/developer-articles/create-a-site-with-direct-upload/
content_type: developer article
last_modified: 2026-03-29
---

Uploading files through a web browser is a quick way to get a website live on CloudCannon.

When creating a new site:

1. Select **Upload a folder** or **Upload a zip file**
2. Click on **Select your folder** or **Select your zip file**
3. Click on **Sync Files**

![Sync step of creating a site to add your files](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Create-Upload-Folder.webp)

> CloudCannon supports any file type uploaded or synced from a storage provider. The maximum size per file is 25 MB.

To upload files from the *File Browser*:

1. Open the *Add Files* menu
2. Select **Upload files** or **Upload a folder**

Uploading a folder uploads all files inside the folder, rather than the folder itself.

![Adding files to your site using the File Browser](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-File-Browser-Controls-Add-Menu-Dropdown.webp)

> Alternatively, drag and drop files into the File Browser.

Each file uploads individually to CloudCannon through your web browser.

> If your site is synced with a storage provider, CloudCannon will push the files there as well.


---

---
title: Add related links to your Project
description: Learn how to add related links to your CloudCannon Project page.
url: https://cloudcannon.com/documentation/developer-articles/add-related-links-to-your-project/
content_type: developer article
last_modified: 2026-03-11
---

Adding related links to your **Project** page is a great way to make common tasks quicker for your team. You can use these links to navigate to external resources, like analytics, documentation, FAQs, or often-used parts of the CloudCannon app.

To add related links to your *Project*:

1. Click the *Projects* button in the *App Sidebar*. CloudCannon will open the *Projects Browser*.
2. Select the *Project* to which you want to add related links by clicking on the *Project Card*. CloudCannon will open the *Project Sites Browser*.
3. Navigate to the *Details* section under the *Project Settings* tab and scroll to the *Related Links* section.
4. Enter a display name for the link in the *Name* field.
5. Type or paste your desired link into the *URL* field.
6. (Optional.) If you want to add more than one link, click the *Add Link* button. CloudCannon will add an extra *Name* and *URL* text field.
7. Click *Update Project*.

CloudCannon will display your link at the top of your *Project* page, above the project description (if applicable).

![A screenshot of the Project Settings page shows a Related Link named 'Production Site' with a URL filled in.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Project-Settings-Related-Links.webp)

![A screenshot of the Project page shows a Related Link displayed at the top, above the list of Sites.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Project-Sites-Browser-With-Links.webp)

You can remove a related link from your *Project* by clicking the *Delete* icon in the top right of the link on the *Project Settings* page.


---

---
title: Add SSO/SAML authentication
description: Learn how to add Single Sign-On authentication for your CloudCannon Organization.
url: https://cloudcannon.com/documentation/developer-articles/add-sso-saml-authentication/
content_type: developer article
last_modified: 2026-03-29
---

> **This feature is available on our [Enterprise plan](/pricing/).**
> 
> Want to chat about whether this feature is right for you? Our support team is always [happy to hear from you](mailto:success@cloudcannon.com?subject=A%20question%20about%20SSO%2FSAML).

To set up [SSO/SAML](/documentation/developer-articles/what-is-sso-saml/), you will need to copy data from CloudCannon to your Identity Provider and vice versa.

You must also identify which [Permission Group](/documentation/user-articles/what-are-permission-groups/) for new team members should be added to. This can be a [default](/documentation/user-articles/what-are-default-permission-groups/) or [Custom Permission Group](/documentation/developer-articles/what-are-custom-permission-groups/). CloudCannon will add new team members to this Permission Group if they join your Organization through SSO login rather than the CloudCannon email invitation link.

> SAML can be tricky to configure. If you need assistance setting-up SSO/SAML, please don’t hesitate to contact our [support team](/support/).

## Configure your Identity Provider

To configure your Identity Provider software:

1. Navigate to the *Single Sign-On* page under *Org settings*.
2. Copy the *Login URL* and *Consume URL (SSO URL)* links from CloudCannon and enter them into your Identity Provider.
3. Your Identity Provider will provide you with the details for *SAML 2.0 Endpoint (HTTP)*, *Issuer Suffix* (must begin with “cloudcannon.com/”), *Name ID Format*, *Authn Context*, and *X.509 Certificate*. Copy these details or download the XML file provided.

![A screenshot of the Single Sign-On page shows the configuration details for initial set up of your Identity Provider.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Single-Sign-On.webp)

## Configure SAML

To configure SAML:

1. Navigate to the *Single Sign-On* page under *Org settings*.
2. Select the initial Permission Group for team members joining your Organization through SSO.
3. Enter the details for *SAML 2.0 Endpoint (HTTP)*, *Issuer Suffix* (must begin with “cloudcannon.com/”), *Name ID Format*, *Authn Context*, and *X.509 Certificate*. Alternatively, click the *Fill form using XML Metadata* button and upload your XML file.
4. Click the *Add Single Sign-On* button.

CloudCannon will provide additional details once you have set up SAML. Your identity provider may require these details.


---

---
title: Adjusting the uploads path
description: Learn how to configure where CloudCannon will upload new assets and define the default browser location for selecting existing files.
url: https://cloudcannon.com/documentation/developer-articles/adjusting-the-uploads-path/
content_type: developer article
last_modified: 2026-04-11
---

Upload paths control the location that new asset files are uploaded to. You can configure your upload paths using these options:

**`paths.uploads`** String

Determines the directory to upload to, for site files.

**`paths.uploads_filename`** String

Determines the name of the uploaded file, for site files.

The default value is `[asset_filename_without_ext|slugify|deburr][count].[asset_ext|lowercase]`.

**`paths.uploads_use_relative_path`** Boolean

If this is set, files will be referenced relative to the path of the file they were uploaded to.

For example, if `paths.uploads` is configured as `[base_path]/images` and you upload `image.jpg` to `/blog/my-post.md`, the path will be saved as `images/image.jpg`.
In the same scenario, if you select an existing image `/siteicon.png`, the path will be saved as `../siteicon.png`.

The default value is `false`.

**`paths.static`** String

Determines the location of statically copied site assets.

**`paths.dam_uploads`** String

Determines the directory to upload to, when uploading [DAM](/documentation/developer-articles/introduction-to-assets-and-dams/) files.

**`paths.dam_uploads_filename`** String

Determines the name of the uploaded file, when uploading [DAM](/documentation/developer-articles/introduction-to-assets-and-dams/) files.

The default value is `[asset_filename]`.

Uploads paths are configured alongside other paths in a number of places:

- Globally in the [CloudCannon Configuration file](/documentation/developer-articles/what-is-the-cloudcannon-configuration-file/).
- Per Content Editor or Editable Region with [editables configuration options](/documentation/developer-articles/define-editable-regions-in-your-html/#options).
- Per input with inputs configuration:
  
  - [File input options](/documentation/user-articles/what-is-a-file-input/#options).
  - [URL input options](/documentation/user-articles/what-is-a-url-input/#options).
  - [Rich Text input options](/documentation/user-articles/what-is-a-rich-text-input/#options).

Here's an example for a fixed path:

```yaml
paths:
  uploads: assets/uploads
  dam_uploads: raw
```

Here's an example for a path that changes depending on where new assets files are uploaded:

```yaml
paths:
  uploads: static/assets/[collection]/{title|slugify}
  dam_uploads: raw/{date|year}-{date|month}-{date|day}
```

> The uploads path also defines the default location when selecting existing files.

## Placeholders

Uploads paths have a number of placeholders available, depending on whether you are configuring the upload directory (with `path.uploads` or `path.dam_uploads`) or the upload filename (with `path.uploads_filename` or `path.dam_uploads_filename`).

### Directory placeholders

There are two types of placeholders: file and data placeholders.

File placeholders are always available, and relate to the file the editor is open on:

- `[collection]` is the collection key the file is assigned to.
- `[path]` is the full path of the file, relative to site source.
- `[base_path]` is the path of the file excluding filename, relative to site source.
- `[slug]` is the filename, excluding extension. Is an empty string if this results in "index".
- `[filename]` is the filename, including extension.
- `[ext]` is the last extension.
- `[relative_path]` is the full path of the file, relative to the collection path.
- `[relative_base_path]` is the path of the file excluding filename, relative to the collection path.
- `[full_slug]` is an alias for `[relative_base_path]/[slug]`.

Data placeholders are populated from front matter or data values in the editor, and support a number of filters:

- `{title}` is the title from inside the file.
- `{id}` is the id from inside the file.
- `{title|lowercase}` is title from inside the file, lower cased.
- `{category|slugify}` is category from inside the file, slugified.
- `{tag|slugify|uppercase}` is tag from inside the file, slugified, then upper cased.
- `{date|year}` is date from inside the file, with the 4-digit year extracted.
- `{date|month}` is date from inside the file, with the 2-digit month extracted.
- `{date|day}` is date from inside the file, with the 2-digit day extracted.

The placeholders are processed when the new asset is added. This means that changes to front matter or data after adding an asset file are not updated for that processed upload path.

### Filename placeholders

- `[asset_filename]` is the full name of uploaded file (e.g. "my-document.pdf").
- `[asset_filename_without_ext]` is filename without any extension (e.g. "my-document").
- `[asset_ext]` is the file's extension without a "." (e.g. "png").
- `[date]`
- `[count]` becomes a hyphen and number if the processed file path clashes with an existing file (e.g. `my-document-1.pdf`)

You can use filters to transform these placeholders. For example `[asset_filename|slugify].[asset_ext]` will convert "My Document.pdf" into "my-document.pdf". You can read more about using placeholders, and see a list of all available filters, [in this article](/documentation/developer-articles/configure-your-template-strings/).

> Placeholders that result in empty values may result in sequential slashes — these are collapsed into one after applying placeholders.

## Migrating from old format

The `uploads_dir` option and legacy placeholders are an old configuration that we have since improved on. These are backwards compatible so there's no need to change anything. If you do want to update, the legacy placeholders and their new equivalents are:

- `:categories` is now `{categories|slugify}`.
- `:title` is now `{title|slugify}`.
- `:slug` is now `{slug}`.
- `:year` is now `{date|year}`.
- `:month` is now `{date|month}`.
- `:day` is now `{date|day}`.
- `:collection` is now `[collection]`.


---

---
title: Allow authenticated users to log out
description: Learn how CloudCannon detects if a user is authenticated and how to configure a logout button on your authenticated pages.
url: https://cloudcannon.com/documentation/developer-articles/allow-authenticated-users-to-log-out/
content_type: developer article
last_modified: 2026-04-11
---

> This feature is only available for Sites [hosted through CloudCannon](/documentation/user-articles/what-is-web-hosting/#hosting-on-cloud-cannon). If you host your Site externally, or use CloudCannon in [Headless Mode](/documentation/developer-articles/what-is-headless-mode/), this feature will not work.

When you [enable password authentication](/documentation/developer-articles/enable-password-authentication/), [enable user account authentication](/documentation/developer-articles/enable-user-account-authentication/), or [enable SAML authentication](/documentation/developer-articles/enable-saml-authentication/), CloudCannon attaches a cookie to the visitor's web browser when they have successfully logged in (i.e., authenticated). CloudCannon uses this cookie to allow access when a user requests an authenticated route.

> No sensitive authentication data is exposed through cookies.

This cookie is removed if a visitor clears their Internet browser cache.

You can allow authenticated users to log out by adding a logout link to your authenticated routes. CloudCannon reserves the `/logout` route on all Sites. The logout URL for your Site will be your domain name followed by `/logout`, even if you serve your Site on a [subdomain](/documentation/developer-articles/add-a-custom-domain-to-your-site/), or [subpath](/documentation/developer-articles/add-a-custom-domain-to-your-site/), CloudCannon w (e.g., `example.com/logout`, `app.example.com/logout`, or `example.com/documentation/logout`).

> CloudCannon reserves the `/logout` URL for all Sites hosted on CloudCannon, even if you do not have a CloudCannon authentication method enabled. You cannot serve any content on this URL.

When a visitor clicks the logout link, CloudCannon removes the cookie and redirects them to your home page.

You can create a logout button on your authenticated pages using the following link:

File: `index.html`

```html

<a href="/logout">Log out</a>

```

If you use [authenticated routes](/documentation/developer-articles/configure-authenticated-routes/), your public pages may have a mix of authenticated and non-authenticated users. In this case, you can use JavaScript and CSS to show the logout button only to authenticated users.

File: `script.js`

```javascript

var isAuthenticated = document.cookie.indexOf("authenticated=true") >= 0;

if (isAuthenticated) {
  document.body.classList.add("authenticated");
}

```

File: `styles.css`

```css

.logout {
  display: none;
}

.authenticated .logout {
  display: block;
}

```

File: `index.html`

```html

<a href="/logout" class="logout">Log out</a>

```

In the above example, the user's browser will add the `authenticated` class to the `body` element of your page if they have the `authenticated` cookie. The CSS file will only display elements with the `.logout` class if nested within an element with the `.authenticated` class.


---

---
title: Authenticate your Git provider
description: Learn how to authenticate a Git provider during Site creation or through your Org Settings.
url: https://cloudcannon.com/documentation/developer-articles/authenticate-your-git-provider/
content_type: developer article
last_modified: 2026-02-24
---

> **Permissions required**
> 
> Members of the Owners or Developers [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `org:settings:git:provider` permission, can manage which Git providers are connected to an Organization.

For CloudCannon to sync your files from a Git repository, you must give it permission to access your Git provider. CloudCannon supports [GitHub](/documentation/developer-articles/connecting-a-github-repository-as-your-source/?__hstc=242898397.6032b94e38c1ac0306d0387267014e86.1758859406215.1759875180243.1759911875948.6&__hssc=242898397.8.1759911875948&__hsfp=488715181), [GitLab](/documentation/developer-articles/connecting-a-gitlab-respository-as-your-source/?__hstc=242898397.6032b94e38c1ac0306d0387267014e86.1758859406215.1759875180243.1759911875948.6&__hssc=242898397.8.1759911875948&__hsfp=488715181), or [Bitbucket](/documentation/developer-articles/connecting-a-bitbucket-respository-as-your-source/?__hstc=242898397.6032b94e38c1ac0306d0387267014e86.1758859406215.1759875180243.1759911875948.6&__hssc=242898397.8.1759911875948&__hsfp=488715181). You only need to authenticate your Git provider once, and you can authenticate multiple Git providers on an account (but not multiple accounts on the same provider).

There are two ways to authenticate a Git provider: when you create a new *Site*, and through your *Org Settings* page.

## Authenticate during *Site* creation

To authenticate a Git provider during *Site* creation:

1. Click the *Sites* button in the *App Sidebar*. CloudCannon will open the *Sites Browser*.
2. Click the *Create a Site* button. CloudCannon will open the *Create a Site* page.
3. Select an unauthenticated Git provider using the *File source* dropdown. CloudCannon will show you the *Authenticate* button. Authenticated providers have a green shield icon next to the option.
4. Click the *Authenticate* button and follow your Git provider's instructions to authenticate access.
5. Return to the *Create a Site* page on CloudCannon and continue following the prompts to create a *Site*.

Your Git provider is now authenticated, and CloudCannon will display all repositories available through that provider in the *Repository* dropdown.

![A screenshot of the Create a Site page shows an Authenticate button to approve CloudCannon's access to GitHub.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Create-a-Site-Authenticate-GitHub.webp)

![A screenshot of the list of Git providers shows the green shield icon indicating that GitHub is authenticated through CloudCannon.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Create-a-Site-Authenticated-GitHub.webp)

## Authenticate in your *Org Settings*

To authenticate a Git provider through your *Org Settings*:

1. Click the *Org Settings* button in the *App Sidebar*. CloudCannon will open the *Details* page.
2. Navigate to the *GitHub*, *Bitbucket*, or *GitLab* page under the *Files* heading, depending on which provider you want to authenticate.
3. Click the *Authenticate* button and follow your Git provider's instructions to authenticate access.

Your Git provider is now authenticated.

![A screenshot of the Bitbucket page under Org Settings shows the authenticate button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Bitbucket-Page.webp)


---

---
title: Best practice for splitting your Configuration File
description: Learn about the best practices for splitting your Configuration File.
url: https://cloudcannon.com/documentation/developer-articles/best-practice-for-splitting-your-configuration-file/
content_type: developer article
last_modified: 2026-02-10
---

It is important to find the right balance between organization and maintainability when [splitting your *Site* configuration](/documentation/developer-articles/split-your-configuration-file/) across multiple *Configuration Files*. If you split your configuration too granularly, finding a specific configuration can be as difficult as if it were all in the same file.

When you split your configuration, we recommend starting with a single section (e.g., one *Collection* under `collections_config` or your *Site*-scope Inputs under `_inputs`) and testing that the configuration behaves as expected before moving on to other sections.

Let's walk through a list of best practices to help you split your configuration. All these examples are optional, but might help you determine the right balance for splitting your *Site* configuration.

## Create a dedicated *Configuration File* for each *Collection*

If you have many *Collections* on your *Site*, scrolling through all your configuration to find the right one is not efficient. In this case, it might be easier to create a dedicated *Configuration File* for each *Collection*, rather than list each one in your main *CloudCannon Configuration File*.

In this example, we have two *Collections*: Pages and Posts.

File: `cloudcannon.config.yml`

```YAML
collections_config:
  pages:
    path: content
    icon: wysiwyg
  posts:
    path: content/posts
    icon: event
    preview:
      text:
        - key: title
      subtext:
        - key: author
      metadata:
        - icon: event
          text:
            - template: Published on {date|date_long}
```

We can move all the content under each *Collection* key into the dedicated files, `pages.cloudcannon.collections.yml` and `posts.cloudcannon.collections.yml`, in a new folder, `.cloudcannon/collections/`. Then, we can reference all *Collection Configuration Files* in the new folder using the `collections_config_from_glob` key in our main *CloudCannon Configuration File.*

File: `cloudcannon.config.yml`

```YAML
collections_config_from_glob:
  - '/.cloudcannon/collections/*.cloudcannon.collections.yml'
```

File: `pages.cloudcannon.collections.yml`

```YAML
pages:
  path: content
  icon: wysiwyg
```

File: `posts.cloudcannon.collections.yml`

```YAML
posts:
  path: content/posts
  icon: event
  preview:
    text:
      - key: title
    subtext:
      - key: author
    metadata:
      - icon: event
        text:
          - template: Published on {date|date_long}
```

## Create chains of *Configuration Files*

When you split your *Site* configuration across multiple *Configuration Files*, your main *Configuration File* will point to other *Configuration Files* on your *Site* using `*_from_glob` keys.

However, you can also use `*_from_glob` key in any other *Configuration File*, allowing you to create chains of configuration across several files. As long as every *Configuration File* ultimately connects back to your main *Configuration File*, CloudCannon will be able to merge your configuration.

File: `cloudcannon.config.yml`

```YAML
collections_config_from_glob___1___:
  - '/.cloudcannon/collections/*.cloudcannon.collections.yml'
```

File: `/.cloudcannon/collections/posts.cloudcannon.collections.yml`

```YAML
posts:
  path: content/posts
  icon: event
  schemas_from_glob:
    - '/.cloudcannon/schemas/blogPost.cloudcannon.schemas.yml'
    - '/.cloudcannon/schemas/companyAnnouncement.cloudcannon.schemas.yml'
    - '/.cloudcannon/schemas/caseStudy.cloudcannon.schemas.yml'
```

## Use negative globs for finer control

The value of each `*_from_glob` key is an array of strings, where each string is a glob pattern matching specific files on your *Site*. You can use the array to specify multiple files. However, if you want to match all files with a few exceptions, it is more efficient to use a negative glob.

In this example, we have several *Schema Configuration Files* in the `.cloudcannon/schemas/` folder (e.g., Announcement, Customer Story, Blog, Pages). We want to use most, but not all, of these *Schemas* in our Posts *Collection*.

File: `/.cloudcannon/collections/posts.cloudcannon.collections.yml`

```YAML
posts:
  path: content/posts
  icon: event
  schemas_from_glob:
    - '/.cloudcannon/schemas/*.cloudcannon.schemas.yml'
    - '!/.cloudcannon/schemas/pages.cloudcannon.schemas.yml'
```

We can tell CloudCannon to use all *Schema Configuration Files* in this folder using the `*.cloudcannon.schemas.yml` glob, but exclude `pages.cloudcannon.schemas.yml` by prefixing the string with an `!` character to create a negative glob.

## Define related configuration in the same file

Your *Configuration Files* can contain multiple entries for object configuration keys, allowing you to store related configuration together in the same file.

File: `cloudcannon.config.yml`

```YAML
collections_config:
  posts:
    path: content/posts
    icon: event
    inputs_from_glob:
      - '/.cloudcannon/inputs/seo.cloudcannon.inputs.yml'
      - '/.cloudcannon/inputs/blog-details.cloudcannon.inputs.yml'
```

File: `/.cloudcannon/inputs/seo.cloudcannon.inputs.yml`

```YAML
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
```

## Use split and inline configuration in the same file

You don't have to split all your configuration into separate files. Instead, you can use inline configuration and reference other *Configuration Files* using `*_from_glob` keys simultaneously.

File: `cloudcannon.config.yml`

```YAML
_inputs_from_glob:
  - '/.cloudcannon/inputs/seo.cloudcannon.inputs.yml'
  - '/.cloudcannon/inputs/blog-details.cloudcannon.inputs.yml'
_inputs:
  authors:
    type: multiselect
    options:
      values: collections.authors
```

## Configuring Structures inside Inputs

It is important to note the correct places to use `_structures_from_glob` and `values_from_glob`. CloudCannon expects `.cloudcannon.structures.yml` *Configuration Files* need to have the *Structure*  key at the root of the file, while `.cloudcannon.structure-value.yml` *Configuration Files* only contain the keys for a single array item.

Please use one of the following configurations:

File: `cloudcannon.config.yml`

```YAML
_structures:
  staffTypes:
    style: modal
    values:
      - label: Employee
        value:
          name:
          job_description:
          profile_picture:
_inputs:
  staff:
    type: array
    options:
      structures: _structures.staffTypes
```

File: `cloudcannon.config.yml`

```YAML
_structures_from_glob:
  - /.cloudcannon/structures/staffTypes.cloudcannon.structure.yml
_inputs:
  staff:
    type: array
    options:
      structures: _structures.staffTypes
```

File: `cloudcannon.config.yml`

```YAML
_inputs:
  staff:
    type: array
    options:
      structures:
        values_from_glob:
          - /.cloudcannon/structures/staffTypes.cloudcannon.structure-value.yml
```

> The following configuration is incorrect, as the `_structures` key is not the same as the `_inputs.*.options.structures` key:
> 
> File: `cloudcannon.config.yml`
> 
> ```YAML
> 
> _inputs:
>   staff:
>     type: array
>     options:
>       _structures_from_glob:
>         - /.cloudcannon/structures/staffTypes.cloudcannon.structure.yml
> 
> ```


---

---
title: Best practices for Custom Permission Groups
description: Learn about common pitfalls and best practices for creating Custom Permission Groups.
url: https://cloudcannon.com/documentation/developer-articles/best-practices-for-custom-permission-groups/
content_type: developer article
last_modified: 2026-04-11
---

> **This feature is available on our [Team and Enterprise plans](/pricing/).**
> 
> Want to chat about whether this feature is right for you? Our support team is always [happy to hear from you](mailto:success@cloudcannon.com?subject=A%20question%20about%20custom%20Permission%20Groups).

[Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) give you fine-grained control over the permissions in your Organizations. When [creating a Custom Permission Group](/documentation/developer-articles/create-a-custom-permission-group/), there are some common pitfalls you can fall into. In this article, we will go over a few examples.

## Resources

A resource is something you can interact with in CloudCannon, such as an individual Site, Pull Request settings, or billing information. Each resource has one or more associated actions: Read, Write, or Create. In CloudCannon, you select which resources you want members to have access to using the resource permission tree.

### Minimum set of resources required to view a Site in CloudCannon

There is a minimum set of resources required to view a Site in CloudCannon.

Groups will need a permission containing the following resources for each Site you want members to access: `site:details:read`, `site:build:details:read`, and `site:sync:details:read`. If you have connected your Site to a DAM, you will also need `site:dam:read`.

> **Why is there not a single resource for viewing a Site in CloudCannon?**
> 
> We separated the resources required to view a Site to support future API access. The CloudCannon API will be able to access any subset of resources without loading everything. The CloudCannon API is currently in early access.

## File globs

A file glob is a pattern used to identify matching files. Files globs look similar to a file path with a mix of literal text and special characters such as `*` and `{ }`. In CloudCannon, you can specify read or write access to specific file globs in a Custom Permission Group for fine-grain control over reading and editing site files.

> If you need assistance setting-up file globs in your Organization, our [support team](/support/) is always happy to help.

Here are some common pitfalls when creating file globs.

### Adding a file glob overrides the resource tree

Specifying a file glob in a permission or an exception will override any selections made in the resource tree. This is because adding globs enables the *site:file* resource at a more specific level.

By selecting `site:files:read` or `site:files:write` in the resource tree, you allow Group members to read or write all files within your permission scope. However, as soon as you specify a file glob, CloudCannon will override the resource tree and limit access to only files that match your file glob.

You may unintentionally lose access to files by specifying a file glob.

For example, suppose we add the file glob `posts/**` with write access to a Custom Permission Group. Members of this Group will be able to see and edit any files within the collection “Posts” (as permission to write implicitly includes permission to read). Because we have not included any other file globs, members of this Group will lose read access to all files that do not match this file glob. Without permission to read other files, all other collections on your Site will not appear in the app.

To avoid this pitfall, carefully consider what files your Group members need access to and include a file glob for all these files.

### Multiple file globs are necessary to edit a single file

When giving access to a small number of files on your Site, you should consider how many file globs you need to achieve your goal. Some file globs are not immediately obvious but are required for CloudCannon to function as intended.

You should also allow access to:

- The Site icon file.
- The Schemas folder or specific Schema for any files you want Group members to be able to edit or create.
- Any folders in your repository for storing or uploading images and videos.

### File globs in an exception but none specified in a permission

Adding a file glob to an exception and none to permissions will prevent members of this Group from accessing any Site files, even if you selected `site:files:read` or `site:files:write` in the permission resource tree. This is because specifying a file glob in a permission or an exception will override any selections made in the resource tree.

In this case, a file glob in an exception overrides the permission tree, and because no permissions file globs are specified, the members of this Group cannot access any files.

To avoid this pitfall, add a permission with the file glob `**/*` for access to all files, or create a more specific file glob to allow access to some files. Your exception will now function.

### Specifying files but not subfolders

File globs include special characters such as `*` and `{ }`. The `*` character denotes any file, while `/**/` denotes any number of folders. When you want to specify any file, it is important to account for any subfolders within your collection.

For example, the file glob `/posts/*` will match any file located immediately within the “Posts” collection. The glob `/posts/*/*` will match any file located exactly one subfolder deep in your collection.

To account for files within any number of subfolders, we recommend using a file glob that contains `/**/*`. In the above example, this would be `/posts/**/*`, which matches any file immediately within the “Posts” collection or within any number of subfolders under “Posts.”

### Adding file globs but forgetting the read permission for your CloudCannon configuration file

You need permission to read the [CloudCannon configuration file](/documentation/developer-articles/what-is-the-cloudcannon-configuration-file/)  to see the Collections in your *Site Navigation*. As soon as you specify a file glob, CloudCannon will override the generic options `site:files:read` or `site:files:write` in the resource tree and limit access to only files that match your file glob. If you do not provide permission to read the CloudCannon Configuration file, members of your Custom Permission Groups will be limited in their ability to use Sites on CloudCannon.


---

---
title: Best practices for HTML in rich text
description: Some HTML elements cannot be edited in the rich text editor. 
url: https://cloudcannon.com/documentation/developer-articles/best-practices-for-rich-text/
content_type: developer article
last_modified: 2026-04-11
---

You can edit markup content in one of CloudCannon's three [rich text editors](/documentation/developer-articles/what-are-rich-text-editors/): the [Content Editor](/documentation/user-articles/what-is-the-content-editor/), [editable regions](/documentation/developer-articles/define-editable-regions-in-your-html/) in the [Visual Editor](/documentation/user-articles/what-is-the-visual-editor/), or [Rich Text inputs](/documentation/user-articles/what-is-a-rich-text-input/). However, CloudCannon will handle some markup content differently.

CloudCannon uses the following definitions:

- **Rich text content** — any HTML, Markdown, or MDX content you might want to edit in the Content Editor, an editable region in the Visual Editor, or a Rich Text input.
- **Custom markup** — any HTML, Markdown, or MDX structure that cannot be recreated in a rich text editor (e.g., `<div>` tags or style attributes). This is usually any structure that the *WYSIWYG toolbar* cannot produce.

Editing custom markup in a rich text editor comes with risk. This is because:

- You can unintentionally delete custom markup from your files. CloudCannon cannot render custom markup in the rich text editor; therefore, it would be easy to backspace or accidentally delete your HTML structures. Because the *WYSIWYG toolbar* cannot produce custom markup, it cannot be recreated if you accidentally delete it.
- Some custom markup structures pose a security risk to your Site by enabling cross-site scripting attacks (e.g., `<script>` tags) and other unwanted interactions between your code and the editing interface (e.g., `<style>` tags).

To get the most out of your editing experience, we recommend that you only include markup that can be rendered and edited in a CloudCannon rich text editor.

## Unsupported HTML elements in rich text editors

To protect your content and your site, CloudCannon does not allow you to edit custom markup using the [Content Editor](/documentation/user-articles/what-is-the-content-editor/) or a [Rich Text input](/documentation/user-articles/what-is-a-rich-text-input/) by default. Although you cannot edit your custom markup in the Content Editor or rich text inputs, CloudCannon will preserve it. Your custom markup will appear as an uneditable Snippet.

![Unsupported HTML in the rich text editor will appear as an uneditable Snippet.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Unsupported-HTML.webp)

By default, you can edit some custom markup using [editable regions](/documentation/developer-articles/define-editable-regions-in-your-html/), but not any custom markup that poses a risk for cross-site scripting attacks.

You can still edit the surrounding content in your files using a rich text editor and edit your custom markup in the [Source Editor](/documentation/user-articles/what-is-the-source-editor/).

## Best practice for custom markup

To ensure your files remain editable in the rich text editor, we recommend the following solutions to avoid some common pitfalls:

- Remove custom markup from inside elements with `class='editable'`. Any other markup inside your editable region may cause the region to become an uneditable Snippet.
- Create a [Snippet](/documentation/developer-articles/what-is-a-snippet/). Depending on your SSG, there are libraries of Snippets available, or you can create custom Snippets.
- Use postprocessing to add the desired HTML during the build (e.g., using Hugo's [Markdown render hooks](https://gohugo.io/templates/render-hooks/)).

## Configure how CloudCannon handles custom markup

You can configure how CloudCannon handles custom markup using the `allow_custom_markup` and `remove_custom_markup` keys.

The `allow_custom_markup` key enables you to edit custom markup in rich text editors and explicitly accept the risk of unintentionally deleting elements that cannot be recreated. By default, `allow_custom_markup` is `false` for inputs and the Content Editor and `true` for editable regions.

The `remove_custom_markup` key enables you to strip custom markup from content edited in a rich text editor, allowing you to clean files of unnecessary HTML content. By default, `remove_custom_markup` is `false` for inputs, the Content Editor, and editable regions.

For more information, please read our [rich text editor](/documentation/developer-reference/configuration-file/types/_editables/) reference documentation.


---

---
title: CloudCannon link protocol
description: CloudCannon links are a custom protocol that allows you to deep link into CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/cloudcannon-protocol/
content_type: developer article
last_modified: 2026-04-11
---

CloudCannon Links allow you to reference other sections of the CloudCannon interface. These are used within Editor links and Add options.

## Syntax

CloudCannon Links are formatted with `cloudcannon:{path}#{slug}` and match the URL structure of the CloudCannon app.

**`path`** string

The relative path of the collection inside of the site url. For example  `https://app.cloudcannon.com/123/editor#sites/456/dashboard` would become  `dashboard` which targets the current site's dashboard.

If you want your link to be relative to `https://app.cloudcannon.com/` add  a `!` to the start of your URL. This is used internally for linking to the  templates list and using this is not recommended.

**`slug`** string

Modelled after [JavaScripts property accessors](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Property_accessors), this is a recursive representation of your desired object target. Starting from the base of your structure, name each item as a step towards your desired object. Each object or property is separated by a dot. An array item is denoted by an open square bracket, an integer starting from 0, followed by a closing square bracket (`[index]`).

### Linking to front matter

By excluding the front path, the cloudcannon link is relative to the current page. This is useful for keeping your code DRY. For example:

- `cloudcannon:#title` Targets the title of the current page
- `cloudcannon:#seo.title` Targets the title within the seo object
- `cloudcannon:#people[0]` Targets the first array item in an array named people.
- `cloudcannon:#people[0].title` Targets the title of the first array item within an array named people.

### Creating an array item

A special case of slug editing is the `+`, by targeting an array you can trigger an item to be added to the end of the array. For example `cloudcannon:#people[+]` Create a new item in an array named people.


---

---
title: Configure a 404 page
description: Configure a helpful, branded 404 page when a visitor requests a page that cannot be found.
url: https://cloudcannon.com/documentation/developer-articles/configure-a-404-page/
content_type: developer article
last_modified: 2026-04-11
---

> This feature is only available for Sites [hosted through CloudCannon](/documentation/user-articles/what-is-web-hosting/#hosting-on-cloud-cannon). If you host your Site externally, or use CloudCannon in [Headless Mode](/documentation/developer-articles/what-is-headless-mode/), this feature will not work.

A "404 page" is the webpage shown to visitors when the web server cannot find the content for the URL they requested, named after the [HTTP status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) `404 Not Found`. A web server may be unable to find a page's content because:

- The URL is incorrect.
- The content has been deleted from the website or moved to a different URL.

By default, visitors will see a simple 404 page when the web server cannot find a URL from a Site hosted on CloudCannon.

![A screenshot of CloudCannon's default 404 page.](assets/onboarding_screenshots/CloudCannon-Documentation-404-Page.png)

> CloudCannon will also show a 404 page if a visitor requests the URL for an image or file on your website.

We recommend creating a dedicated 404 page that matches your Site branding and provides helpful resources when your users get lost.

To show visitors a custom 404 page:

1. Create a file called `404.html` and add the content you want CloudCannon to serve.
2. Save your page to your Site. We recommend saving it in the same place as other important pages (e.g., "Home" or "About").
3. Navigate to the `routing.json` file within your `.cloudcannon` folder using the *File browser*, or create one if you have not done so.
4. Create an entry within the `routes` array with the subkeys `from`, `to`, `status`, and `forced`.
5. Set `from` to a REGEX string that captures all URLs (e.g., `/.*`), `to` to the path of your 404 page, `status` to `404`, and `forced` to `false`.
6. Save your changes.

After a successful build, CloudCannon will show visitors your custom `404.html` when the web server cannot find a page on your website.

It is important to set `forced` to `false`, as this configuration option determines whether the routing rule should take priority over any existing page content. By setting this key to `false`, CloudCannon will only serve our 404 page content for URLs that match the `from` REGEX string if the web server cannot find a page's content.

If you would prefer, you can also configure your `routing.json` file using your local development environment.

For a complete list of options available in the `routing.json` file, please read our [routing reference](/documentation/developer-reference/routing-file/) documentation.

> Set the permalink of your page to /404.html if you are using Jekyll and non-default permalinks.

We also recommend creating a custom header to prevent search engines indexing your 404 page. For more information, please read our documentation on [custom headers](/documentation/developer-articles/configure-custom-routing/#custom-headers).

Here is an example of what your 404 route should look like:

File: `routing.json`

```json

{
  "routes": [
    {
      "from": "/.*",
      "to": "/404.html",
      "status": 404,
      "forced": false
    }
  ],
  "headers": [
    {
      "match": "/404.html",
      "headers": [
        {
          "name": "X-Robots-Tag",
          "value": "noindex, nofollow"
        }
      ]
    }
  ]
}

```

Most Sites only need one 404 page, but you can create as many 404 routes as required by configuring a more specific `from` URL. You must list routes in order from most to least specific REGEX strings, otherwise will ignore consecutive routes. For more generic information, please read our documentation on [configuring custom routing](/documentation/developer-articles/configure-custom-routing/).

File: `routing.json`

```json

{
  "routes": [
    {
      "from": "/blog/.*",
      "to": "/404-blog.html",
      "status": 404,
      "forced": false
    },
    {
      "from": "/.*",
      "to": "/404.html",
      "status": 404,
      "forced": false
    }
  ]
}

```


---

---
title: Configure a Boolean input
description: Learn how to configure a Boolean input to edit true or false values in your data files or front matter.
url: https://cloudcannon.com/documentation/developer-articles/configure-a-boolean-input/
content_type: developer article
last_modified: 2026-03-29
---

> **Permissions required**
> 
> Members of all [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `site:file:write` permission, can configure inputs in all locations in the configuration cascade. You can limit permission to specific locations in the configuration using [file globs](/documentation/developer-articles/what-are-custom-permission-groups/#specify-a-file-glob).

A [Boolean input](/documentation/user-articles/what-is-a-boolean-input/) is an editing interface for structured data with true or false values in data files or front matter. By configuring your inputs, you can customize the appearance and functionality for a better editing experience.

![A screenshot of the Checkbox Boolean input in the Data Editor shows a true value.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Boolean-Input-Checkbox-True.webp)

![A screenshot of the Switch Boolean input in the Data Editor shows a true value.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Boolean-Input-Switch-True.webp)

For a complete list of configuration keys available for inputs please read our [Inputs](/documentation/developer-reference/configuration-file/types/_inputs/) reference documentation.

These instructions assume that you know what type of Boolean input you want to configure and where in the configuration cascade. For more information, please read our documentation on [Boolean inputs](/documentation/user-articles/what-is-a-boolean-input/), [inputs](/documentation/user-articles/what-are-inputs/) in general, and the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

To configure a Boolean input:

1. Open your website files in your local development environment, or log in to CloudCannon and select the Site for which you want to configure your input.
2. Navigate to the location in the configuration cascade where you want to configure your input. This can be the root of your CloudCannon Configuration File, within the `collections_config.*` key in your CloudCannon Configuration File, a Schema file, the frontmatter of a markup file, or any where you configure a Structure.
3. Identify the `_inputs` key, or create one at that level of the configuration cascade.
4. Add an input name key for your input under the `_inputs` key (a.k.a., `_inputs.*`). We recommend naming your input something simple that indicates the function or context.
5. Add the `type` key under your input name key, with either the `checkbox` or `switch` value.
6. (Optional.) Add any other general configuration keys (e.g., `label`, `comment`, `context`) under your input name key.
7. (Optional.) Add any specific configuration keys under `_inputs.*.options` (e.g., `required`).

CloudCannon will now apply this input configuration to all markup files that use your input name key, without needing to save your configuration. This allows you to make changes to your input configuration and see those changes affect inputs live.

When you are happy with your input configuration, you must save your input configuration.

File: `cloudcannon.config.yml`

```YAML
```

_inputs___1___:
  blog_published___2___:
    type___3___: checkbox
  featured___4___:
    type___5___: switch

```

**[1]** All inputs are defined under the `_inputs` key, regardless of where they are in the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

**[2]** This Boolean input is called `blog_published`.

**[3]** The value of the `type` key determines the input type. This is a `checkbox` Boolean input.

**[4]** This Boolean input is called `featured`.

**[5]** The value of the `type` key determines the input type. This is a `switch` Boolean input.
```

When you add your input key name to a data or markup file, your configured Boolean input will appear in the Data Editor, Visual Editor, or Content Editor.

File: `blog.md`

```Markdown

---
blog_published: true
featured: false
---

Blog content goes here.

```

## Input configuration options

General configuration options are available for all input types. You can define the label, comment, and context box for your Boolean input, whether it is hidden or disabled, and how CloudCannon should handle configuration at multiple levels of the configuration cascade.

Boolean inputs are simple. There are no specific configuration options for Boolean inputs.

Here is an example of a Boolean input using some of the most commonly used configuration keys.

File: `cloudcannon.config.yml`

```YAML

_inputs:
  blog_published:
    type: checkbox
    label: Published
    comment: This blog will appear on our website when this box is checked

```

## Valid values

Here are some examples of valid values for the key `available`. These work for both Checkbox and Switch inputs.

**YAML:**

Empty/null value:

- `available: `

Boolean values (without any quotation marks):

- `available: true`
- `available: false`

**TOML:**

Boolean values (without any quotation marks):

- `available = true`
- `available = false`

**JSON:**

Null value:

- `"available": null`

Boolean values (without any quotation marks):

- `"available": true`
- `"available": false`

## Unconfigured Boolean inputs

In some cases, CloudCannon can still detect a Boolean input even if you have not configured it.

CloudCannon will interpret any unconfigured input with a `true` or `false` value as a Checkbox Boolean input. CloudCannon cannot create a Switch input without configuration.

File: `article.md`

```Markdown

---
public: true
---

Content goes here.

```

This behavior is convenient if you have simple inputs or do not want to configure inputs. It is also beneficial for new websites on CloudCannon where you have yet to create any CloudCannon-specific configuration.

> We recommend configuring your inputs for greater control over their functionality and appearance.


---

---
title: Configure a Code input
description: Learn how to configure a Code input to edit blocks of code or mono-space plain text content in your data files or front matter.
url: https://cloudcannon.com/documentation/developer-articles/configure-a-code-input/
content_type: developer article
last_modified: 2026-03-29
---

> **Permissions required**
> 
> Members of all [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `site:file:write` permission, can configure inputs in all locations in the configuration cascade. You can limit permission to specific locations in the configuration using [file globs](/documentation/developer-articles/what-are-custom-permission-groups/#specify-a-file-glob).

A [Code input](/documentation/user-articles/what-is-a-code-input/) is an editing interface for code or mono-spaced plain text content. By configuring your inputs, you can customize the appearance and functionality for a better editing experience.

![A screenshot of the Code Input in the Data Editor shows code in a text area with syntax highlighting.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Code-Input-Ruby-Codeblock.webp)

These instructions assume that you know where in the configuration cascadeyou want to configure your input. For more information, please read our documentation on [Code inputs](/documentation/user-articles/what-is-a-code-input/), [inputs](/documentation/user-articles/what-are-inputs/) in general, and the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

To configure a Code input:

1. Open your website files in your local development environment, or log in to CloudCannon and select the Site for which you want to configure your input.
2. Navigate to the location in the configuration cascade where you want to configure your input. This can be the root of your CloudCannon Configuration File, within the `collections_config.*` key in your CloudCannon Configuration File, a Schema file, the frontmatter of a markup file, or any where you configure a Structure.
3. Identify the `_inputs` key, or create one at that level of the configuration cascade.
4. Add an input name key for your input under the `_inputs` key (a.k.a., `_inputs.*`). We recommend naming your input something simple that indicates the function or context.
5. Add the `type` key under your input name key, with the value `code`.
6. (Optional.) Add any other general configuration keys (e.g., `label`, `comment`, `context`) under your input name key.
7. (Optional.) Add any specific configuration keys under `_inputs.*.options` (e.g., `syntax`, `theme`, `show_gutter`).

CloudCannon will now apply this input configuration to all markup files that use your input name key, without needing to save your configuration. This allows you to make changes to your input configuration and see those changes affect inputs live.

When you are happy with your input configuration, you must save your input configuration.

File: `cloudcannon.config.yml`

```YAML
```

_inputs___1___:
  example_ruby___2___:
    type___3___: code

```

**[1]** All inputs are defined under the `_inputs` key, regardless of where they are in the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

**[2]** This Code input is called `example_ruby`.

**[3]** The value of the `type` key determines the input type. This is a `code` input.
```

When you add your input key name to a data or markup file, your configured Code input will appear in the Data Editor, Visual Editor, or Content Editor.

File: `data.yml`

```YAML

example_ruby: |
  def say_hello
    puts 'Hi there!'
  end

  say_hello

```

## Input configuration options

General configuration options are available for all input types. You can define the label, comment, and context box for your Code input, whether it is hidden or disabled, and how CloudCannon should handle configuration at multiple levels of the configuration cascade.

Specific configuration options for Code inputs include defining the height of the code area, tab size, theme color, gutter visibility, syntax highlighting, and how CloudCannon handles empty values. You can also add input validation to require a value, specify the minimum and maximum value length, or match a regular expression.

Here is an example of a Code input using some of the most commonly used configuration keys.

File: `cloudcannon.config.yml`

```YAML

_inputs:
  example_ruby:
    type: code
    label: Example Ruby Code
    comment: Enter the example code for the feature
    options:
      max_visible_lines: 25
      min_visible_lines: 15
      show_gutter: false
      syntax: ruby
      theme: darcula
      required: true

```

For a complete list of configuration keys available for inputs please read our [Inputs](/documentation/developer-reference/configuration-file/types/_inputs/) reference documentation.

These keys configure the appearance and functionality of Code inputs in CloudCannon.

**`_inputs.*.options.max_visible_lines`** Integer

This key determines the maximum number of visible lines in the code area, controlling maximum height. When content exceeds this number of lines, the input becomes a scroll area. Defaults to `30`.

**`_inputs.*.options.min_visible_lines`** Integer

This key determines the minimum number of visible lines in the code area, controlling initial height. When content exceeds this number of lines, the input expands line by line until it reaches the value of `max_visible_lines`. Defaults to `10`.

**`_inputs.*.options.show_gutter`** Boolean

This key toggles the line numbers and code-folding controls. Defaults to `true`.

**`_inputs.*.options.syntax`** String

This key determines how the input parses your content for syntax highlighting. The value should match the code language. This key has no default.

Value must be one of:

`abap` `abc` `actionscript` `ada` `alda` `apache_conf` `apex` `applescript` `aql` `asciidoc` `asl` `assembly_x86` `autohotkey` `batchfile` `c9search` `c_cpp` `cirru` `clojure` `cobol` `coffee` `coldfusion` `crystal` `csharp` `csound_document` `csound_orchestra` `csound_score` `csp` `css` `curly` `d` `dart` `diff` `django` `dockerfile` `dot` `drools` `edifact` `eiffel` `ejs` `elixir` `elm` `erlang` `forth` `fortran` `fsharp` `fsl` `ftl` `gcode` `gherkin` `gitignore` `glsl` `gobstones` `golang` `graphqlschema` `groovy` `haml` `handlebars` `haskell` `haskell_cabal` `haxe` `hjson` `html` `html_elixir` `html_ruby` `ini` `io` `jack` `jade` `java` `javascript` `json` `json5` `jsoniq` `jsp` `jssm` `jsx` `julia` `kotlin` `latex` `less` `liquid` `lisp` `livescript` `logiql` `logtalk` `lsl` `lua` `luapage` `lucene` `makefile` `markdown` `mask` `matlab` `maze` `mediawiki` `mel` `mixal` `mushcode` `mysql` `nginx` `nim` `nix` `nsis` `nunjucks` `objectivec` `ocaml` `pascal` `perl` `perl6` `pgsql` `php` `php_laravel_blade` `pig` `plain_text` `powershell` `praat` `prisma` `prolog` `properties` `protobuf` `puppet` `python` `qml` `r` `razor` `rdoc` `red` `redshift` `rhtml` `rst` `ruby` `rust` `sass` `scad` `scala` `scheme` `scss` `sh` `sjs` `slim` `smarty` `snippets` `soy_template` `space` `sparql` `sql` `sqlserver` `stylus` `svg` `swift` `tcl` `terraform` `tex` `text` `textile` `toml` `tsx` `turtle` `twig` `typescript` `vala` `vbscript` `velocity` `verilog` `vhdl` `visualforce` `wollok` `xml` `xquery` `yaml` `zeek`

Alternatively, you can configure `syntax` with the naming convention. `syntax` is assumed to be the section preceding the normalized `_code_block` suffix (e.g. `my_javascript_code_block` for `javascript`).

**`_inputs.*.options.tab_size`** Integer

This key defines how many spaces each line is auto indented by, and how many spaces a tab is shown as. Defaults to `2`.

**`_inputs.*.options.theme`** String

This key determines the color scheme for syntax highlighting. This key is only applicable if `syntax` is also defined. Defaults to `monokai`.

Value must be one of:

`ambiance` `chaos` `chrome` `clouds` `clouds_midnight` `cobalt` `crimson_editor` `dawn` `dracula` `dreamweaver` `eclipse` `github` `gob` `gruvbox` `idle_fingers` `iplastic` `katzenmilch` `kr_theme` `kuroir` `merbivore` `merbivore_soft` `mono_industrial` `monokai` `nord_dark` `pastel_on_dark` `solarized_dark` `solarized_light` `sqlserver` `terminal` `textmate` `tomorrow` `tomorrow_night` `tomorrow_night_blue` `tomorrow_night_bright` `tomorrow_night_eighties` `twilight` `vibrant_ink` `xcode`

**`_inputs.*.options.empty_type`** string

This key determines how CloudCannon handles an empty value. This key does not apply to existing empty values.

Value must be one of the following:

- `string` - an empty value for this input will be stored as `""`.
- `null` - an empty value for this input will be stored as a null value (default). This does not apply to TOML files.

**`_inputs.*.options.required`** Boolean

This key toggles whether CloudCannon requires this Input to have a value. If set to `true`, CloudCannon will require you to enter a value to save your changes, or discard your unsaved changes.

By default, this key is `false` (i.e, CloudCannon does not require this Input to have a value).

This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.

In this example, we want to require our team to enter an `author` value for markup files with this Input.

File: `cloudcannon.config.yml`

```YAML
  _inputs:
    author:
      type: text
      comment: Enter the name of the author for this blog post.
      options:
        required: true

```

**`_inputs.*.options.required_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.required`. This key requires you to define `options.required`.

This key has no default.

This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to use enter an Input value using a required message.

File: `cloudcannon.config.yml`

```YAML
  _inputs:
    author:
      type: text
      comment: Enter the name of the author for this blog post.
      options:
        required: true
        required_message: You are not allowed to leave this blank.

```

**`_inputs.*.options.max_length`** Number

This key defines the maximum string length, in characters, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.

Value can be any non-negative integer. If this key is set to `0`, CloudCannon requires the Input to be empty. If `options.min_length` is also configured, this key cannot be a smaller number.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, `allow_create` must be set to `true`.

In this example, we want our team to enter a blog description using the Rich Text `seo_description` Input. This Input limits you to a maximum of 125 characters.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      min_length: 25
```

**`_inputs.*.options.max_length_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.max_length`. This key requires you to define `options.max_length`.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to enter a valid number of characters using a custom message.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      max_length_message: You are only allowed 125 characters.
      min_length: 25
      min_length_message: Please write more than 25 characters.
```

**`_inputs.*.options.min_length`** Number

This key defines the minimum string length, in characters, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.

Value can be any positive integer. If `options.max_length` is also configured, this key cannot be a greater number.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, `allow_create` must be set to `true`.

In this example, we want our team to enter a blog description using the Rich Text `seo_description` Input. This Input requires a minimum of 25 characters.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      min_length: 25
```

**`_inputs.*.options.min_length_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.min_length`. This key requires you to define `options.min_length`.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to enter a valid number of characters using a custom message.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      max_length_message: You are only allowed 125 characters.
      min_length: 25
      min_length_message: Please write more than 25 characters.
```

**`_inputs.*.options.pattern`** String

This key defines a [regular expression](https://re2js.leopard.in.ua/) that the Input value must match. When configured, CloudCannon will require you to enter a value that matches the REGEX pattern. If the Input already contains an invalid value, CloudCannon will require you to enter a valid string to save your changes, or discard your unsaved changes.

Value must be a valid REGEX string. If your REGEX string includes a `\` character and CloudCannon Configuration File is a `.yml` file, use single quotes `'` around the string to avoid a build error.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, `allow_create` must be set to `true`.

In this example, we want our team to add an email address to the `contact_email` Input using the correct email format.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  contact_email:
    type: email
    options:
      pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
      pattern_message: 'Please use the format ___@___.__'
```

**`_inputs.*.options.pattern_message`** String

This key defines the message that explains which [regular expression](https://re2js.leopard.in.ua/) an Input will accept. This key requires you to define `options.pattern`.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to use the correct email format in the `contact_email` Input using a pattern message.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  contact_email:
    type: email
    options:
      pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
      pattern_message: 'Please use the format ___@___.__'
```

## Valid values

Code inputs can have multiple valid values for empty, single-line, and multiline content. Here are some examples of valid values for the key `code`.

**YAML:**

Empty/null value:

- `code: `

Any valid string (quoted or unquoted):

- `code: ""`
- `code: ''`
- `code: any string`
- `code: "any string"`
- `code: 'any string'`

Any valid multiline string:

- `code: >
    multiline string`
- `code: >-
    multiline string`
- `code: >+
    multiline string`
- `code: |
    multiline string`
- `code: |-
    multiline string`
- `code: |+
    multiline string`

**TOML:**

Any valid string:

- `code = ""`
- `code = "any string"`

Any valid escaped string:

- `code = ''`
- `code = 'any string (literal)'`

Any valid multiline string:

- `code = """
    multiline string"""`
- `code = """\
    multiline string (trimmed)
    \"""`
- `code = '''
    literal multiline string'''`

**JSON:**

Null value:

- `"code": null`

Any valid string:

- `"code": ""`
- `"code": "any string"`

Any valid multiline string:

- `"code": "multiline \n string"`

## Unconfigured Code inputs

In some cases, CloudCannon can still detect a Code input even if you have not configured it.

CloudCannon will interpret any unconfigured input with the key name `code_block`, or that ends in `_code_block` as a Code input.

File: `about.md`

```Markdown

---
code_block: |
  Some content is better in monospace.

  1 + 1 = 2
  2 + 2 = 4
---

```

This behavior is convenient if you have simple inputs or do not want to configure inputs. It is also beneficial for new websites on CloudCannon where you have yet to create any CloudCannon-specific configuration.

> We recommend configuring your inputs for greater control over their functionality and appearance.


---

---
title: Configure a Color input
description: Learn how to configure a Color input to edit a color value in your data files or front matter.
url: https://cloudcannon.com/documentation/developer-articles/configure-a-color-input/
content_type: developer article
last_modified: 2026-03-29
---

> **Permissions required**
> 
> Members of all [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `site:file:write` permission, can configure inputs in all locations in the configuration cascade. You can limit permission to specific locations in the configuration using [file globs](/documentation/developer-articles/what-are-custom-permission-groups/#specify-a-file-glob).

A [Color input](/documentation/user-articles/what-is-a-color-input/) is an editing interface for color information. By configuring your inputs, you can customize the appearance and functionality for a better editing experience.

![A screenshot of the Color input in the Data Editor shows a HEX value in the text field.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Color-Input-HEX-Open.webp)

These instructions assume that you know where in the configuration cascade you want to configure your input. For more information, please read our documentation on [Color inputs](/documentation/user-articles/what-is-a-color-input/), [inputs](/documentation/user-articles/what-are-inputs/) in general, and the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

To configure a Color input:

1. Open your website files in your local development environment, or log in to CloudCannon and select the Site for which you want to configure your input.
2. Navigate to the location in the configuration cascade where you want to configure your input. This can be the root of your CloudCannon Configuration File, within the `collections_config.*` key in your CloudCannon Configuration File, a Schema file, the frontmatter of a markup file, or any where you configure a Structure.
3. Identify the `_inputs` key, or create one at that level of the configuration cascade.
4. Add an input name key for your input under the `_inputs` key (a.k.a., `_inputs.*`). We recommend naming your input something simple that indicates the function or context.
5. Add the `type` key under your input name key, with the value `color`.
6. (Optional.) Add any other general configuration keys (e.g., `label`, `comment`, `context`) under your input name key.
7. (Optional.) Add any specific configuration keys under `_inputs.*.options` (e.g., `format`, `alpha`).

CloudCannon will now apply this input configuration to all markup files that use your input name key, without needing to save your configuration. This allows you to make changes to your input configuration and see those changes affect inputs live.

When you are happy with your input configuration, you must save your input configuration.

File: `cloudcannon.config.yml`

```YAML
```

_inputs___1___:
  gradient_stop___2___:
    type___3___: color

```

**[1]** All inputs are defined under the `_inputs` key, regardless of where they are in the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

**[2]** This Color input is called `gradient_stop`.

**[3]** The value of the `type` key determines the input type. This is a `color` input.
```

When you add your input key name to a data or markup file, your configured Color input will appear in the Data Editor, Visual Editor, or Content Editor.

File: `blog.md`

```Markdown

---
gradient_stop: rgb(3, 74, 216)
---

Blog content goes here.

```

## Input configuration options

General configuration options are available for all input types. You can define the label, comment, and context box for your Color input, whether it is hidden or disabled, and how CloudCannon should handle configuration at multiple levels of the configuration cascade.

Specific configuration options for Color inputs include defining the format of a color value, enabling transparency controls, and how CloudCannon handles empty values. You can also add input validation to require a value, specify the minimum and maximum value length, or match a regular expression.

Here is an example of a Color input using some of the most commonly used configuration keys.

File: `cloudcannon.config.yml`

```YAML

_inputs:
  background:
    type: color
    label: Background Color
    comment: Select the color for the background of this page.
    options:
      format: hex
      required: true
      pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$
      pattern_message: Please enter a valid HEX format.

```

For a complete list of configuration keys available for inputs please read our [Inputs](/documentation/developer-reference/configuration-file/types/_inputs/) reference documentation.

These keys configure the appearance and functionality of Color inputs in CloudCannon.

**`_inputs.*.options.format`** String

This key determines what format the color picker uses. Does not update existing values. Defaults to follow the input naming convention, or `hex`.

Value must be one of `rgb`, `hex`, `hsl`  or `hsv`.

**`_inputs.*.options.alpha`** Boolean

This key toggles the transparency controls for the color picker. Defaults to follow the input naming convention.

**`_inputs.*.options.empty_type`** string

This key determines how CloudCannon handles an empty value. This key does not apply to existing empty values.

Value must be one of the following:

- `string` - an empty value for this input will be stored as `""`.
- `null` - an empty value for this input will be stored as a null value (default). This does not apply to TOML files.

**`_inputs.*.options.palette`** Array of Strings

This key adds a color palette to the Color Input dropdown for important color values. This array will accept multiple color value formats.

In this example, we want to provide our team members with an array of specific color values which they can select from a color palette.

File: `cloudcannon.config.yml`

```YAML
  _inputs:
    theme_color:
      type: color
      options:
        palette:
          - rgb(255, 128, 0)
          - hsv(00, 70, 50)
          - lightyellow

```

**`_inputs.*.options.hide_picker`** Boolean

This key toggles whether CloudCannon will show the spectrum color picker as well as the color palette. If set to `true`, CloudCannon will hide the spectrum color picker. This key requires you to define `options.palette`.

By default, this key is `false` (i.e, CloudCannon does show the spectrum color picker).

In this example, we want our team to select a color from the configured color palette rather than use the color spectrum picker.

File: `cloudcannon.config.yml`

```YAML
  _inputs:
    theme_color:
      type: color
      options:
        palette:
          - rgb(255, 128, 0)
          - hsv(00, 70, 50)
          - lightyellow
        hide_picker: true

```

**`_inputs.*.options.empty_type`** string

This key determines how CloudCannon handles an empty value. This key does not apply to existing empty values.

Value must be one of the following:

- `string` - an empty value for this input will be stored as `""`.
- `null` - an empty value for this input will be stored as a null value (default). This does not apply to TOML files.

**`_inputs.*.options.required`** Boolean

This key toggles whether CloudCannon requires this Input to have a value. If set to `true`, CloudCannon will require you to enter a value to save your changes, or discard your unsaved changes.

By default, this key is `false` (i.e, CloudCannon does not require this Input to have a value).

This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.

In this example, we want to require our team to enter an `author` value for markup files with this Input.

File: `cloudcannon.config.yml`

```YAML
  _inputs:
    author:
      type: text
      comment: Enter the name of the author for this blog post.
      options:
        required: true

```

**`_inputs.*.options.required_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.required`. This key requires you to define `options.required`.

This key has no default.

This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to use enter an Input value using a required message.

File: `cloudcannon.config.yml`

```YAML
  _inputs:
    author:
      type: text
      comment: Enter the name of the author for this blog post.
      options:
        required: true
        required_message: You are not allowed to leave this blank.

```

**`_inputs.*.options.max_length`** Number

This key defines the maximum string length, in characters, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.

Value can be any non-negative integer. If this key is set to `0`, CloudCannon requires the Input to be empty. If `options.min_length` is also configured, this key cannot be a smaller number.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, `allow_create` must be set to `true`.

In this example, we want our team to enter a blog description using the Rich Text `seo_description` Input. This Input limits you to a maximum of 125 characters.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      min_length: 25
```

**`_inputs.*.options.max_length_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.max_length`. This key requires you to define `options.max_length`.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to enter a valid number of characters using a custom message.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      max_length_message: You are only allowed 125 characters.
      min_length: 25
      min_length_message: Please write more than 25 characters.
```

**`_inputs.*.options.min_length`** Number

This key defines the minimum string length, in characters, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.

Value can be any positive integer. If `options.max_length` is also configured, this key cannot be a greater number.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, `allow_create` must be set to `true`.

In this example, we want our team to enter a blog description using the Rich Text `seo_description` Input. This Input requires a minimum of 25 characters.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      min_length: 25
```

**`_inputs.*.options.min_length_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.min_length`. This key requires you to define `options.min_length`.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to enter a valid number of characters using a custom message.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      max_length_message: You are only allowed 125 characters.
      min_length: 25
      min_length_message: Please write more than 25 characters.
```

**`_inputs.*.options.pattern`** String

This key defines a [regular expression](https://re2js.leopard.in.ua/) that the Input value must match. When configured, CloudCannon will require you to enter a value that matches the REGEX pattern. If the Input already contains an invalid value, CloudCannon will require you to enter a valid string to save your changes, or discard your unsaved changes.

Value must be a valid REGEX string. If your REGEX string includes a `\` character and CloudCannon Configuration File is a `.yml` file, use single quotes `'` around the string to avoid a build error.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, `allow_create` must be set to `true`.

In this example, we want our team to add an email address to the `contact_email` Input using the correct email format.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  contact_email:
    type: email
    options:
      pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
      pattern_message: 'Please use the format ___@___.__'
```

**`_inputs.*.options.pattern_message`** String

This key defines the message that explains which [regular expression](https://re2js.leopard.in.ua/) an Input will accept. This key requires you to define `options.pattern`.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to use the correct email format in the `contact_email` Input using a pattern message.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  contact_email:
    type: email
    options:
      pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
      pattern_message: 'Please use the format ___@___.__'
```

## Valid values

Here are some examples of valid values for the key `color`.

**YAML:**

Empty/null value:

- `color: `

Any valid CSS color name (quoted or unquoted):

- `color: blue`
- `color: "blue"`

Quoted hexadecimal color (case insensitive):

- `color: "#034AD8"`
- `color: "#034ad8"`
- `color: "#034AD8FF"`

RGB and RGBA (quoted or unquoted):

- `color: rgb(3, 74, 216)`
- `color: "rgb(3, 74, 216)"`
- `color: rgba(3, 74, 216, 0.5)`
- `color: "rgba(3, 74, 216, 0.5)"`

HSL and HSLA (quoted or unquoted):

- `color: hsl(220, 97.3, 42.9)`
- `color: "hsl(220, 97.3, 42.9)"`
- `color: hsla(220, 97.3, 42.9, 0.5)`
- `color: "hsla(220, 97.3, 42.9, 0.5)"`

HSV and HSVA (quoted or unquoted):

- `color: hsv(220, 98.6, 84.7)`
- `color: "hsv(220, 98.6, 84.7)"`
- `color: hsva(220, 98.6, 84.7, 0.5)`
- `color: "hsva(220, 98.6, 84.7, 0.5)"`

**TOML:**

Any valid CSS color name:

- `color = "blue"`

Hexadecimal color (case insensitive):

- `color = "#034AD8"`
- `color = "#034ad8"`
- `color = "#034AD8FF"`

RGB and RGBA:

- `color = "rgb(3, 74, 216)"`
- `color = "rgba(3, 74, 216, 0.5)"`

HSL and HSLA:

- `color = "hsl(220, 97.3, 42.9)"`
- `color = "hsla(220, 97.3, 42.9, 0.5)"`

HSV and HSVA:

- `color = "hsv(220, 98.6, 84.7)"`
- `color = "hsva(220, 98.6, 84.7, 0.5)"`

**JSON:**

Empty/null value:

- `"color": null`

Any valid CSS color name:

- `"color": "blue"`

Hexadecimal color (case insensitive):

- `"color": "#034AD8"`
- `"color": "#034ad8"`
- `"color": "#034AD8FF"`

RGB and RGBA:

- `"color": "rgb(3, 74, 216)"`
- `"color": "rgba(3, 74, 216, 0.5)"`

HSL and HSLA:

- `"color": "hsl(220, 97.3, 42.9)"`
- `"color": "hsla(220, 97.3, 42.9, 0.5)"`

HSV and HSVA:

- `"color": "hsv(220, 98.6, 84.7)"`
- `"color": "hsva(220, 98.6, 84.7, 0.5)"`

> CloudCannon may alter your input value under the following circumstances:
> 
> - Hex colors with an alpha value will be converted to `rgba`.
> - Colors will be converted to the specified `format` input option when loaded in the Data Editor.
> - Quotes will be stripped from non-hex colors when loaded in the Data Editor.

## Unconfigured Color inputs

In some cases, CloudCannon can still detect a Color input even if you have not configured it.

CloudCannon will interpret any unconfigured input with the key name `color`, `colour`, `rgb`, `rgba`, `hex`, `hsv`, `hsva`, `hsl`, or `hsla`, or that ends in `_color`, `_colour`, `_rgb`, `_rgba`, `_hex`, `_hsv`, `_hsva`, `_hsl`, or `_hsla`, as a Color input. Key name variations ending with "a" will enable the `alpha` option automatically.

File: `about.md`

```Markdown

---
main_hex: "#034AD8"
---

Content goes here.

```

This behavior is convenient if you have simple inputs or do not want to configure inputs. It is also beneficial for new websites on CloudCannon where you have yet to create any CloudCannon-specific configuration.

> We recommend configuring your inputs for greater control over their functionality and appearance.


---

---
title: Configure a Date or Time input
description: Learn how to configure Date and Time inputs to edit date and time values in your data files or front matter.
url: https://cloudcannon.com/documentation/developer-articles/configure-a-date-or-time-input/
content_type: developer article
last_modified: 2026-03-29
---

> **Permissions required**
> 
> Members of all [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `site:file:write` permission, can configure inputs in all locations in the configuration cascade. You can limit permission to specific locations in the configuration using [file globs](/documentation/developer-articles/what-are-custom-permission-groups/#specify-a-file-glob).

[Date and Time inputs](/documentation/user-articles/what-are-date-and-time-inputs/) are editing interfaces for date and time values. By configuring your inputs, you can customize the appearance and functionality for a better editing experience.

![A screenshot of the Datetime input in the Data Editor shows an open calendar widget under the date text field.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Datetime-Input-Open.webp)

These instructions assume that you know what type of Date or Time input you want to configure and where in the configuration cascade. For more information, please read our documentation on [Date and Time inputs](/documentation/user-articles/what-are-date-and-time-inputs/), [inputs](/documentation/user-articles/what-are-inputs/) in general, and the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

To configure a Date or Time input:

1. Open your website files in your local development environment, or log in to CloudCannon and select the Site for which you want to configure your input.
2. Navigate to the location in the configuration cascade where you want to configure your input. This can be the root of your CloudCannon Configuration File, within the `collections_config.*` key in your CloudCannon Configuration File, a Schema file, the frontmatter of a markup file, or any where you configure a Structure.
3. Identify the `_inputs` key, or create one at that level of the configuration cascade.
4. Add an input name key for your input under the `_inputs` key (a.k.a., `_inputs.*`). We recommend naming your input something simple that indicates the function or context.
5. Add the `type` key under your input name key, with the value `datetime`, `date`, or `time`.
6. (Optional.) Add any other general configuration keys (e.g., `label`, `comment`, `context`) under your input name key.
7. (Optional.) Add any specific configuration keys under `_inputs.*.options` (e.g., `timezone`, `start_from`, `end_before`).

CloudCannon will now apply this input configuration to all markup files that use your input name key, without needing to save your configuration. This allows you to make changes to your input configuration and see those changes affect inputs live.

When you are happy with your input configuration, you must save your input configuration.

File: `cloudcannon.config.yml`

```YAML
```

_inputs___1___:
  published___2___:
    type___3___: datetime
  due___4___:
    type___5___: date
  event_opens___6___:
    type___7___: time

```

**[1]** All inputs are defined under the `_inputs` key, regardless of where they are in the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

**[2]** This Datetime input is called `published`.

**[3]** The value of the `type` key determines the input type. This is a `datetime` input.

**[4]** This Date input is called `due`.

**[5]** The value of the `type` key determines the input type. This is a `date` input.

**[6]** This Time input is called `event_opens`.

**[7]** The value of the `type` key determines the input type. This is a `time` input.
```

When you add your input key name to a data or markup file, your configured Date or Time input will appear in the Data Editor, Visual Editor, or Content Editor.

File: `data.yml`

```YAML

published: 2024-07-16T12:00:00Z
due: 2024-07-16T00:00:00Z
event_opens: 12:00 pm

```

> Even though the Date input does not display the time, CloudCannon will automatically add `00:00:00` to the end of Date values, separated by a "T" character. This is for consistency with Datetime inputs, and to store timezone information necessary for determining the current date.

## Input configuration options

General configuration options are available for all input types. You can define the label, comment, and context box for your Date and Time input, whether it is hidden or disabled, and how CloudCannon should handle configuration at multiple levels of the configuration cascade.

Specific configuration options for Date and Time inputs include defining the timezone and how CloudCannon handles empty values. You can also add input validation to require a value, or specify a valid date range.

Here is an example of a Datetime input using some of the most commonly used configuration keys.

File: `cloudcannon.config.yml`

```YAML

_inputs:
  event_datetime:
    type: datetime
    label: Event Date and Time
    comment: Select when the event will occur
    options:
      timezone: America/New_York
      required: true
      start_from: 2024-01-01T00:00:00Z
      end_before: 2025-01-01T00:00:00Z

```

For a complete list of configuration keys available for inputs please read our [Inputs](/documentation/developer-reference/configuration-file/types/_inputs/) reference documentation.

These keys configure the appearance and functionality of Date and Time inputs in CloudCannon.

**`_inputs.*.options.timezone`** String

This key determines which timezone to use when displaying and editing dates. This will also change the suffix of the date value. Defaults to the `timezone` configured in your [CloudCannon Configuration File](/documentation/developer-articles/create-your-cloudcannon-configuration-file/), which defaults to `Etc/UTC`.

Values must be in [tz database name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) format (e.g. `Pacific/Auckland` or `America/New_York`).

Available for Datetime and Date inputs only.

**`_inputs.*.options.empty_type`** string

This key determines how CloudCannon handles an empty value. This key does not apply to existing empty values.

Value must be one of the following:

- `string` - an empty value for this input will be stored as `""`.
- `null` - an empty value for this input will be stored as a null value (default). This does not apply to TOML files.

**`_inputs.*.options.required`** Boolean

This key toggles whether CloudCannon requires this Input to have a value. If set to `true`, CloudCannon will require you to enter a value to save your changes, or discard your unsaved changes.

By default, this key is `false` (i.e, CloudCannon does not require this Input to have a value).

This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.

In this example, we want to require our team to enter an `author` value for markup files with this Input.

File: `cloudcannon.config.yml`

```YAML
  _inputs:
    author:
      type: text
      comment: Enter the name of the author for this blog post.
      options:
        required: true

```

**`_inputs.*.options.required_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.required`. This key requires you to define `options.required`.

This key has no default.

This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to use enter an Input value using a required message.

File: `cloudcannon.config.yml`

```YAML
  _inputs:
    author:
      type: text
      comment: Enter the name of the author for this blog post.
      options:
        required: true
        required_message: You are not allowed to leave this blank.

```

**`_inputs.*.options.start_from`** Date

This key defines the earliest date and time, inclusive, that CloudCannon will allow in an Input. When configured, CloudCannon will prevent you from selecting an earlier date and time. If the Input already contains an earlier date and time, CloudCannon will require you to change it to a valid value to save your changes, or discard your unsaved changes.

Value must be in [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. If `options.end_before` is also configured, this key cannot be a later date and time.

This key has no default.

This key is available for Date and Time Inputs.

In this example, we want our team to enter the date and time of an event in the `2022_event` Input. This Input will only allow dates on or after January 1st, 2022.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  2022_event:
    type: datetime
    options:
      start_from: 2022-01-01T00:00:00Z
      end_before: 2023-01-01T00:00:00Z
```

**`_inputs.*.options.start_from_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.start_from`. This key requires you to define `options.start_from`.

This key has no default.

This key is available for Date and Time Inputs.

In this example, we prompt our team to enter a valid date using a custom message.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  2022_event:
    type: datetime
    options:
      start_from: 2022-01-01T00:00:00Z
      start_from_message: Date is too early. Must be during 2022.
      end_before: 2023-01-01T00:00:00Z
      end_before_message: Date is too late. Must be during 2022.
```

**`_inputs.*.options.end_before`** Date

This key defines the date and time, exclusive, that CloudCannon will allow in an Input. When configured, CloudCannon will prevent you from selecting a later date and time. If the Input already contains a  later date and time, CloudCannon will require you to change it to a valid value to save your changes, or discard your unsaved changes.

Value must be in [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. If `options.start_from` is also configured, this key cannot be an earlier date and time.

This key has no default.

This key is available for Date and Time Inputs.

In this example, we want our team to enter the date and time of an event in the `2022_event` Input. This Input will only allow dates before January 1st, 2023.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  2022_event:
    type: datetime
    options:
      start_from: 2022-01-01T00:00:00Z
      end_before: 2023-01-01T00:00:00Z
```

**`_inputs.*.options.end_before_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.end_before`. This key requires you to define `options.end_before`.

This key has no default.

This key is available for Date and Time Inputs.

In this example, we prompt our team to enter a valid date using a custom message.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  2022_event:
    type: datetime
    options:
      start_from: 2022-01-01T00:00:00Z
      start_from_message: Date is too early. Must be during 2022.
      end_before: 2023-01-01T00:00:00Z
      end_before_message: Date is too late. Must be during 2022.
```

## Valid values

Here are some examples of valid values for Date and Time inputs.

**YAML:**

Empty/null value:

- `datetime: `
- `time: `

Empty string:

- `datetime: ""`
- `datetime: ''`
- `time: ""`
- `time: ''`

ISO 8601 formatted datetime (quoted or unquoted):

- `datetime: 2020-07-15T12:00:00Z`
- `datetime: '2020-07-15T12:00:00Z'`
- `datetime: "2020-07-15T12:00:00Z"`

12hr time (quoted or unquoted):

- `time: 1:23 pm`
- `time: '1:23 pm'`
- `time: "1:23 pm"`

24hr time (quoted or unquoted):

- `time: 13:23:00`
- `time: '13:23:00'`
- `time: "13:23:00"`

**TOML:**

Empty string:

- `datetime = ""`
- `datetime = ''`
- `time = ""`
- `time = ''`

ISO 8601 formatted datetime (quoted or unquoted):

- `datetime = 2020-07-15T12:00:00Z`
- `datetime = "2020-07-15T12:00:00Z"`
- `datetime = '2020-07-15T12:00:00Z'`

ISO 8601 formatted datetime with space instead of `T` (quoted or unquoted):

- `datetime = 2020-07-15 12:00:00Z`
- `datetime = "2020-07-15 12:00:00Z"`

The space will be converted to a T when loaded into the Data Editor.

12hr time:

- `time = "1:23 pm"`
- `time = '1:23 pm'`

24hr time:

- `time = "13:23:00"`
- `time = '13:23:00'`

**JSON:**

Null value:

- `"datetime": null`
- `"time": null`

Empty string:

- `"datetime": ""`
- `"time": ""`

ISO 8601 formatted datetime:

- `"datetime": "2020-07-15T12:00:00Z"`

12hr time:

- `"time": "1:23 pm"`

24hr time:

- `"time": "13:23:00"`

> CloudCannon may alter your input value under the following circumstances:
> 
> - When loaded in the Data Editor, date, time, and datetime inputs surrounded by quotation marks will be automatically unquoted.
> - When loaded in the Data Editor, 24hr times will be converted to 12hr times.

## Unconfigured Date and Time inputs

In some cases, CloudCannon can still detect a Date or Time input even if you have not configured it.

CloudCannon will interpret any unconfigured input with the key name:

- `datetime` or `at`, or that ends in `_datetime` or `_at`, as a Datetime input.
- `date`, or that ends in `_date`, as a Date input.
- `time`, or that ends in `_time`, as a Time input.

File: `about.md`

```Markdown

---
at: 2024-07-16T12:00:00Z
---

Content goes here.

```

This behavior is convenient if you have simple inputs or do not want to configure inputs. It is also beneficial for new websites on CloudCannon where you have yet to create any CloudCannon-specific configuration.

> We recommend configuring your inputs for greater control over their functionality and appearance.


---

---
title: Configure a File input
description: Learn how to configure a File input to edit file paths or links to external files in your data files or front matter.
url: https://cloudcannon.com/documentation/developer-articles/configure-a-file-input/
content_type: developer article
last_modified: 2026-03-29
---

> **Permissions required**
> 
> Members of all [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `site:file:write` permission, can configure inputs in all locations in the configuration cascade. You can limit permission to specific locations in the configuration using [file globs](/documentation/developer-articles/what-are-custom-permission-groups/#specify-a-file-glob).

A [File input](/documentation/user-articles/what-is-a-file-input/) is an editing interface for file paths, allowing you to upload a file to your repository or [DAM](/documentation/developer-articles/integrating-your-dam-with-cloudcannon/), or add links to external files. By configuring your inputs, you can customize the appearance and functionality for a better editing experience.

![A screenshot of the Image Input in the Data Editor shows a preview for the selected image file.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Image-Input.webp)

These instructions assume that you know what type of File input you want to configure and where in the configuration cascade. For more information, please read our documentation on [File inputs](/documentation/user-articles/what-is-a-file-input/), [inputs](/documentation/user-articles/what-are-inputs/) in general, and the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

To configure a File input:

1. Open your website files in your local development environment, or log in to CloudCannon and select the Site for which you want to configure your input.
2. Navigate to the location in the configuration cascade where you want to configure your input. This can be the root of your CloudCannon Configuration File, within the `collections_config.*` key in your CloudCannon Configuration File, a Schema file, the frontmatter of a markup file, or any where you configure a Structure.
3. Identify the `_inputs` key, or create one at that level of the configuration cascade.
4. Add an input name key for your input under the `_inputs` key (a.k.a., `_inputs.*`). We recommend naming your input something simple that indicates the function or context.
5. Add the `type` key under your input name key, with the value `file`, `document`, or `image`.
6. (Optional.) Add any other general configuration keys (e.g., `label`, `comment`, `context`) under your input name key.
7. (Optional.) Add any specific configuration keys under `_inputs.*.options` (e.g., `paths`, `accepts_mime_types`, `allowed_sources`).

CloudCannon will now apply this input configuration to all markup files that use your input name key, without needing to save your configuration. This allows you to make changes to your input configuration and see those changes affect inputs live.

When you are happy with your input configuration, you must save your input configuration.

File: `cloudcannon.config.yml`

```YAML
```

_inputs___1___:
  example_css___2___:
    type___3___: file
  download_newsletter___4___:
    type___5___: document
  logo___6___:
    type___7___: image

```

**[1]** All inputs are defined under the `_inputs` key, regardless of where they are in the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

**[2]** This File input is called `example_css`.

**[3]** The value of the `type` key determines the input type. This is a `file` input.

**[4]** This Document input is called `download_newsletter`.

**[5]** The value of the `type` key determines the input type. This is a `document` File input.

**[6]** This Image input is called `logo`.

**[7]** The value of the `type` key determines the input type. This is a `image` File input.
```

When you add your input key name to a data or markup file, your configured File input will appear in the Data Editor, Visual Editor, or Content Editor.

File: `data.yml`

```YAML

example_css: /guides/tutorial-styles.css
download_newsletter: /newsletters/july-2024.pdf
logo: /web-assets/logo.png

```

## Input configuration options

General configuration options are available for all input types. You can define the label, comment, and context box for your File input, whether it is hidden or disabled, and how CloudCannon should handle configuration at multiple levels of the configuration cascade.

Specific configuration options for File inputs include defining the default path for uploading assets, which MIME types an input will accept, which DAMs you can upload to and browse, and how CloudCannon handles empty values. You can also add input validation to require a value, specify the minimum and maximum value length, maximum file size, or match a regular expression. For inputs that accept images, you can configure how CloudCannon resizes images, MIME type, and whether CloudCannon creates additional images of different sizes when you upload a new asset.

Here is an example of a File input using some of the most commonly used configuration keys.

File: `cloudcannon.config.yml`

```YAML

_inputs:
  image:
    type: image
    label: Featured Image
    comment: Upload or select an image for this post
    options:
      path:
        uploads: images
      accepts_mime_types:
        - image/png
        - image/jpeg
      allowed_sources:
        - site-files
      required: true
      max_file_size: 5242880
      pattern: (?i)\.(jpe?g|png)$
      pattern_message: Please select a JPG or PNG image file

```

For a complete list of configuration keys available for inputs please read our [Inputs](/documentation/developer-reference/configuration-file/types/_inputs/) reference documentation.

These keys configure the appearance and functionality of File inputs in CloudCannon.

**`_inputs.*.options.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_path`

This key has no default. If undefined at higher levels of the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/), `paths` will default to any values configured in the [CloudCannon configuration file](/documentation/developer-articles/what-is-the-cloudcannon-configuration-file/).

For more information, please read our documentation on [Rich Text editors](/documentation/developer-articles/what-are-rich-text-editors/) or [File inputs](/documentation/user-articles/what-is-a-file-input/).

**`_inputs.*.options.path.dam_static`** String

This key enables you to define the path for the location of statically copied assets for [DAM](/documentation/developer-articles/introduction-to-assets-and-dams/) files.

**`_inputs.*.options.path.dam_uploads`** String

This key enables you to define the path for the default location of newly uploaded [DAM](/documentation/developer-articles/introduction-to-assets-and-dams/) files.

You can use [dynamic placeholders](/documentation/developer-articles/configure-your-template-strings/) for `uploads` and `dam_uploads`. For more information, please read our documentation on [adjusting file upload paths](/documentation/developer-articles/adjusting-the-uploads-path/).

**`_inputs.*.options.path.dam_uploads_filename`** String

This key enables you to define the name of a file, after uploading it to a [DAM](/documentation/developer-articles/introduction-to-assets-and-dams/).

**`_inputs.*.options.path.static`** String

This key enables you to define the path for the location of statically copied assets.

**`_inputs.*.options.path.uploads`** String

This key enables you to define the path for the default location of newly uploaded files.

You can use [dynamic placeholders](/documentation/developer-articles/configure-your-template-strings/) for `uploads` and `dam_uploads`. For more information, please read our documentation on [adjusting file upload paths](/documentation/developer-articles/adjusting-the-uploads-path/).

**`_inputs.*.options.path.uploads_filename`** String

This key enables you to define the name of a file, after uploading it.

**`_inputs.*.options.path.uploads_use_relative_path`** Boolean

This key enables you to use a file path relative to the current file when uploading through this input. File inputs in data files or front matter will also use relative file paths when selecting an existing file.

**`_inputs.*.options.accepts_mime_types`** String or array of strings

This key restricts which file types you are allowed to select or upload through an input. Each File input type has a different default:

- File: `*`
- Image: `image/x-icon,image/gif,image/jpeg,image/png,image/webp,image/bmp,image/svg+xml`
- Document: `application/pdf,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document,application/vnd.ms-excel,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet,application/vnd.ms-powerpoint,application/vnd.openxmlformats-officedocument.presentationml.presentation`

If this key uses a string value, the value format should be a comma-separated (no spaces) list of accepted [MIME types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types). The string `*` allows any type.

If this key uses an array of values, each item in the array should be a string containing a single accepted [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types).

**`_inputs.*.options.allowed_sources`** Array

This key lists which DAMs you are allowed to upload to and browse. Valid values include `site-files` and the reference key for any DAM connected to your site.

If `site-files` is omitted from the array, site files will not be available as an asset source for this input.

**`_inputs.*.options.empty_type`** String

This key determines how CloudCannon handles an empty value. This key does not apply to existing empty values.

Value must be one of the following:

- `string` - an empty value for this input will be stored as "".
- `null` - an empty value for this input will be stored as a null value (default). This does not apply to TOML files.

**`_inputs.*.options.disable_upload_file`** Boolean

This key toggles whether CloudCannon shows the "Upload a new file" option in the "Add URL" dropdown menu on a URL Input or "Add file" dropdown menu on a File Input. When set to `true`, the "Upload a new file" option is not available.

By default, this key is `false` (i.e., users can upload files).

In this example, we have a `logo` Image input where users can only select existing images but cannot upload new ones.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  logo:
    type: image
    label: Company Logo
    options:
      disable_upload_file: true
```

**`_inputs.*.options.disable_direct_input`** Boolean

This key toggles whether you can type in the text field of a File Input or URL Input. When set to `true`, you cannot manually type or paste values into the input text field.

By default, this key is `false` (i.e., users can type directly into the input field).

In this example, we have a `document` File input where users must select files through the File Browser and cannot manually type file paths.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  document:
    type: document
    label: PDF Document
    options:
      disable_direct_input: true
```

**`_inputs.*.options.disable_upload_file_in_file_browser`** Boolean

This key toggles whether the "Add" button in the top right of the File browser modal is available, after selecting the "Link to existing file" option in the "Add URL" dropdown menu on a URL Input or "Add file" dropdown menu on a File Input. When set to `true`, the "Link to existing file" option is not available.

By default, this key is `false` (i.e., users can upload files in the File browser modal).

In this example, we have a `background_image` Image input where users can upload files using the "Upload a new file" option in the "Add URL" dropdown menu on a URL Input or "Add file" dropdown menu on a File Input, but not from within the File browser modal.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  background_image:
    type: image
    label: Background Image
    options:
      disable_upload_file_in_file_browser: true
```

**`_inputs.*.options.required`** Boolean

This key toggles whether CloudCannon requires this Input to have a value. If set to `true`, CloudCannon will require you to enter a value to save your changes, or discard your unsaved changes.

By default, this key is `false` (i.e, CloudCannon does not require this Input to have a value).

This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.

In this example, we want to require our team to enter an `author` value for markup files with this Input.

File: `cloudcannon.config.yml`

```YAML
  _inputs:
    author:
      type: text
      comment: Enter the name of the author for this blog post.
      options:
        required: true

```

**`_inputs.*.options.required_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.required`. This key requires you to define `options.required`.

This key has no default.

This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to use enter an Input value using a required message.

File: `cloudcannon.config.yml`

```YAML
  _inputs:
    author:
      type: text
      comment: Enter the name of the author for this blog post.
      options:
        required: true
        required_message: You are not allowed to leave this blank.

```

**`_inputs.*.options.max_length`** Number

This key defines the maximum string length, in characters, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.

Value can be any non-negative integer. If this key is set to `0`, CloudCannon requires the Input to be empty. If `options.min_length` is also configured, this key cannot be a smaller number.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, `allow_create` must be set to `true`.

In this example, we want our team to enter a blog description using the Rich Text `seo_description` Input. This Input limits you to a maximum of 125 characters.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      min_length: 25
```

**`_inputs.*.options.max_length_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.max_length`. This key requires you to define `options.max_length`.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to enter a valid number of characters using a custom message.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      max_length_message: You are only allowed 125 characters.
      min_length: 25
      min_length_message: Please write more than 25 characters.
```

**`_inputs.*.options.min_length`** Number

This key defines the minimum string length, in characters, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.

Value can be any positive integer. If `options.max_length` is also configured, this key cannot be a greater number.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, `allow_create` must be set to `true`.

In this example, we want our team to enter a blog description using the Rich Text `seo_description` Input. This Input requires a minimum of 25 characters.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      min_length: 25
```

**`_inputs.*.options.min_length_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.min_length`. This key requires you to define `options.min_length`.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to enter a valid number of characters using a custom message.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      max_length_message: You are only allowed 125 characters.
      min_length: 25
      min_length_message: Please write more than 25 characters.
```

**`_inputs.*.options.pattern`** String

This key defines a [regular expression](https://re2js.leopard.in.ua/) that the Input value must match. When configured, CloudCannon will require you to enter a value that matches the REGEX pattern. If the Input already contains an invalid value, CloudCannon will require you to enter a valid string to save your changes, or discard your unsaved changes.

Value must be a valid REGEX string. If your REGEX string includes a `\` character and CloudCannon Configuration File is a `.yml` file, use single quotes `'` around the string to avoid a build error.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, `allow_create` must be set to `true`.

In this example, we want our team to add an email address to the `contact_email` Input using the correct email format.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  contact_email:
    type: email
    options:
      pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
      pattern_message: 'Please use the format ___@___.__'
```

**`_inputs.*.options.pattern_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.pattern`. This key requires you to define `options.pattern`.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to use the correct email format in the `contact_email` Input using a pattern message.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  contact_email:
    type: email
    options:
      pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
      pattern_message: 'Please use the format ___@___.__'
```

If the input accepts images, the following options are also available:

**`resize_style`** String

This key determines how CloudCannon resizes images prior to uploading them to your repository or DAM. CloudCannon resizes images using a bounding box defined by the `width` and `height` options. Defaults to `contain`, if `width` and `height` are defined.

Value must be one of the following:

- `crop` — Prompts the user to choose a region of the image that matches the dimensions of the bounding box.
- `cover` — Keeps the original aspect ratio of the uploaded image but enlarges the image to match the largest dimension of the bounding box.
- `contain` — Keeps the original aspect ratio of the uploaded image but reduces the image to match the smallest dimension of the bounding box.
- `stretch` — Ignores the original aspect ratio and resizes the image to match the dimensions of the bounding box.

If either `width` or `height` are not defined, the `contain`, `cover` and `stretch` options will not work. For the `crop`option, `width` and `height` are optional, and control the minimum size and aspect ratio of the crop region.

**`width`** Integer

This key determines the width of the bounding box CloudCannon uses to resize images prior to upload. Works in conjunction with the `resize_style` option.

**`height`** Integer

This key determines the height of the bounding box CloudCannon uses to resize images prior to upload. Works in conjunction with the `resize_style` option.

**`mime_type`** String

This key determines what format CloudCannon will convert an image to prior to uploading it. CloudCannon also updates the file extension. Defaults to keeping an image's original MIME type.

Value must be one of:

- `image/jpeg`
- `image/png`
- `image/webp`

**`expandable`** Boolean

This key determines whether you can expand an image to fit the bounding box when resizing an image prior to upload. Defaults to `false`. Has no effect if files are not resized.

**`prevent_resize_existing_files`** Boolean

This key determines whether CloudCannon will prompt you to resize an existing image when you select it through this input. Defaults to false.

When resizing an existing image, CloudCannon will save the resized copy without overwriting the original file.

**`sizes`** Array of objects

This key determines whether CloudCannon will create additional images of different sizes  when uploading or selecting an image through this input. This key has no default.

Each entry in the array contains the following fields:

- `size` — Set the dimensions for the additional image file. Value must be a number with the "x" suffix for relative size or "w" suffix for fixed width (e.g., 2x, 3x, 100w, 360w).
- `target` — References another input. CloudCannon sets the value of this target input to the file path of the additional image file.

If CloudCannon cannot create an additional image (e.g., the image you uploaded is too small), CloudCannon does not set the value of the target input.

## Valid values

Here are some examples of valid values for the key `file`. These work for File, Document, and Image inputs.

**YAML:**

Empty/null value:

- `file: `

Any valid string (quoted or unquoted):

- `file: ""`
- `file: ''`
- `file: path/to/file.ext`
- `file: "path/to/file.ext"`
- `file: 'path/to/file.ext'`

**TOML:**

Any valid string:

- `file = ""`
- `file = ''`
- `file = "path/to/file.ext"`
- `file = 'path/to/file.ext'`

**JSON:**

Null value:

- `"file": null`

Any valid string:

- `"file": ""`
- `"file": "path/to/file.ext"`

## Unconfigured File inputs

In some cases, CloudCannon can still detect a File input even if you have not configured it.

CloudCannon will interpret any unconfigured input with the key name:

- `path`, or that ends in `_path`, as a File input.
- `document` or `document_path`, or that ends in `_document` or `_document_path`, as a Document input.
- `image` or `image_path`, or that ends in `_image` or `_image_path`, as an Image input.

File: `data.yml`

```YAML

background_image: /images/forest.jpeg

```

This behavior is convenient if you have simple inputs or do not want to configure inputs. It is also beneficial for new websites on CloudCannon where you have yet to create any CloudCannon-specific configuration.

> We recommend configuring your inputs for greater control over their functionality and appearance.


---

---
title: Configure a Number input
description: Learn how to configure a Number input to edit numeric values in your data files or front matter.
url: https://cloudcannon.com/documentation/developer-articles/configure-a-number-input/
content_type: developer article
last_modified: 2026-03-29
---

> **Permissions required**
> 
> Members of all [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `site:file:write` permission, can configure inputs in all locations in the configuration cascade. You can limit permission to specific locations in the configuration using [file globs](/documentation/developer-articles/what-are-custom-permission-groups/#specify-a-file-glob).

A [Number input](/documentation/user-articles/what-is-a-number-input/) is an editing interface for numeric values. By configuring your inputs, you can customize the appearance and functionality for a better editing experience.

![A screenshot of the Number Input in the Data Editor shows a text field and arrows to increase or decrease the value.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Number-Input.webp)

![A screenshot of the Range Input in the Data Editor shows a bar with a draggable circle.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Range-Input.webp)

These instructions assume that you know where in the configuration cascade you want to configure your input. For more information, please read our documentation on [Number inputs](/documentation/user-articles/what-is-a-number-input/), [inputs](/documentation/user-articles/what-are-inputs/) in general, and the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

To configure a Number input:

1. Open your website files in your local development environment, or log in to CloudCannon and select the Site for which you want to configure your input.
2. Navigate to the location in the configuration cascade where you want to configure your input. This can be the root of your CloudCannon Configuration File, within the `collections_config.*` key in your CloudCannon Configuration File, a Schema file, the frontmatter of a markup file, or any where you configure a Structure.
3. Identify the `_inputs` key, or create one at that level of the configuration cascade.
4. Add an input name key for your input under the `_inputs` key (a.k.a., `_inputs.*`). We recommend naming your input something simple that indicates the function or context.
5. Add the `type` key under your input name key, with the value `number` or `range`.
6. (Optional.) Add any other general configuration keys (e.g., `label`, `comment`, `context`) under your input name key.
7. If your input is a `range`, you must define the `max`, `min`, and `step` keys under `_inputs.*.options`.
8. (Optional.) Add any other specific configuration keys under `_inputs.*.options` (e.g., `required`).

CloudCannon will now apply this input configuration to all markup files that use your input name key, without needing to save your configuration. This allows you to make changes to your input configuration and see those changes affect inputs live.

When you are happy with your input configuration, you must save your input configuration.

File: `cloudcannon.config.yml`

```YAML
```

_inputs___1___:
  step___2___:
    type___3___: number
  priority___4___:
    type___5___: range

```

**[1]** All inputs are defined under the `_inputs` key, regardless of where they are in the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

**[2]** This Number input is called `step`.

**[3]** The value of the `type` key determines the input type. This is a `number` input.

**[4]** This Range input is called `priority`.

**[5]** The value of the `type` key determines the input type. This is a `range` input.
```

When you add your input key name to a data or markup file, your configured Number input will appear in the Data Editor, Visual Editor, or Content Editor.

File: `data.yml`

```YAML

step: 4
priority: 10

```

## Input configuration options

General configuration options are available for all input types. You can define the label, comment, and context box for your Number input, whether it is hidden or disabled, and how CloudCannon should handle configuration at multiple levels of the configuration cascade.

Specific configuration options for Number inputs include defining the step size and how CloudCannon handles empty values. You can also add input validation to require a value and specify the minimum and maximum value.

Here is an example of a Number input using some of the most commonly used configuration keys.

File: `cloudcannon.config.yml`

```YAML

_inputs:
  available:
    type: range
    label: Product Quantity
    comment: Enter the number of items in stock
    options:
      min: 0
      max: 1000
      step: 1
      required: true

```

For a complete list of configuration keys available for inputs please read our [Inputs](/documentation/developer-reference/configuration-file/types/_inputs/) reference documentation.

These keys configure the appearance and functionality of Number inputs in CloudCannon.

**`_inputs.*.options.required`** Boolean

This key toggles whether CloudCannon requires this Input to have a value. If set to `true`, CloudCannon will require you to enter a value to save your changes, or discard your unsaved changes.

By default, this key is `false` (i.e, CloudCannon does not require this Input to have a value).

This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.

In this example, we want to require our team to enter an `author` value for markup files with this Input.

File: `cloudcannon.config.yml`

```YAML
  _inputs:
    author:
      type: text
      comment: Enter the name of the author for this blog post.
      options:
        required: true

```

**`_inputs.*.options.required_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.required`. This key requires you to define `options.required`.

This key has no default.

This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to use enter an Input value using a required message.

File: `cloudcannon.config.yml`

```YAML
  _inputs:
    author:
      type: text
      comment: Enter the name of the author for this blog post.
      options:
        required: true
        required_message: You are not allowed to leave this blank.

```

**`_inputs.*.options.max`** Number

This key defines the maximum numerical value CloudCannon will allow in an Input. When configured, CloudCannon will prevent you from entering a greater numerical value. If the Input already contains a greater numerical value, CloudCannon will require you to enter a valid value to save your changes, or discard your unsaved changes. This key is required for `range` inputs.

Value can be any integer. If `options.min` is also configured, this key cannot be a lesser number.

This key has no default.

This key is available for Number Inputs.

In this example, we want to add a rating out of five for each article in our travel blog using the `rating` Input. This Input limits you to a maximum rating of five.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  rating:
    type: number
    comment: How highly did you rate this experience?
    options:
      max: 5
      min: 1
```

**`_inputs.*.options.max_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.max`. This key requires you to define `options.max`.

This key has no default.

This key is available for Number Inputs.

In this example, we prompt our team to enter a valid number using a custom message.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  rating:
    type: number
    comment: How highly did you rate this experience?
    options:
      max: 5
      max_message: Cannot be more than 5
      min: 1
      min_message: Cannot be less than 1
```

**`_inputs.*.options.min`** Number

This key defines the minimum numerical value CloudCannon will allow in an Input. When configured, CloudCannon will prevent you from entering a lesser numerical value. If the Input already contains a lesser numerical value, CloudCannon will require you to enter a valid value to save your changes, or discard your unsaved changes. This key is required for `range` inputs.

Value can be any integer. If `options.max` is also configured, this key cannot be a greater number.

This key has no default.

This key is available for Number Inputs.

In this example, we want to add a rating out of five for each article in our travel blog using the `rating` Input. This Input limits you to a minimum rating of one.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  rating:
    type: number
    comment: How highly did you rate this experience?
    options:
      max: 5
      min: 1
```

**`_inputs.*.options.min_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.min`. This key requires you to define `options.min`.

This key has no default.

This key is available for Number Inputs.

In this example, we prompt our team to enter a valid number using a custom message.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  rating:
    type: number
    comment: How highly did you rate this experience?
    options:
      max: 5
      max_message: Cannot be more than 5
      min: 1
      min_message: Cannot be less than 1
```

**`_inputs.*.options.step`** Float or "any"

This key determines how granular changes to the value can be. This key is required for `range` inputs

Value must be either:

- a number.
- `any`, which allows any decimal value between `max` and `min` values.

**`_inputs.*.options.empty_type`** string

This key determines how CloudCannon handles an empty value. This key does not apply to existing empty values.

Value must be one of the following:

- `string` - an empty value for this input will be stored as "".
- `null` - an empty value for this input will be stored as a null value (default). This does not apply to TOML files.

## Valid values

Here are some examples of valid values for the key `number`. These work for both Number and Range inputs.

**YAML:**

Empty/null value:

- `number: `

Whole base-10 integers (unquoted):

- `number: 123456`
- `number: -123456`
- `number: 123456e78`
- `number: 123456e+78`
- `number: 123456e-78`

Floating point numbers (unquoted):

- `number: 123.456`
- `number: -123.456`
- `number: 123.456e78`
- `number: 123.456e+78`
- `number: 123.456e-78`

Binary integers (unquoted):

- `number: 0b11110001001000000`

Hexadecimal integers (unquoted):

- `number: 0x1E240`

**TOML:**

Whole base-10 integers (unquoted):

- `number = 12346`
- `number = +123456`
- `number = -123456`
- `number = 123_456`

Floating point numbers (unquoted):

- `number = 123.456`
- `number = +123.456`
- `number = -123.456`
- `number = 123.456e78`
- `number = 123.456E78`
- `number = 123.456e09`
- `number = 123.456e+78`
- `number = 123.456e-78`
- `number = -123.456e78`
- `number = 123_456.789_012`

Hexadecimal numbers (unquoted):

- `number = 0x1E240`

Octal numbers (unquoted):

- `number = 0o361100`

Binary numbers (unquoted):

- `number = 0b11110001001000000`

**JSON:**

Null value:

- `"number": null`

Base-10 integers (unquoted):

- `"number": 123456`
- `"number": -123456`
- `"number": 123456e78`
- `"number": -123456e78`

Floating-point numbers (unquoted):

- `"number": 123.456`
- `"number": -123.456`
- `"number": 123.456e78`
- `"number": 123.456E78`
- `"number": 123.456e+78`
- `"number": -123.456e78`

> When you load a binary and hexadecimal number in the Data Editor, it will be converted to base-10 integers.

## Unconfigured Number inputs

In some cases, CloudCannon can still detect a Number input even if you have not configured it.

CloudCannon will interpret any unconfigured input with a numeric value as a Number input. CloudCannon cannot create a Range input without configuration.

File: `data.yml`

```YAML

page_number: 7
days: 50

```

This behavior is convenient if you have simple inputs or do not want to configure inputs. It is also beneficial for new websites on CloudCannon where you have yet to create any CloudCannon-specific configuration.

> We recommend configuring your inputs for greater control over their functionality and appearance.


---

---
title: Configure a Pull Request template
description: Learn how to configure a Pull Request template for your Site on CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/configure-a-pull-request-template/
content_type: developer article
last_modified: 2026-03-04
---

> **Permissions required**
> 
> Members of the Owners, Developers, or Technical Editors [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `site:source-editor:write` and `site:file:write` permissions, can edit your *CloudCannon Configuration File*. You can limit permission to specific files using [file globs](/documentation/developer-articles/what-are-custom-permission-groups/#specify-a-file-glob).

A [Pull Request template](/documentation/developer-articles/what-is-a-pull-request-template/) allows you to define the default values for the title and body of your Pull Requests. You can also configure any [Inputs](/documentation/user-articles/what-are-inputs/) used by your Pull Request. If you have multiple templates on your *Site*, you can choose which template you want to use when creating a Pull Request.

These instructions assume you use [Pull Requests](/documentation/developer-articles/merging-and-pull-requests/) as the publishing method for your *Site*.

To configure a Pull Request template:

1. Navigate to your *File Browser* and open your *CloudCannon Configuration File* in the Source Editor, or open it in your local development environment.
2. Identify the `pull_request_templates` key, or create one at the root level of your *Configuration File*.
3. Add an array item under the `pull_request_templates` key.
4. (Optional.) Add any other configuration keys (e.g., `label`, `title`, `body`) under your array item.
5. Save your changes.

CloudCannon will update the list of available Pull Request templates on the *Publishing* page.

![A screenshot of the Publishing page shows the Pull Request template dropdown for selecting a template.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Publishing-Page-Create-Pull-Request-with-Template.webp)

## Configuration options

Here is an example of two Pull Request templates using some of the most commonly used configuration keys.

File: `cloudcannon.config.yml`

```yaml
```

pull_request_templates:
  - label___1___: Update content
    _inputs:
      title:
        options:
          required___2___: true
      body:
        type: markdown
        options___3___:
          bold: true
          italic: true
          link: true
          format: p h1 h2 h3
  - label: Delete content
    title: Delete content
    _inputs:
      title:
        options:
          disabled___4___: true
    template_path___5___: .github/templates/delete-content.md

```

**[1]** The name of the first Pull Request template is "Update content", which is visible in the dropdown menu on the *Publishing* page.

**[2]** We have configured the `title` Input in this Pull Request template. CloudCannon will require a value for this Input before you can create the Pull Request.

**[3]** We have configured the `body` Input in this Pull Request template. You can edit the content of the `body` Input using a limited set of Markdown formatting options.

**[4]** We have configured the `title` Input in this Pull Request template. CloudCannon will not allow you to change the value of the `title` Input as the `disabled` option is `true`.

**[5]** We want the `body` field in our Pull Request template to use the content of the `.github/templates/delete-content.md` file by default.
```

These keys configure the Pull Request templates available on your *Site*.

**`pull_request_templates`** Array

This key defines the options for Pull Request templates.

The following nested keys are available for each entry in the `pull_request_templates` array:

- `label`
- `title`
- `body`
- `template_path`
- `_inputs`

This key has no default.

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

File: `cloudcannon.config.yml`

```YAML
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`** String

This key defines the name of a Pull Request template, which appears in the dropdown menu on the *Publishing* page.

This key has no default.

In this example, the name of the Pull Request template in the dropdown menu on the *Publishing* page will be "Content Update".

File: `cloudcannon.config.yml`

```YAML
pull_request_templates:
  - label: Content Update
    title: Updates to...
    body: In this update, I have made the following changes...
```

**`pull_request_templates[*].title`** String

This key defines the default value of the "Title" field in your Pull Request.

This key has no default.

In this example, the `title` field of our Pull Request template is populated by the string "Updates to..." by default.

File: `cloudcannon.config.yml`

```YAML
pull_request_templates:
  - label: Content Update
    title: Updates to...
    body: In this update, I have made the following changes...
```

**`pull_request_templates[*].body`** String

This key defines the default value of the "Body" field in your Pull Request.

This key has no default.

In this example, the `body` field of our Pull Request template is populated by the string "In this update, I have made the following changes..." by default.

File: `cloudcannon.config.yml`

```YAML
pull_request_templates:
  - label: Content Update
    title: Updates to...
    body: In this update, I have made the following changes...
```

**`pull_request_templates[*].template_path`** String

This key defines the path to the file CloudCannon should use as the value of the `body` field in a Pull Request template. This file path must be relative to the root of your repository (i.e., `/`, not the value of `source`). This allows you to create more complex default content for your Pull Request.

CloudCannon will not use the content of this file if the `body` key is also defined for the Pull Request template.

This key has no default.

In this example, the `body` field of our Pull Request template is populated by the contents of `.github/templates/delete-content.md` by default.

File: `cloudcannon.config.yml`

```YAML
pull_request_templates:
  - label: Delete content
    title: Delete content
    _inputs:
      title:
        disabled: true
    template_path: .github/templates/delete-content.md
```

**`pull_request_templates[*]._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`
- `*.disabled`
- `*.instance_value`
- `*.cascade`
- `*.options`

This key has no default. If undefined at higher levels of the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/), `_inputs` will default to any values configured in the [CloudCannon configuration file](/documentation/developer-articles/what-is-the-cloudcannon-configuration-file/).


---

---
title: Configure a Rich Text input
description: Learn how to configure a Rich Text input to edit HTML or Markdown content in your data files or front matter.
url: https://cloudcannon.com/documentation/developer-articles/configure-a-rich-text-input/
content_type: developer article
last_modified: 2026-03-29
---

> **Permissions required**
> 
> Members of all [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `site:file:write` permission, can configure inputs in all locations in the configuration cascade. You can limit permission to specific locations in the configuration using [file globs](/documentation/developer-articles/what-are-custom-permission-groups/#specify-a-file-glob).

A [Rich Text input](/documentation/user-articles/what-is-a-rich-text-input/) is an editing interface for markup content. By configuring your inputs, you can customize the appearance and functionality for a better editing experience.

![A screenshot of the Markdown input in the Data Editor shows a text field and a WYSIWYG toolbar.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Markdown-Input.webp)

You can configure the WYSIWYG toolbar for a Rich Text input in the same way you configure the toolbar for the [Content Editor](/documentation/user-articles/what-is-the-content-editor/). For more information, please read our documentation on [configuring your Rich Text editors](/documentation/developer-articles/configure-your-rich-text-editors/).

These instructions assume that you know where in the configuration cascade you want to configure your input. For more information, please read our documentation on [Rich Text inputs](/documentation/user-articles/what-is-a-rich-text-input/), [inputs](/documentation/user-articles/what-are-inputs/) in general, and the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

To configure a Rich Text input:

1. Open your website files in your local development environment, or log in to CloudCannon and select the Site for which you want to configure your input.
2. Navigate to the location in the configuration cascade where you want to configure your input. This can be the root of your CloudCannon Configuration File, within the `collections_config.*` key in your CloudCannon Configuration File, a Schema file, the frontmatter of a markup file, or any where you configure a Structure.
3. Identify the `_inputs` key, or create one at that level of the configuration cascade.
4. Add an input name key for your input under the `_inputs` key (a.k.a., `_inputs.*`). We recommend naming your input something simple that indicates the function or context.
5. Add the `type` key under your input name key, with the value `html` or `markdown`.
6. (Optional.) Add any other general configuration keys (e.g., `label`, `comment`, `context`) under your input name key.
7. (Optional.) Add any specific configuration keys under `_inputs.*.options` (e.g., `allow_resize`, `initial_height`, `paths`).

CloudCannon will now apply this input configuration to all markup files that use your input name key, without needing to save your configuration. This allows you to make changes to your input configuration and see those changes affect inputs live.

When you are happy with your input configuration, you must save your input configuration.

File: `cloudcannon.config.yml`

```YAML
```

_inputs___1___:
  content___2___:
    type___3___: html
  top_copy___4___:
    type___5___: markdown

```

**[1]** All inputs are defined under the `_inputs` key, regardless of where they are in the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

**[2]** The Rich Text input is called `content`.

**[3]** The value of the `type` key determines the input type. This is an `html` Rich Text input.

**[4]** The Rich Text input is called `top_copy`.

**[5]** The value of the `type` key determines the input type. This is a `markdown` Rich Text input.
```

When you add your input key name to a data or markup file, your configured Rich Text input will appear in the Data Editor, Visual Editor, or Content Editor.

File: `about.md`

```Markdown

---
content: |
  <p>This paragraph has <em>emphasis</em> and <strong>strength</strong>.</p>
  <ol>
    <li>Walk</li>
    <li>Run</li>
  </ol>
  <p>Linking to <a href="/">index</a>.</p>
top_copy: |
  # Animals

  - Dogs
  - Cats

  ***Its raining cats and dogs.***
---

```

> You may need to convert the Markdown value into HTML to use it on your site, for example by using the `markdownify` filter in Jekyll or Hugo. For more information, please read our documentation on [configuring your markdown engine](/documentation/developer-articles/configure-your-markdown-engine/).

## Input configuration options

General configuration options are available for all input types. You can define the label, comment, and context box for your Rich Text input, whether it is hidden or disabled, and how CloudCannon should handle configuration at multiple levels of the configuration cascade.

Specific configuration options for Rich Text inputs include configuring whether your team members are allowed to resize the text area, the initial height of the text area, the upload paths or filenames for any assets uploaded through this input, and how CloudCannon handles empty values. You can also add input validation to require a value, specify the minimum and maximum value length, or match a regular expression.

Here is an example of a Rich Text input using some of the most commonly used configuration keys.

File: `cloudcannon.config.yml`

```YAML

_inputs:
  description:
    type: markdown
    label: Page Description
    comment: Enter the description for this page
    options:
      allow_resize: false
      initial_height: 200
      paths:
        dam_uploads: assets/images
        dam_uploads_filename: "[filename].[extension]"
      required: true
      max_length: 500

```

For a complete list of configuration keys available for inputs please read our [Inputs](/documentation/developer-reference/configuration-file/types/_inputs/) reference documentation.

These keys configure the appearance and functionality of Rich Text inputs in CloudCannon.

**`_inputs.*.options.allow_resize`** Boolean

This key toggles the resize handler to vertically resize the text area of the input. Defaults to `true`.

**`_inputs.*.options.initial_height`** Integer

This key defines the initial height of the input text area in pixels (`px`). Defaults to `320`. Supports values between `135` and `1200`.

**`_inputs.*.options.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](/documentation/developer-articles/using-the-configuration-cascade/), `paths` will default to any values configured in the [CloudCannon configuration file](/documentation/developer-articles/what-is-the-cloudcannon-configuration-file/).

For more information, please read our documentation on [Rich Text editors](/documentation/developer-articles/what-are-rich-text-editors/) or [File inputs](/documentation/user-articles/what-is-a-file-input/).

**`_inputs.*.options.paths.dam_static`** String

This key enables you to define the path for the location of statically copied assets for [DAM](/documentation/developer-articles/introduction-to-assets-and-dams/) files.

**`_inputs.*.options.paths.dam_uploads`** String

This key enables you to define the path for the default location of newly uploaded [DAM](/documentation/developer-articles/introduction-to-assets-and-dams/) files.

You can use [dynamic placeholders](/documentation/developer-articles/configure-your-template-strings/) for `uploads` and `dam_uploads`. For more information, please read our documentation on [adjusting file upload paths](/documentation/developer-articles/adjusting-the-uploads-path/).

**`_inputs.*.options.paths.dam_uploads_filename`** String

This key enables you to define the name of a file, after uploading it to a [DAM](/documentation/developer-articles/introduction-to-assets-and-dams/).

**`_inputs.*.options.paths.static`** String

This key enables you to define the path for the location of statically copied assets.

**`_inputs.*.options.paths.uploads`** String

This key enables you to define the path for the default location of newly uploaded files.

You can use [dynamic placeholders](/documentation/developer-articles/configure-your-template-strings/) for `uploads` and `dam_uploads`. For more information, please read our documentation on [adjusting file upload paths](/documentation/developer-articles/adjusting-the-uploads-path/).

**`_inputs.*.options.paths.uploads_filename`** String

This key enables you to define the name of a file, after uploading it.

**`_inputs.*.options.paths.uploads_use_relative_paths`** Boolean

This key enables you to use a file path relative to the current file when uploading through this input. File inputs in data files or front matter will also use relative file paths when selecting an existing file.

**`_inputs.*.options.empty_type`** string

This key determines how CloudCannon handles an empty value. This key does not apply to existing empty values.

Value must be one of the following:

- `string` - an empty value for this input will be stored as "".
- `null` - an empty value for this input will be stored as a null value (default). This does not apply to TOML files.

**`_inputs.*.options.required`** Boolean

This key toggles whether CloudCannon requires this Input to have a value. If set to `true`, CloudCannon will require you to enter a value to save your changes, or discard your unsaved changes.

By default, this key is `false` (i.e, CloudCannon does not require this Input to have a value).

This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.

In this example, we want to require our team to enter an `author` value for markup files with this Input.

File: `cloudcannon.config.yml`

```YAML
  _inputs:
    author:
      type: text
      comment: Enter the name of the author for this blog post.
      options:
        required: true

```

**`_inputs.*.options.required_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.required`. This key requires you to define `options.required`.

This key has no default.

This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to use enter an Input value using a required message.

File: `cloudcannon.config.yml`

```YAML
  _inputs:
    author:
      type: text
      comment: Enter the name of the author for this blog post.
      options:
        required: true
        required_message: You are not allowed to leave this blank.

```

**`_inputs.*.options.max_length`** Number

This key defines the maximum string length, in characters, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.

Value can be any non-negative integer. If this key is set to `0`, CloudCannon requires the Input to be empty. If `options.min_length` is also configured, this key cannot be a smaller number.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, `allow_create` must be set to `true`.

In this example, we want our team to enter a blog description using the Rich Text `seo_description` Input. This Input limits you to a maximum of 125 characters.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      min_length: 25
```

**`_inputs.*.options.max_length_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.max_length`. This key requires you to define `options.max_length`.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to enter a valid number of characters using a custom message.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      max_length_message: You are only allowed 125 characters.
      min_length: 25
      min_length_message: Please write more than 25 characters.
```

**`_inputs.*.options.min_length`** Number

This key defines the minimum string length, in characters, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.

Value can be any positive integer. If `options.max_length` is also configured, this key cannot be a greater number.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, `allow_create` must be set to `true`.

In this example, we want our team to enter a blog description using the Rich Text `seo_description` Input. This Input requires a minimum of 25 characters.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      min_length: 25
```

**`_inputs.*.options.min_length_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.min_length`. This key requires you to define `options.min_length`.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to enter a valid number of characters using a custom message.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      max_length_message: You are only allowed 125 characters.
      min_length: 25
      min_length_message: Please write more than 25 characters.
```

**`_inputs.*.options.pattern`** String

This key defines a [regular expression](https://re2js.leopard.in.ua/) that the Input value must match. When configured, CloudCannon will require you to enter a value that matches the REGEX pattern. If the Input already contains an invalid value, CloudCannon will require you to enter a valid string to save your changes, or discard your unsaved changes.

Value must be a valid REGEX string. If your REGEX string includes a `\` character and CloudCannon Configuration File is a `.yml` file, use single quotes `'` around the string to avoid a build error.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, `allow_create` must be set to `true`.

In this example, we want our team to add an email address to the `contact_email` Input using the correct email format.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  contact_email:
    type: email
    options:
      pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
      pattern_message: 'Please use the format ___@___.__'
```

**`_inputs.*.options.pattern_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.pattern`. This key requires you to define `options.pattern`.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to use the correct email format in the `contact_email` Input using a pattern message.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  contact_email:
    type: email
    options:
      pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
      pattern_message: 'Please use the format ___@___.__'
```

## Valid values

Rich Text inputs can have multiple valid values for empty, single line, and multiline content. Here are some examples of valid values for the key `html`. These work for both HTML and Markdown inputs.

**YAML:**

Empty/null value:

- `html: `

Any valid string (quoted or unquoted):

- `html: ""`
- `html: ''`
- `html: any string`
- `html: "any string"`
- `html: 'any string'`

Any valid multiline string:

- `html: >
    multiline string`
- `html: >-
    multiline string`
- `html: >+
    multiline string`
- `html: |
    multiline string`
- `html: |-
    multiline string`
- `html: |+
    multiline string`

**TOML:**

Any valid string:

- `html = ""`
- `html = "any string"`

Any valid escaped string:

- `html = ''`
- `html = 'any string (literal)'`

Any valid multiline string:

- `html = """
    multiline string"""`
- `html = """\
    multiline string (trimmed) \
    """`
- `html = '''
    literal multiline string'''`

**JSON:**

Null value:

- `"html": null`

Any valid string:

- `"html": ""`
- `"html": "any string"`

Any valid multiline string:

- `"html": "multiline \n string"`

## Unconfigured Rich Text inputs

In some cases, CloudCannon can still detect a Rich Text input even if you have not configured it.

CloudCannon will interpret any unconfigured input with the key name `html` or `markdown`, or that ends in `_html` or `_markdown`, as a Rich Text input.

File: `about.md`

```Markdown

---
sidebar_html: |
  <p>This paragraph has <em>emphasis</em> and <strong>strength</strong>.</p>
  <ol>
    <li>Walk</li>
    <li>Run</li>
  </ol>
  <p>Linking to <a href="/">index</a>.</p>
---

```

This behavior is convenient if you have simple inputs or do not want to configure inputs. It is also beneficial for new websites on CloudCannon where you have yet to create any CloudCannon-specific configuration.

> We recommend configuring your inputs for greater control over their functionality and appearance.


---

---
title: Configure a Select input
description: Learn how to configure Select  inputs to select from fixed or dynamic lists in your data files or front matter.
url: https://cloudcannon.com/documentation/developer-articles/configure-a-select-input/
content_type: developer article
last_modified: 2026-03-29
---

> **Permissions required**
> 
> Members of all [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `site:file:write` permission, can configure inputs in all locations in the configuration cascade. You can limit permission to specific locations in the configuration using [file globs](/documentation/developer-articles/what-are-custom-permission-groups/#specify-a-file-glob).

A [Select input](/documentation/user-articles/what-is-a-select-input/) is an editing interface for selecting values from predefined lists. By configuring your inputs, you can customize the appearance and functionality for a better editing experience.

![A screenshot of the Select Input in the Data Editor shows a text field and a dropdown menu.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Select-Input-Dropdown-Open.webp)

These instructions assume that you know what type of Select input you want to configure, how you want to populate the values of your input, and where in the configuration cascade. For more information, please read our documentation on [Select inputs](/documentation/user-articles/what-is-a-select-input/), [inputs](/documentation/user-articles/what-are-inputs/) in general, [populating a Select input](/documentation/developer-articles/populate-a-select-input/), and the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

To configure a Select input:

1. Open your website files in your local development environment, or log in to CloudCannon and select the Site for which you want to configure your input.
2. Navigate to the location in the configuration cascade where you want to configure your input. This can be the root of your CloudCannon Configuration File, within the `collections_config.*` key in your CloudCannon Configuration File, a Schema file, a markup file, or anywhere you configure a Structure.
3. Identify the `_inputs` key, or create one at that level of the configuration cascade.
4. Add an input name key for your input under the `_inputs` key (a.k.a., `_inputs.*`). We recommend naming your input something simple that indicates the function or context.
5. Add the `type` key under your input name key, with the value `select`, `multiselect`, `choice`, or `multichoice`.
6. (Optional.) Add any other general configuration keys (e.g., `label`, `comment`, `context`) under your input name key.
7. Add the `values` key under `_inputs.*.options` to define how CloudCannon should populate your input. The value must be a fixed data set, Collection, or data file.
8. (Optional.) Add any other specific configuration keys under `_inputs.*.options` (e.g., `preview`, `value_key`, `allow_empty`).

CloudCannon will now apply this input configuration to all markup files that use your input name key, without needing to save your configuration. This allows you to make changes to your input configuration and see those changes affect inputs live.

When you are happy with your input configuration, you must save your input configuration.

File: `cloudcannon.config.yml`

```YAML
```

_inputs___1___:
  blog_author___2___:
    type___3___: select
  blog_tags___4___:
    type___5___: multiselect
  priority___6___:
    type___7___: choice
  theme_color___8___:
    type___9___: multichoice

```

**[1]** All inputs are defined under the `_inputs` key, regardless of where they are in the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

**[2]** This Select input is called `blog_author`.

**[3]** The value of the `type` key determines the input type. This is a `select` input.

**[4]** This Multiselect input is called `blog_tags`.

**[5]** The value of the `type` key determines the input type. This is a `multiselect` input.

**[6]** This Choice input is called `priority`.

**[7]** The value of the `type` key determines the input type. This is a `choice` input.

**[8]** This Multichoice input is called `theme_color`.

**[9]** The value of the `type` key determines the input type. This is a `multichoice` input.
```

When you add your input key name to a data or markup file, your configured Select input will appear in the Data Editor, Visual Editor, or Content Editor.

File: `blog.md`

```Markdown

---
blog_author: Author A
blog_tags:
  - Opinion
  - Resource
priority: high
theme_color:
  - Blue
  - Green
---

Content goes here.

```

## Input configuration options

General configuration options are available for all input types. You can define the label, comment, and context box for your Select input, whether it is hidden or disabled, and how CloudCannon should handle configuration at multiple levels of the configuration cascade.

Specific configuration options for Select inputs include defining the list of input options, the appearance of option previews, whether you can create new values, whether the input can be empty, and how CloudCannon handles empty values. You can also add input validation to require a value, specify the minimum and maximum number of items, and whether CloudCannon should require unique values.

Here is an example of a Select input using some of the most commonly used configuration keys.

File: `cloudcannon.config.yml`

```YAML

_inputs:
  blog_author:
    type: select
    label: Blog Author
    comment: Select the author for this blog post
    options:
      values:
        - name: Karen Key
          role: Project Manager
          profile_picture: /staff/karen_key.jpg
        - name: Holly James
          role: Engineering Lead
          profile_picture: /staff/holly_james.jpg
      value_key: name
      preview:
        text:
          - key: name
        image:
          - key: profile_picture
      required: true

```

For a complete list of configuration keys available for inputs please read our [Inputs](/documentation/developer-reference/configuration-file/types/_inputs/) reference documentation.

These keys configure the appearance and functionality of Select inputs in CloudCannon.

**`_inputs.*.options.allow_create`** Boolean

This key determines whether you are allowed to enter a new text value that does not appear in the data set. CloudCannon does not add new text values to the data set. Defaults to `false`.

**`_inputs.*.options.allow_empty`** Boolean

This key toggles the presence of an empty option alongside the options listed under `values`. Defaults to `true`. When `false`, CloudCannon will use the first value in the data set by default.

This key has no effect on Multiselect inputs.

**`_inputs.*.options.empty_type`** string

This key determines how CloudCannon handles an empty value. This key does not apply to existing empty values.

Value must be one of the following:

- `string` - an empty value for this input will be stored as "".
- `array` - an empty value for this input will be stored as `[]`.
- `null` - an empty value for this input will be stored as a null value (default). This does not apply to TOML files.

Available for Multiselect and Multichoice inputs.

**`_inputs.*.options.preview`** Object

This key enables you to define the appearance of input values in the Data Editor or sidebar of the Visual or Content Editor. The following nested keys are available:

- `text`
- `icon` (Choice/Multichoice only)
- `icon_color` (Choice/Multichoice only)
- `icon_background_color` (Choice/Multichoice only)
- `image` (Choice/Multichoice only)

Defaults to:

File: `cloudcannon.config.yml`

```YAML
preview:
  text:
    - key: title
    - key: name
  icon:
    - key: icon
```

For more information about previews, please read our documentation on [configuring card previews](/documentation/developer-articles/configure-your-card-previews/).

**`_inputs.*.options.preview.text`** Array, string or boolean

This key determines the title text displayed for a value option. This key has no default, and has no effect unless the value option is an Object.

If set to `false`, no text is displayed.

**`_inputs.*.options.preview.icon`** Array, string or boolean

This key determines the icon displaye beside the text and subtext on a Card. The value must match a name from the [Google's Material Icons](https://fonts.google.com/icons) list.

This key defaults to checking the `icon` key, then falls back to the `notes` icon.

If set to `false`, no icon is displayed.

If `image` is defined, the image replaces `icon` when loaded successfully.

This key supports cascading options, which can be either an Array or a single value. Value can be one of the following:

- A String of the exact value (e.g `"edit_note"`)
- A reference to a key within the connected item (e.g `key: icon` in YAML or `{ "key": "icon" }` in JSON)
- A String with placeholders that will be replaced with values (e.g. `template: {icon_type}` in YAML or `{ "template": "{icon_type}" }` in JSON)

Available for Choice and Multichoice inputs.

In this example, we configure a static icon for the card.

File: `cloudcannon.config.yml`

```YAML
preview:
  icon: edit_note
```

In this example, we use a dynamic icon from the data.

File: `cloudcannon.config.yml`

```YAML
preview:
  icon:
    - key: icon_type
    - support_agent
```

**`_inputs.*.options.preview.icon_color`** Array, string or boolean

This key determines the color of the icon displayed on a Card.

This key supports cascading options, which can be either an Array or a single value. Value can be one of the following:

- A String of the exact value (e.g `"#ff0000"`)
- A reference to a key within the connected item (e.g `key: color` in YAML or `{ "key": "color" }` in JSON)
- A String with placeholders that will be replaced with values (e.g. `template: {color_code}` in YAML or `{ "template": "{color_code}" }` in JSON)

By default, this key is `#000000` (black).

In this example, we configure a dynamic icon color from the data with a fallback to red.

File: `cloudcannon.config.yml`

```YAML
preview:
  icon: edit_note
  icon_color:
    - key: color
    - '#ff0000'
```

In this example, we use a static icon color.

File: `cloudcannon.config.yml`

```YAML
preview:
  icon: nature_people
  icon_color:
    - '#00ff00'
```

**`_inputs.*.options.preview.icon_background_color`** Array, string or boolean

This key determines the background color of the icon displayed on a Card. This is useful if your `icon_color` value has poor contrast on a white background.

This key supports cascading options, which can be either an Array or a single value.Value can be one of the following:

- A String of the exact value (e.g `"#ff0000"`)
- A reference to a key within the connected item (e.g `key: color` in YAML or `{ "key": "color" }` in JSON)
- A String with placeholders that will be replaced with values (e.g. `template: {color_code}` in YAML or `{ "template": "{color_code}" }` in JSON)

This key has no default.

In this example, we configure a dynamic icon background color from the data with a fallback to red.

File: `cloudcannon.config.yml`

```YAML
preview:
  icon: edit_note
  icon_background_color:
    - key: color
    - '#ff0000'
```

In this example, we use a static icon background color.

File: `cloudcannon.config.yml`

```YAML
preview:
  icon: nature_people
  icon_background_color:
    - '#00ff00'
```

**`_inputs.*.options.preview.image`** array, string, or boolean

This key determines the image displayed for a value option. This key has no default and, if the value option is an Object, falls back to `thumbnail_image`, `thumbnail_image_path`, `image`, and `image_path` in that order. If no image is found, `icon` is displayed instead.

If set to `false`, no image is displayed.

Available for Choice and Multichoice inputs.

**`_inputs.*.options.values`** Array, object or string

This key defines which values are available for a Select or Multiselect input.

You must define this key for the Select or Multiselect input to function.

Value can be an array of options, or a string referencing a fixed data set, Collection, or data file.

This key has no default.

In this example, CloudCannon will provide items in the `posts` Collection as values for the `heathers_posts` input. CloudCannon will also apply a filter, returning only files where the `author` structured data key is equal to "Heather".

File: `cloudcannon.config.yml`

```YAML
_inputs:
  heathers_posts:
    type: multiselect
    label: Heather's Posts
    options:
      values: "collections.posts[?(@.author == 'Heather')]"
```

**`_inputs.*.options.value_key`** String or array of strings

This key defines which key CloudCannon should use as the Select/Multiselect input value when a value option is an Object with multiple nested keys.

Defaults to `['id', 'uuid', 'path', 'title', 'name']`. Has no effect unless `values` is an array of objects.

If set as an array, keys are tried in order, until a non-empty value is found. If no keys are set for an available value, that value is not included in the input options.

If set as a string, this key is used directly. Value options are excluded if they don't have a value for this key.

**`_inputs.*.options.required`** Boolean

This key toggles whether CloudCannon requires this Input to have a value. If set to `true`, CloudCannon will require you to enter a value to save your changes, or discard your unsaved changes.

By default, this key is `false` (i.e, CloudCannon does not require this Input to have a value).

This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.

In this example, we want to require our team to enter an `author` value for markup files with this Input.

File: `cloudcannon.config.yml`

```YAML
  _inputs:
    author:
      type: text
      comment: Enter the name of the author for this blog post.
      options:
        required: true

```

**`_inputs.*.options.required_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.required`. This key requires you to define `options.required`.

This key has no default.

This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to use enter an Input value using a required message.

File: `cloudcannon.config.yml`

```YAML
  _inputs:
    author:
      type: text
      comment: Enter the name of the author for this blog post.
      options:
        required: true
        required_message: You are not allowed to leave this blank.

```

**`_inputs.*.options.max_items`** Number

This key defines the maximum number of items CloudCannon will allow in an Input. When configured, CloudCannon will prevent you from adding more items to this Input. If the Input already contains more items, CloudCannon will require you to remove items until the Input contains a valid number to save your changes, or discard your unsaved changes.

Value can be any positive integer. If `options.min_items` is also configured, this key cannot be a lesser number.

This key has no default.

This key is available for Array and Multiselect or Multichoice Inputs.

In this example, we want to add an array of filepaths to our homepage's `featured_posts` Input. This Input limits you to a maximum of five array items.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  featured_posts:
    type: array
    options:
      max_items: 5
      max_items_message: Cannot be more than 5
      min_items: 2
      min_items_message: Cannot be less than 2
```

**`_inputs.*.options.max_items_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.max_items`. This key requires you to define `options.max_items`.

This key has no default.

This key is available for Array and Multiselect or Multichoice Inputs.

In this example, we prompt our team to enter a valid number of items using a custom message.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  featured_posts:
    type: array
    options:
      max_items: 5
      max_items_message: Cannot be more than 5
      min_items: 2
      min_items_message: Cannot be less than 2
```

**`_inputs.*.options.min_items`** Number

This key defines the minimum number of items CloudCannon will allow in an Input. When configured, CloudCannon will prevent you from removing items from this Input below this value. If the Input already contains fewer items, CloudCannon will require you to add items until the Input contains a valid number to save your changes, or discard your unsaved changes.

Value can be any positive integer. If `options.max_items` is also configured, this key cannot be a greater number.

This key has no default.

This key is available for Array and Multiselect or Multichoice Inputs.

In this example, we want to add an array of filepaths to our homepage's `featured_posts` Input. This Input limits you to a maximum of two array items.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  featured_posts:
    type: array
    options:
      max_items: 5
      max_items_message: Cannot be more than 5
      min_items: 2
      min_items_message: Cannot be less than 2
```

**`_inputs.*.options.min_items_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.min_items`. This key requires you to define `options.min_items`.

This key has no default.

This key is available for Array and Multiselect or Multichoice Inputs.

In this example, we prompt our team to enter a valid number of items using a custom message.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  featured_posts:
    type: array
    options:
      max_items: 5
      max_items_message: Cannot be more than 5
      min_items: 2
      min_items_message: Cannot be less than 2
```

**`_inputs.*.options.max_length`** Number

This key defines the maximum string length, in characters, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.

Value can be any non-negative integer. If this key is set to `0`, CloudCannon requires the Input to be empty. If `options.min_length` is also configured, this key cannot be a smaller number.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, `allow_create` must be set to `true`.

In this example, we want our team to enter a blog description using the Rich Text `seo_description` Input. This Input limits you to a maximum of 125 characters.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      min_length: 25
```

**`_inputs.*.options.max_length_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.max_length`. This key requires you to define `options.max_length`.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to enter a valid number of characters using a custom message.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      max_length_message: You are only allowed 125 characters.
      min_length: 25
      min_length_message: Please write more than 25 characters.
```

**`_inputs.*.options.min_length`** Number

This key defines the minimum string length, in characters, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.

Value can be any positive integer. If `options.max_length` is also configured, this key cannot be a greater number.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, `allow_create` must be set to `true`.

In this example, we want our team to enter a blog description using the Rich Text `seo_description` Input. This Input requires a minimum of 25 characters.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      min_length: 25
```

**`_inputs.*.options.min_length_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.min_length`. This key requires you to define `options.min_length`.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to enter a valid number of characters using a custom message.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      max_length_message: You are only allowed 125 characters.
      min_length: 25
      min_length_message: Please write more than 25 characters.
```

**`_inputs.*.options.pattern`** String

This key defines a [regular expression](https://re2js.leopard.in.ua/) that the Input value must match. When configured, CloudCannon will require you to enter a value that matches the REGEX pattern. If the Input already contains an invalid value, CloudCannon will require you to enter a valid string to save your changes, or discard your unsaved changes.

Value must be a valid REGEX string. If your REGEX string includes a `\` character and CloudCannon Configuration File is a `.yml` file, use single quotes `'` around the string to avoid a build error.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, `allow_create` must be set to `true`.

In this example, we want our team to add an email address to the `contact_email` Input using the correct email format.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  contact_email:
    type: email
    options:
      pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
      pattern_message: 'Please use the format ___@___.__'
```

**`_inputs.*.options.pattern_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.pattern`. This key requires you to define `options.pattern`.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to use the correct email format in the `contact_email` Input using a pattern message.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  contact_email:
    type: email
    options:
      pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
      pattern_message: 'Please use the format ___@___.__'
```

## Valid values

Here are some examples of valid values for Select inputs.

**YAML:**

Empty/null value:

- `select_value: `

Single value (Select/Choice):

- `select_value: option1`
- `select_value: "option1"`

Multiple values (Multiselect/Multichoice):

```yaml
multiselect_value:
  - option1
  - option2
  - option3
```

**TOML:**

Single value (Select/Choice):

- `select_value = "option1"`

Multiple values (Multiselect/Multichoice):

- `multiselect_value = ["option1", "option2", "option3"]`

**JSON:**

Empty/null value:

- `"select_value": null`

Single value (Select/Choice):

- `"select_value": "option1"`

Multiple values (Multiselect/Multichoice):

```json
{
  "multiselect_value": [
    "option1",
    "option2",
    "option3"
  ]
}
```

## Unconfigured Select inputs

When the [Infer Select values from input key](/documentation/developer-articles/input-naming-convention-flags/) flag is enabled, CloudCannon can still detect a Select input even if you have not configured it.

CloudCannon will interpret any key as a Select input if the key name ends in the singular form of a fixed data set you have defined under `_select_data` (e.g., `author` or `blog_author` for the fixed data set `authors`).

File: `blog.md`

```Markdown

---
blog_author: Karen Key
---

Blog content goes here.

```

File: `cloudcannon.config.yml`

```YAML

_select_data:
  authors:
    - Karen Key
    - Billy Mills
    - Holly James

```

CloudCannon no longer infers Select inputs by default, as the detection method for single and plural key names did not respect more complex plural suffixes (e.g., "-es") or non-English words.

> We recommend configuring your inputs for greater control over their functionality and appearance.


---

---
title: Configure a Text input
description: Learn how to configure a Text input to edit plain text content in your data files or front matter.
url: https://cloudcannon.com/documentation/developer-articles/configure-a-text-input/
content_type: developer article
last_modified: 2026-03-29
---

> **Permissions required**
> 
> Members of all [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `site:file:write` permission, can configure inputs in all locations in the configuration cascade. You can limit permission to specific locations in the configuration using [file globs](/documentation/developer-articles/what-are-custom-permission-groups/#specify-a-file-glob).

A [Text input](/documentation/user-articles/what-is-a-text-input/) is an editing interface for plain text content. By configuring your inputs, you can customize the appearance and functionality for a better editing experience.

![A screenshot of the Text Input in the Data Editor shows a text field.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Text-Input.webp)

These instructions assume that you know what type of Text input you want to configure and where in the configuration cascade. For more information, please read our documentation on [Text inputs](/documentation/user-articles/what-is-a-text-input/), [inputs](/documentation/user-articles/what-are-inputs/) in general, and the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

To configure a Text input:

1. Open your website files in your local development environment, or log in to CloudCannon and select the Site for which you want to configure your input.
2. Navigate to the location in the configuration cascade where you want to configure your input. This can be the root of your CloudCannon Configuration File, within the `collections_config.*` key in your CloudCannon Configuration File, a Schema file, the frontmatter of a markup file, or any where you configure a Structure.
3. Identify the `_inputs` key, or create one at that level of the configuration cascade.
4. Add an input name key for your input under the `_inputs` key (a.k.a., `_inputs.*`). We recommend naming your input something simple that indicates the function or context.
5. Add the `type` key under your input name key, with the value `text`, `textarea`, or `email`.
6. (Optional.) Add any other general configuration keys (e.g., `label`, `comment`, `context`) under your input name key.
7. (Optional.) Add any specific configuration keys under `_inputs.*.options` (e.g., `show_count`, `empty_type`).

CloudCannon will now apply this input configuration to all markup files that use your input name key, without needing to save your configuration. This allows you to make changes to your input configuration and see those changes affect inputs live.

When you are happy with your input configuration, you must save your input configuration.

File: `cloudcannon.config.yml`

```YAML
```

_inputs___1___:
  blog_title___2___:
    type___3___: text
  page_description___4___:
    type___5___: textarea
  contact_address___6___:
    type___7___: email

```

**[1]** All inputs are defined under the `_inputs` key, regardless of where they are in the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

**[2]** This Text input is called `blog_title`.

**[3]** The value of the `type` key determines the input type. This is a `text` input.

**[4]** This Textarea input is called `page_description`.

**[5]** The value of the `type` key determines the input type. This is a `textarea` Text input.

**[6]** This Email input is called `contact_address`.

**[7]** The value of the `type` key determines the input type. This is a `email` Text input.
```

When you add your input key name to a data or markup file, your configured Text input will appear in the Data Editor, Visual Editor, or Content Editor.

File: `data.yml`

```YAML

blog_title: The benefits of static sites
page_description: This page is about how to configure your inputs.
contact_address: support@cloudcannon.com

```

## Input configuration options

General configuration options are available for all input types. You can define the label, comment, and context box for your Text input, whether it is hidden or disabled, and how CloudCannon should handle configuration at multiple levels of the configuration cascade.

Specific configuration options for Text inputs include configuring how CloudCannon handles empty values. You can also add input validation to require a value, specify the minimum and maximum value length, or match a regular expression. For Textarea inputs, you can configure a character counter.

Here is an example of a Text input using some of the most commonly used configuration keys.

File: `cloudcannon.config.yml`

```YAML

_inputs:
  seo_description:
    type: textarea
    label: SEO Description
    comment: Enter a description for search engines
    options:
      show_count: true
      empty_type: null
      required: true
      max_length: 160

```

For a complete list of configuration keys available for inputs please read our [Inputs](/documentation/developer-reference/configuration-file/types/_inputs/) reference documentation.

These keys configure the appearance and functionality of Text inputs in CloudCannon.

**`_inputs.*.options.show_count`** Boolean

This key toggles a character counter.

Available for Textarea input only.

**`_inputs.*.options.empty_type`** string

This key determines how CloudCannon handles an empty value. This key does not apply to existing empty values.

Value must be one of the following:

- `string` - an empty value for this input will be stored as "".
- `null` - an empty value for this input will be stored as a null value (default). This does not apply to TOML files.

**`_inputs.*.options.icon`** String

This key determines whether CloudCannon should display an icon at the beginning of the text field and which icon it should display. The value must match a name from the [Material Icons](https://fonts.google.com/icons?icon.set=Material+Icons) list.

This key has no default.

In this example, we have added the `person` icon to the beginning of the text field to visually add context.

File: `cloudcannon.config.yml`

```YAML
  _inputs:
    author:
      options:
        icon: person

```

**`_inputs.*.options.required`** Boolean

This key toggles whether CloudCannon requires this Input to have a value. If set to `true`, CloudCannon will require you to enter a value to save your changes, or discard your unsaved changes.

By default, this key is `false` (i.e, CloudCannon does not require this Input to have a value).

This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.

In this example, we want to require our team to enter an `author` value for markup files with this Input.

File: `cloudcannon.config.yml`

```YAML
  _inputs:
    author:
      type: text
      comment: Enter the name of the author for this blog post.
      options:
        required: true

```

**`_inputs.*.options.required_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.required`. This key requires you to define `options.required`.

This key has no default.

This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to use enter an Input value using a required message.

File: `cloudcannon.config.yml`

```YAML
  _inputs:
    author:
      type: text
      comment: Enter the name of the author for this blog post.
      options:
        required: true
        required_message: You are not allowed to leave this blank.

```

**`_inputs.*.options.max_length`** Number

This key defines the maximum string length, in characters, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.

Value can be any non-negative integer. If this key is set to `0`, CloudCannon requires the Input to be empty. If `options.min_length` is also configured, this key cannot be a smaller number.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, `allow_create` must be set to `true`.

In this example, we want our team to enter a blog description using the Rich Text `seo_description` Input. This Input limits you to a maximum of 125 characters.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      min_length: 25
```

**`_inputs.*.options.max_length_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.max_length`. This key requires you to define `options.max_length`.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to enter a valid number of characters using a custom message.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      max_length_message: You are only allowed 125 characters.
      min_length: 25
      min_length_message: Please write more than 25 characters.
```

**`_inputs.*.options.min_length`** Number

This key defines the minimum string length, in characters, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.

Value can be any positive integer. If `options.max_length` is also configured, this key cannot be a greater number.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, `allow_create` must be set to `true`.

In this example, we want our team to enter a blog description using the Rich Text `seo_description` Input. This Input requires a minimum of 25 characters.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      min_length: 25
```

**`_inputs.*.options.min_length_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.min_length`. This key requires you to define `options.min_length`.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to enter a valid number of characters using a custom message.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      max_length_message: You are only allowed 125 characters.
      min_length: 25
      min_length_message: Please write more than 25 characters.
```

**`_inputs.*.options.pattern`** String

This key defines a [regular expression](https://re2js.leopard.in.ua/) that the Input value must match. When configured, CloudCannon will require you to enter a value that matches the REGEX pattern. If the Input already contains an invalid value, CloudCannon will require you to enter a valid string to save your changes, or discard your unsaved changes.

Value must be a valid REGEX string. If your REGEX string includes a `\` character and CloudCannon Configuration File is a `.yml` file, use single quotes `'` around the string to avoid a build error.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, `allow_create` must be set to `true`.

In this example, we want our team to add an email address to the `contact_email` Input using the correct email format.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  contact_email:
    type: email
    options:
      pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
      pattern_message: 'Please use the format ___@___.__'
```

**`_inputs.*.options.pattern_message`** String

This key defines the message that explains which [regular expression](https://re2js.leopard.in.ua/) an Input will accept. This key requires you to define `options.pattern`.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to use the correct email format in the `contact_email` Input using a pattern message.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  contact_email:
    type: email
    options:
      pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
      pattern_message: 'Please use the format ___@___.__'
```

## Valid values

Text inputs can have multiple valid values for empty, single line, and multiline content. Here are some examples of valid values for the key `text`. These work for Text, Textarea, and Email inputs.

**YAML:**

Empty/null value:

- `text: `

Any valid string (quoted or unquoted):

- `text: ""`
- `text: ''`
- `text: any string`
- `text: "any string"`
- `text: 'any string'`

Any valid multiline string:

- `text: >
    multiline string`
- `text: >-
    multiline string`
- `text: >+
    multiline string`
- `text: |
    multiline string`
- `text: |-
    multiline string`
- `text: |+
    multiline string`

**TOML:**

Any valid string:

- `text = ""`
- `text = "any string"`

Any valid escaped string:

- `text = ''`
- `text = 'any string (literal)'`

Any valid multiline string:

- `text = """
    multiline string"""`
- `text = """\
    multiline string (trimmed) \
    """`
- `text = '''
    literal multiline string'''`

**JSON:**

Null value:

- `"text": null`

Any valid string:

- `"text": ""`
- `"text": "any string"`

Any valid multiline string:

- `"text": "multiline \n string"`

## Unconfigured Text inputs

In some cases, CloudCannon can still detect a Text input even if you have not configured it.

CloudCannon will interpret any unconfigured input with the key name:

- `textarea` or `description`, or that ends in `_textarea` or `_description`, as a Textarea input.
- `email` or `email_address`, or that ends in `_email` or `_email_address`, as an Email input.

CloudCannon will interpret any unconfigured input with a string value as a Text input, provided that the key name does not match the naming convention for any other input type.

File: `data.yml`

```YAML

image_description: A beautiful forest scene

```

This behavior is convenient if you have simple inputs or do not want to configure inputs. It is also beneficial for new websites on CloudCannon where you have yet to create any CloudCannon-specific configuration.

> We recommend configuring your inputs for greater control over their functionality and appearance.


---

---
title: Configure a URL input
description: Learn how to configure a URL input to edit relative, absolute, and fully qualified URLs in your data files or front matter.
url: https://cloudcannon.com/documentation/developer-articles/configure-a-url-input/
content_type: developer article
last_modified: 2026-03-29
---

> **Permissions required**
> 
> Members of all [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `site:file:write` permission, can configure inputs in all locations in the configuration cascade. You can limit permission to specific locations in the configuration using [file globs](/documentation/developer-articles/what-are-custom-permission-groups/#specify-a-file-glob).

A [URL input](/documentation/user-articles/what-is-a-url-input/) is an editing interface for relative, absolute, and fully qualified URLs. By configuring your inputs, you can customize the appearance and functionality for a better editing experience.

![A screenshot of the URL Input in the Data Editor shows an external URL value with a preview of the URL image, title, and subtitle.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-URL-Input.webp)

These instructions assume that you know where in the configuration cascade you want to configure your input. For more information, please read our documentation on [URL inputs](/documentation/user-articles/what-is-a-url-input/), [inputs](/documentation/user-articles/what-are-inputs/) in general, and the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

To configure a URL input:

1. Open your website files in your local development environment, or log in to CloudCannon and select the Site for which you want to configure your input.
2. Navigate to the location in the configuration cascade where you want to configure your input. This can be the root of your CloudCannon Configuration File, within the `collections_config.*` key in your CloudCannon Configuration File, a Schema file, the frontmatter of a markup file, or any where you configure a Structure.
3. Identify the `_inputs` key, or create one at that level of the configuration cascade.
4. Add an input name key for your input under the `_inputs` key (a.k.a., `_inputs.*`). We recommend naming your input something simple that indicates the function or context.
5. Add the `type` key under your input name key, with the value `url`.
6. (Optional.) Add any other general configuration keys (e.g., `label`, `comment`, `context`) under your input name key.
7. (Optional.) Add any specific configuration keys under `_inputs.*.options` (e.g., `pattern`, `pattern_message`).

CloudCannon will now apply this input configuration to all markup files that use your input name key, without needing to save your configuration. This allows you to make changes to your input configuration and see those changes affect inputs live.

When you are happy with your input configuration, you must save your input configuration.

File: `cloudcannon.config.yml`

```YAML
```

_inputs___1___:
  associate_link___2___:
    type___3___: url

```

**[1]** All inputs are defined under the `_inputs` key, regardless of where they are in the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

**[2]** This URL input is called `associate_link`.

**[3]** The value of the `type` key determines the input type. This is a `url` input.
```

When you add your input key name to a data or markup file, your configured URL input will appear in the Data Editor, Visual Editor, or Content Editor.

File: `blog.md`

```Markdown

---
associate_link: http://example.com
---

Blog content goes here.

```

## Input configuration options

General configuration options are available for all input types. You can define the label, comment, and context box for your URL input, whether it is hidden or disabled, and how CloudCannon should handle configuration at multiple levels of the configuration cascade.

Specific configuration options for URL inputs include configuring how CloudCannon handles empty values and which URL input options are visible. You can also add input validation to require a value, specify the minimum and maximum value length, or match a regular expression.

Here is an example of a URL input using some of the most commonly used configuration keys.

File: `cloudcannon.config.yml`

```YAML

_inputs:
  external_link:
    type: url
    label: External Link
    comment: Enter a URL to link to an external resource
    options:
      required: true
      pattern: '^https?\:\/\/'
      pattern_message: 'Please use a URL starting with https://'
      empty_type: null

```

For a complete list of configuration keys available for inputs please read our [Inputs](/documentation/developer-reference/configuration-file/types/_inputs/) reference documentation.

These keys configure the appearance and functionality of URL inputs in CloudCannon.

**`_inputs.*.options.empty_type`** string

This key determines how CloudCannon handles an empty value. This key does not apply to existing empty values.

Value must be one of the following:

- `string` - an empty value for this input will be stored as "".
- `null` - an empty value for this input will be stored as a null value (default). This does not apply to TOML files.

**`_inputs.*.options.paths`** Object

This key enables you to define paths for your Rich Text editors, File, or URL 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](/documentation/developer-articles/using-the-configuration-cascade/), `paths` will default to any values configured in the [CloudCannon configuration file](/documentation/developer-articles/what-is-the-cloudcannon-configuration-file/).

For more information, please read our documentation on [adjusting the upload path](/documentation/developer-articles/adjusting-the-uploads-path/).

**`_inputs.*.options.paths.dam_static`** String

This key enables you to define the path for the location of statically copied assets for [DAM](/documentation/developer-articles/introduction-to-assets-and-dams/) files.

**`_inputs.*.options.paths.dam_uploads`** String

This key enables you to define the path for the default location of newly uploaded [DAM](/documentation/developer-articles/introduction-to-assets-and-dams/) files.

You can use [dynamic placeholders](/documentation/developer-articles/configure-your-template-strings/) for `uploads` and `dam_uploads`. For more information, please read our documentation on [adjusting file upload paths](/documentation/developer-articles/adjusting-the-uploads-path/).

**`_inputs.*.options.paths.dam_uploads_filename`** String

This key enables you to define the name of a file, after uploading it to a [DAM](/documentation/developer-articles/introduction-to-assets-and-dams/).

**`_inputs.*.options.paths.static`** String

This key enables you to define the path for the location of statically copied assets.

**`_inputs.*.options.paths.uploads`** String

This key enables you to define the path for the default location of newly uploaded files.

You can use [dynamic placeholders](/documentation/developer-articles/configure-your-template-strings/) for `uploads` and `dam_uploads`. For more information, please read our documentation on [adjusting file upload paths](/documentation/developer-articles/adjusting-the-uploads-path/).

**`_inputs.*.options.paths.uploads_filename`** String

This key enables you to define the name of a file, after uploading it.

**`_inputs.*.options.paths.uploads_use_relative_paths`** Boolean

This key enables you to use a file path relative to the current file when uploading through this input. File inputs in data files or front matter will also use relative file paths when selecting an existing file.

**`_inputs.*.options.allowed_sources`** Array

This key lists which DAMs you are allowed to upload to and browse. Valid values include `site-files` and the reference key for any DAM connected to your site.

If `site-files` is omitted from the array, site files will not be available as an asset source for this input.

**`_inputs.*.options.required`** Boolean

This key toggles whether CloudCannon requires this Input to have a value. If set to `true`, CloudCannon will require you to enter a value to save your changes, or discard your unsaved changes.

By default, this key is `false` (i.e, CloudCannon does not require this Input to have a value).

This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.

In this example, we want to require our team to enter an `author` value for markup files with this Input.

File: `cloudcannon.config.yml`

```YAML
  _inputs:
    author:
      type: text
      comment: Enter the name of the author for this blog post.
      options:
        required: true

```

**`_inputs.*.options.required_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.required`. This key requires you to define `options.required`.

This key has no default.

This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to use enter an Input value using a required message.

File: `cloudcannon.config.yml`

```YAML
  _inputs:
    author:
      type: text
      comment: Enter the name of the author for this blog post.
      options:
        required: true
        required_message: You are not allowed to leave this blank.

```

**`_inputs.*.options.max_length`** Number

This key defines the maximum string length, in characters, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.

Value can be any non-negative integer. If this key is set to `0`, CloudCannon requires the Input to be empty. If `options.min_length` is also configured, this key cannot be a smaller number.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, `allow_create` must be set to `true`.

In this example, we want our team to enter a blog description using the Rich Text `seo_description` Input. This Input limits you to a maximum of 125 characters.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      min_length: 25
```

**`_inputs.*.options.max_length_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.max_length`. This key requires you to define `options.max_length`.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to enter a valid number of characters using a custom message.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      max_length_message: You are only allowed 125 characters.
      min_length: 25
      min_length_message: Please write more than 25 characters.
```

**`_inputs.*.options.min_length`** Number

This key defines the minimum string length, in characters, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.

Value can be any positive integer. If `options.max_length` is also configured, this key cannot be a greater number.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, `allow_create` must be set to `true`.

In this example, we want our team to enter a blog description using the Rich Text `seo_description` Input. This Input requires a minimum of 25 characters.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      min_length: 25
```

**`_inputs.*.options.min_length_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.min_length`. This key requires you to define `options.min_length`.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to enter a valid number of characters using a custom message.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      max_length_message: You are only allowed 125 characters.
      min_length: 25
      min_length_message: Please write more than 25 characters.
```

**`_inputs.*.options.pattern`** String

This key defines a [regular expression](https://re2js.leopard.in.ua/) that the Input value must match. When configured, CloudCannon will require you to enter a value that matches the REGEX pattern. If the Input already contains an invalid value, CloudCannon will require you to enter a valid string to save your changes, or discard your unsaved changes.

Value must be a valid REGEX string. If your REGEX string includes a `\` character and CloudCannon Configuration File is a `.yml` file, use single quotes `'` around the string to avoid a build error.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, `allow_create` must be set to `true`.

In this example, we want our team to add an email address to the `contact_email` Input using the correct email format.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  contact_email:
    type: email
    options:
      pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
      pattern_message: 'Please use the format ___@___.__'
```

**`_inputs.*.options.pattern_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.pattern`. This key requires you to define `options.pattern`.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to use the correct email format in the `contact_email` Input using a pattern message.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  contact_email:
    type: email
    options:
      pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
      pattern_message: 'Please use the format ___@___.__'
```

**`_inputs.*.options.disable_upload_file`** Boolean

This key toggles whether CloudCannon shows the "Upload a new file" option in the "Add URL" dropdown menu on a URL Input or "Add file" dropdown menu on a File Input. When set to `true`, the "Upload a new file" option is not available.

By default, this key is `false` (i.e., users can upload files).

In this example, we have a `logo` Image input where users can only select existing images but cannot upload new ones.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  logo:
    type: image
    label: Company Logo
    options:
      disable_upload_file: true
```

**`_inputs.*.options.disable_direct_input`** Boolean

This key toggles whether you can type in the text field of a File Input or URL Input. When set to `true`, you cannot manually type or paste values into the input text field.

By default, this key is `false` (i.e., users can type directly into the input field).

In this example, we have a `document` File input where users must select files through the File Browser and cannot manually type file paths.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  document:
    type: document
    label: PDF Document
    options:
      disable_direct_input: true
```

**`_inputs.*.options.disable_upload_file_in_file_browser`** Boolean

This key toggles whether the "Add" button in the top right of the File browser modal is available, after selecting the "Link to existing file" option in the "Add URL" dropdown menu on a URL Input or "Add file" dropdown menu on a File Input. When set to `true`, the "Link to existing file" option is not available.

By default, this key is `false` (i.e., users can upload files in the File browser modal).

In this example, we have a `background_image` Image input where users can upload files using the "Upload a new file" option in the "Add URL" dropdown menu on a URL Input or "Add file" dropdown menu on a File Input, but not from within the File browser modal.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  background_image:
    type: image
    label: Background Image
    options:
      disable_upload_file_in_file_browser: true
```

**`_inputs.*.options.hide_link_to_file`** Boolean

This key toggles whether CloudCannon shows the "Link to an existing file" option in the "Add URL" dropdown menu on a URL Input. When set to `true`, the "Link to an existing file" option is not available.

By default, this key is `false` (i.e., file linking and upload options are visible).

In this example, we have a `document_url` URL input where users can only enter URLs manually and cannot link to files or upload new files.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  document_url:
    type: url
    label: Document URL
    comment: Enter the URL to an external document
    options:
      hide_link_to_file: true
```

**`_inputs.*.options.hide_link_to_page`** boolean

This key toggles whether the "Link to a page" option for this URL input is visible.

Setting this key to `true` will hide this option.

By default, this key is false (i.e., the option is visible).

**`_inputs.*.options.hide_link_to_email_address`** boolean

This key toggles whether the "Link to an email address" option for this URL input is visible.

Setting this key to `true` will hide this option.

By default, this key is false (i.e., the option is visible).

**`_inputs.*.options.hide_link_to_telephone`** boolean

This key toggles whether the "Link to a phone number" option for this URL input is visible.

Setting this key to `true` will hide this option.

By default, this key is false (i.e., the option is visible), except for Sites created before 20 August 2025. See our [documentation on legacy flags](/documentation/developer-articles/legacy-option-flags) for more information about the default behavior.

## Valid values

Here are some examples of valid values for the key `url`.

**YAML:**

Empty/null value:

- `url: `

Any valid string (quoted or unquoted):

- `url: ""`
- `url: ''`
- `url: example.com`
- `url: "example.com"`
- `url: 'example.com'`
- `url: "https://example.com"`

URLs containing `:` must be surrounded by quotes

**TOML:**

Any valid string:

- `url = ""`
- `url = ''`
- `url = "example.com"`
- `url = 'example.com'`
- `url = "https://example.com"`

**JSON:**

Null value:

- `"url": null`

Any valid string:

- `"url": ""`
- `"url": "example.com"`
- `"url": "https://example.com"`

## Unconfigured URL inputs

In some cases, CloudCannon can still detect a URL input even if you have not configured it.

CloudCannon will interpret any unconfigured input with the key name `url` or `link`, or that ends in `_url` or `_link`, as a URL input.

File: `data.yml`

```YAML

external_link: https://cloudcannon.com/

```

This behavior is convenient if you have simple inputs or do not want to configure inputs. It is also beneficial for new websites on CloudCannon where you have yet to create any CloudCannon-specific configuration.

> We recommend configuring your inputs for greater control over their functionality and appearance.


---

---
title: Configure an Array input
description: Learn how to configure an Array input to edit lists in your data files or front matter.
url: https://cloudcannon.com/documentation/developer-articles/configure-an-array-input/
content_type: developer article
last_modified: 2026-03-29
---

> **Permissions required**
> 
> Members of all [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `site:file:write` permission, can configure inputs in all locations in the configuration cascade. You can limit permission to specific locations in the configuration using [file globs](/documentation/developer-articles/what-are-custom-permission-groups/#specify-a-file-glob).

An [Array input](/documentation/user-articles/what-is-an-array-input/) is an editing interface for lists of structured data in data files or front matter. By configuring your inputs, you can customize the appearance and functionality for a better editing experience.

![A screenshot of the Array input in the Data Editor, showing a preview of the content within multiple entries.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Array-Input.webp)

These instructions assume that you know how you want to populate the values of your Array input, and where you want to configure it in the configuration cascade. For more information, please read our documentation on [Array inputs](/documentation/user-articles/what-is-an-array-input/), [inputs](/documentation/user-articles/what-are-inputs/) in general, [populating an Array input](/documentation/developer-articles/populate-an-array-input/), and the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

To configure an Array input:

1. Open your website files in your local development environment, or log in to CloudCannon and select the Site for which you want to configure your input.
2. Navigate to the location in the configuration cascade where you want to configure your input. This can be the root of your CloudCannon Configuration File, within the `collections_config.*` key in your CloudCannon Configuration File, a Schema file, the frontmatter of a markup file, or any where you configure a Structure.
3. Identify the `_inputs` key, or create one at that level of the configuration cascade.
4. Add an input name key for your input under the `_inputs` key (a.k.a., `_inputs.*`). We recommend naming your input something simple that indicates the function or context.
5. Add the `type` key under your input name key, with the value `array`.
6. (Optional.) Add any other general configuration keys (e.g., `label`, `comment`, `context`) under your input name key.
7. Define how CloudCannon should populate your input by adding the `structures` key under `_inputs.*.options`, or adding an empty input type.
8. (Optional.) Add any other specific configuration keys under `_inputs.*.options` (e.g., `preview`, `value_key`, `allow_empty`).

CloudCannon will now apply this input configuration to all markup files that use your input name key, without needing to save your configuration. This allows you to make changes to your input configuration and see those changes affect inputs live.

When you are happy with your input configuration, you must save your input configuration.

File: `cloudcannon.config.yml`

```YAML
```

_inputs___1___:
  staff___2___:
    type___3___: array
    options:
      structures___4___: _structures.staff_members

_structures___5___:
  staff_members:
    values:
      - value:
          name:
          position:
          image:

```

**[1]** All inputs are defined under the `_inputs` key, regardless of where they are in the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

**[2]** This Array input is called `staff`.

**[3]** The value of the `type` key determines the input type. This is an `array` input.

**[4]** The `structures` key determines what should populate the input.

**[5]** For more information on Structures, please read our documentation on [structures](/documentation/developer-articles/what-is-a-structure/).
```

When you add your input key name to a data or markup file, your configured Array input will appear in the Data Editor, Visual Editor, or Content Editor.

File: `page.md`

```Markdown

---
staff:
  - name: Karen Key
    position: Project Manager
    image: /images/team/karen_key.jpg
  - name: Holly James
    position: Engineering Team Lead
    image: /images/team/holly_james.jpg
---

Page content goes here.

```

> To allow team members to populate an Array, your input must have at least one item, an entry input type, or a structure.

## Input configuration options

General configuration options are available for all input types. You can define the label, comment, and context box for your Array input, whether it is hidden or disabled, and how CloudCannon should handle configuration at multiple levels of the configuration cascade.

Specific configuration options for Array inputs include defining structures, configuring previews, and how CloudCannon handles empty values. You can also add input validation to require a value, specify the minimum and maximum number of items, or match a regular expression.

Here is an example of an Array input using some of the most commonly used configuration keys.

File: `cloudcannon.config.yml`

```YAML

_inputs:
  page_sections:
    type: array
    options:
      structures: _structures.components
      preview:
        text:
          - key: name
        subtext:
          - key: description
        image:
          - key: my_image
        icon: article
      min_items: 3
      max_items: 5
      required: true

```

For a complete list of configuration keys available for inputs please read our [Inputs](/documentation/developer-reference/configuration-file/types/_inputs/) reference documentation.

These keys configure the appearance and functionality of Array inputs in CloudCannon.

**`_inputs.*.options.structures`** String or object

This key determines which predefined templates to use for populating the Object Input. When configured, team members can select a [structure](/documentation/developer-articles/what-is-a-structure/) to populate the Object with input/input groups. This key has no default.

If configured as an object, CloudCannon will use the values directly.

If configured as a string, CloudCannon will use the matching structures value defined under `_structures` in the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

**`_inputs.*.options.preview`** Object

This key defines the appearance of a Card. You can configure Card preview for [Collections](/documentation/user-articles/what-is-a-collection/), [Schemas](/documentation/developer-articles/what-is-a-schema/), [Object inputs](/documentation/user-articles/what-is-an-object-input/), [Array inputs](/documentation/user-articles/what-is-an-array-input/), [Select inputs](/documentation/user-articles/what-is-a-select-input/), [Structures](/documentation/developer-articles/what-is-a-structure/), the Structure modal, [Snippets](/documentation/developer-articles/what-is-a-snippet/), and the Snippet modal.

The following nested keys are available:

- `text`
- `subtext`
- `icon`
- `icon_color`
- `icon_background_color`
- `image`
- `metadata`
- `gallery`

This key defaults to:

File: `cloudcannon.config.yml`

```YAML
preview:
  text:
    - key: title
    - key: name
  icon:
    - key: icon
```

For more information about previews, please read our documentation on [configuring card previews](/documentation/developer-articles/configure-your-card-previews/).

In this example, we have configured the appearance of file Cards in the *Collection browser*.

File: `cloudcannon.config.yml`

```YAML
collections_config:
  blog:
    preview:
      text:
        - key: title
      subtext:
        - key: author
      icon: edit_note
      icon_color:
        - key: color
        - '#ff0000'
      image:
        - key: image
      metadata:
        - template: [url]
        - icon: event
          text:
            - template: 'Published on {date|date_long}'
      gallery:
        - key: featured_image
```

In this example, we have configured the appearance of Cards in inputs using the Structure `staff`.

File: `cloudcannon.config.yml`

```YAML
_structures:
  staff:
    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
```

**`_inputs.*.options.preview.text`** array, string, or boolean

This key determines the title text displayed on a default Array Input card(s). This key has no default, and falls back to the first nested value found (prioritizing text-based values).

If set to `false`, no text is displayed.

**`_inputs.*.options.preview.subtext`** array, string, or boolean

This key determines the subtitle text displayed on a default Array Input card(s). This key has no default, and falls back to listing the `label` of each nested input. `subtext` is hidden if text and subtext are the same. If there is no text, subtext will appear in the place of text.

If set to `false`, no text is displayed.

**`_inputs.*.options.preview.icon`** Array, string or boolean

This key determines the icon displaye beside the text and subtext on a Card. The value must match a name from the [Google's Material Icons](https://fonts.google.com/icons) list.

This key defaults to checking the `icon` key, then falls back to the `notes` icon.

If set to `false`, no icon is displayed.

If `image` is defined, the image replaces `icon` when loaded successfully.

This key supports cascading options, which can be either an Array or a single value. Value can be one of the following:

- A String of the exact value (e.g `"edit_note"`)
- A reference to a key within the connected item (e.g `key: icon` in YAML or `{ "key": "icon" }` in JSON)
- A String with placeholders that will be replaced with values (e.g. `template:{icon_type}` in YAML or `{ "template": "{icon_type}" }` in JSON)

In this example, we configure a static icon for the card.

File: `cloudcannon.config.yml`

```YAML
preview:
  icon: edit_note
```

In this example, we use a dynamic icon from the data.

File: `cloudcannon.config.yml`

```YAML
preview:
  icon:
    - key: icon_type
    - support_agent
```

**`_inputs.*.options.preview.icon_color`** Array, string or boolean

This key determines the color of the icon displayed on a Card.

This key supports cascading options, which can be either an Array or a single value. Value can be one of the following:

- A String of the exact value (e.g `"#ff0000"`)
- A reference to a key within the connected item (e.g `key: color` in YAML or `{ "key": "color" }` in JSON)
- A String with placeholders that will be replaced with values (e.g. `template:{color_code}` in YAML or `{ "template": "{color_code}" }` in JSON)

By default, this key is `#000000` (black).

In this example, we configure a dynamic icon color from the data with a fallback to red.

File: `cloudcannon.config.yml`

```YAML
preview:
  icon: edit_note
  icon_color:
    - key: color
    - '#ff0000'
```

In this example, we use a static icon color.

File: `cloudcannon.config.yml`

```YAML
preview:
  icon: nature_people
  icon_color:
    - '#00ff00'
```

**`_inputs.*.options.preview.icon_background_color`** Array, string or boolean

This key determines the background color of the icon displayed on a Card. This is useful if your `icon_color` value has poor contrast on a white background.

This key supports cascading options, which can be either an Array or a single value.Value can be one of the following:

- A String of the exact value (e.g `"#ff0000"`)
- A reference to a key within the connected item (e.g `key: color` in YAML or `{ "key": "color" }` in JSON)
- A String with placeholders that will be replaced with values (e.g. `template:{color_code}` in YAML or `{ "template": "{color_code}" }` in JSON)

This key has no default.

In this example, we configure a dynamic icon background color from the data with a fallback to red.

File: `cloudcannon.config.yml`

```YAML
preview:
  icon: edit_note
  icon_background_color:
    - key: color
    - '#ff0000'
```

In this example, we use a static icon background color.

File: `cloudcannon.config.yml`

```YAML
preview:
  icon: nature_people
  icon_background_color:
    - '#00ff00'
```

**`_inputs.*.options.preview.image`** array, string, or boolean

This key determines the image displayed on a default Array Input card(s). This key has no default, and falls back to `thumbnail_image`, `thumbnail_image_path`, `image`, and `image_path` in that order. If no image is found, `icon` is displayed instead.

If set to `false`, no image is displayed.

**`_inputs.*.options.empty_type`** String

This key determines how CloudCannon handles an empty value. This key does not apply to existing empty values.

Value must be one of the following:

- `string` - an empty value for this input will be stored as "".
- `null` - an empty value for this input will be stored as a null value (default). This does not apply to TOML files.

**`_inputs.*.options.disable_add`** Boolean

This key toggles whether you can add new items to an Array Input. When set to `true`, the "Add" button is disabled in editing interfaces.

By default, this key is `false` (i.e., users can add new items to the array).

In this example, we have a `content_blocks` Array Input where users cannot add entries to the Array.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  content_blocks:
    type: array
    label: Categories
    options:
      disable_add: true
      disable_remove: true
```

**`_inputs.*.options.disable_remove`** Boolean

This key toggles whether you can remove items from an Array Input. When set to `true`, CloudCannon will remove the "Delete" option from the Context Menu for each entry.

By default, this key is `false` (i.e., users can remove items from the array).

In this example, we have a `content_blocks` Array Input where users cannot remove entries from the Array.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  content_blocks:
    type: array
    label: Categories
    options:
      disable_add: true
      disable_remove: true
```

**`_inputs.*.options.disable_reorder`** Boolean

This key toggles whether you can reorder items within an Array Input. When set to `true`, CloudCannon will disable the drag-and-drop reordering functionality and remove the "Move Up" and "Move Down" options from the Context Menu for each entry.

By default, this key is `false` (i.e., users can reorder items in the array).

In this example, we have a `staff` Array Input where users cannot reorder the items.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  staff:
    type: array
    label: Our Team
    options:
      disable_reorder: true
```

**`_inputs.*.options.required`** Boolean

This key toggles whether CloudCannon requires this Input to have a value. If set to `true`, CloudCannon will require you to enter a value to save your changes, or discard your unsaved changes.

By default, this key is `false` (i.e, CloudCannon does not require this Input to have a value).

This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.

In this example, we want to require our team to enter an `author` value for markup files with this Input.

File: `cloudcannon.config.yml`

```YAML
  _inputs:
    author:
      type: text
      comment: Enter the name of the author for this blog post.
      options:
        required: true

```

**`_inputs.*.options.required_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.required`. This key requires you to define `options.required`.

This key has no default.

In this example, we prompt our team to use enter an Input value using a required message.

File: `cloudcannon.config.yml`

```YAML
  _inputs:
    author:
      type: text
      comment: Enter the name of the author for this blog post.
      options:
        required: true
        required_message: You are not allowed to leave this blank.

```

**`_inputs.*.options.max_items`** Number

This key defines the maximum number of items CloudCannon will allow in an Input. When configured, CloudCannon will prevent you from adding more items to this Input. If the Input already contains more items, CloudCannon will require you to remove items until the Input contains a valid number to save your changes, or discard your unsaved changes.

Value can be any positive integer. If `options.min_items` is also configured, this key cannot be a lesser number.

This key has no default.

This key is available for Array and Multiselect or Multichoice Inputs.

In this example, we want to add an array of filepaths to our homepage's `featured_posts` Input. This Input limits you to a maximum of five array items.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  featured_posts:
    type: array
    options:
      min_items: 2
      max_items: 5
```

**`_inputs.*.options.max_items_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.max_items`. This key requires you to define `options.max_items`.

This key has no default.

In this example, we prompt our team to enter a valid number of items using a custom message.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  featured_posts:
    type: array
    options:
      max_items: 5
      max_items_message: Cannot be more than 5
      min_items: 2
      min_items_message: Cannot be less than 2
```

**`_inputs.*.options.min_items`** Number

This key defines the minimum number of items CloudCannon will allow in an Input. When configured, CloudCannon will prevent you from removing items from this Input below this value. If the Input already contains fewer items, CloudCannon will require you to add items until the Input contains a valid number to save your changes, or discard your unsaved changes.

Value can be any positive integer. If `options.max_items` is also configured, this key cannot be a greater number.

This key has no default.

This key is available for Array and Multiselect or Multichoice Inputs.

In this example, we want to add an array of filepaths to our homepage's `featured_posts` Input. This Input limits you to a maximum of two array items.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  featured_posts:
    type: array
    options:
      min_items: 2
      max_items: 5
```

**`_inputs.*.options.min_items_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.min_items`. This key requires you to define `options.min_items`.

This key has no default.

This key is available for Array and Multiselect or Multichoice Inputs.

In this example, we prompt our team to enter a valid number of items using a custom message.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  featured_posts:
    type: array
    options:
      max_items: 5
      max_items_message: Cannot be more than 5
      min_items: 2
      min_items_message: Cannot be less than 2
```

**`_inputs.*.options.unique_on`** String

This key defines the JSON Path selector that CloudCannon should use to determine if the value of an Input is unique. When configured, CloudCannon will require the value of the Input to be unique compared to the value defined on the JSON Path. If the Input already contains a non-unique value, CloudCannon will require you to change it to a valid value to save your changes, or discard your unsaved changes.

Value must be a valid JSON Path.

This key has no default.

In this example, we want our team to add article filepaths to the `related_articles` Input. This Input requires all the filepaths to be unique.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  related_articles:
    type: array
    options:
      unique_on: '$.path'
      unique_on_message: The value for path must be different for all items.
```

**`_inputs.*.options.unique_on_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.unique_on`. This key requires you to define `options.unique_on`.

This key has no default.

This key is available for Array inputs.

In this example, we want our team to add article filepaths to the `related_articles` Input. This Input requires all the filepaths to be unique.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  related_articles:
    type: array
    options:
      unique_on: '$.path'
      unique_on_message: The value for path must be different for all items.
```

File: `blog-article.yml`

```YAML
related_articles:
  - path: /articles/first-article.md
    featured: true
  - path: /articles/first-article.md
    featured: false
```

## Valid values

Here are some examples of valid values for an Array input.

**YAML:**

Empty/null value:

- `array: `

Any valid list of values:

```yaml
array:
  - value1
  - value2
  - value3
```

Any valid list of objects:

```yaml
array:
  - name: Item 1
    description: First item
  - name: Item 2
    description: Second item
```

**TOML:**

Any valid array of values:

```toml
array = ["value1", "value2", "value3"]
```

Any valid array of tables:

```toml
[[array]]
name = "Item 1"
description = "First item"

[[array]]
name = "Item 2"
description = "Second item"
```

**JSON:**

Empty/null value:

- `"array": null`

Any valid array of values:

```json
{
      "array": [
        "value1",
        "value2",
        "value3"
      ]
    }
```

Any valid array of objects:

```json
{
      "array": [
        {
          "name": "Item 1",
          "description": "First item"
        },
        {
          "name": "Item 2",
          "description": "Second item"
        }
      ]
    }
```

## Unconfigured Array inputs

In some cases, CloudCannon can still detect an Array input even if you have not configured it.

CloudCannon will interpret any unconfigured input with a list of nested values or keys as an Array input. You cannot create structured Array inputs without configuration.

File: `data.yml`

```YAML

animals:
  - bear
  - lizard
  - swan
  - name: Dog
    fun_fact: Man's best friend.
    image: /images/my-dog.png

```

This behavior is convenient if you have simple inputs or do not want to configure inputs. It is also beneficial for new websites on CloudCannon where you have yet to create any CloudCannon-specific configuration.

> We recommend configuring your inputs for greater control over their functionality and appearance.


---

---
title: Configure an Object input
description: Learn how to configure an Object input to edit x in your data files or front matter.
url: https://cloudcannon.com/documentation/developer-articles/configure-an-object-input/
content_type: developer article
last_modified: 2026-03-29
---

> **Permissions required**
> 
> Members of all [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `site:file:write` permission, can configure inputs in all locations in the configuration cascade. You can limit permission to specific locations in the configuration using [file globs](/documentation/developer-articles/what-are-custom-permission-groups/#specify-a-file-glob).

An [Object input](/documentation/user-articles/what-is-an-object-input/) is an editing interface for nested structured data in data files or front matter. By configuring your inputs, you can customize the appearance and functionality for a better editing experience.

![A screenshot of the Object Input in the Data Editor shows a card previewing the nested title, description, and image.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Object-Input-Closed.webp)

![A screenshot of the nested content within an Object Input in the Data Editor.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Object-Input-Open.webp)

These instructions assume that you know what subtype of Object input you want to configure and where in the configuration cascade. For more information, please read our documentation on [Object inputs](/documentation/user-articles/what-is-an-object-input/), [inputs](/documentation/user-articles/what-are-inputs/) in general, and the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

To configure an Object input:

1. Open your website files in your local development environment, or log in to CloudCannon and select the Site for which you want to configure your input.
2. Navigate to the location in the configuration cascade where you want to configure your input. This can be the root of your CloudCannon Configuration File, within the `collections_config.*` key in your CloudCannon Configuration File, a Schema file, the frontmatter of a markup file, or any where you configure a Structure.
3. Identify the `_inputs` key, or create one at that level of the configuration cascade.
4. Add an input name key for your input under the `_inputs` key (a.k.a., `_inputs.*`). We recommend naming your input something simple that indicates the function or context.
5. Add the `type` key under your input name key, with the value `object`.
6. (Optional.) Add any other general configuration keys (e.g., `label`, `comment`, `context`) under your input name key.
7. Add the `subtype` key under `_inputs.*.options` , with the value `object`, `tabbed`, or `mutable`.
8. (Optional.) Add any other specific configuration keys under `_inputs.*.options` (e.g., `preview`, `structures`, `groups`).

CloudCannon will now apply this input configuration to all markup files that use your input name key, without needing to save your configuration. This allows you to make changes to your input configuration and see those changes affect inputs live.

When you are happy with your input configuration, you must save your input configuration.

File: `cloudcannon.config.yml`

```YAML
```

_inputs___1___:
  seo___2___:
    type___3___: object
    options:
      subtype___4___: object
  event___5___:
    type: object
    options:
      subtype___6___: tabbed
  terminology___7___:
    type: object
    options:
      subtype___8___: mutable

```

**[1]** All inputs are defined under the `_inputs` key, regardless of where they are in the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

**[2]** This Object input is called `seo`.

**[3]** The value of the `type` key determines the input type. This is an `object` input.

**[4]** The value of the `options.subtype` key determines the Object input's subtype. This is an `object` input.

**[5]** This Object input is called `event`.

**[6]** The value of the `options.subtype` key determines the Object input's subtype. This is a `tabbed` input.

**[7]** This Object input is called `terminology`.

**[8]** The value of the `options.subtype` key determines the Object input's subtype. This is a `mutable` input.
```

When you add your input key name to a data or markup file, your configured Object input will appear in the Data Editor, Visual Editor, or Content Editor.

File: `blog.md`

```Markdown

---
seo:
  title: How you can optimize publishing workflows for your content team
  image: /images/logo.svg
  description: CloudCannon's drafting and publishing workflows can tie all of your optimizations together, offering enhanced control, flexibility, and coordination.
event:
  details:
    title:
    image:
    description:
  cast:
    main_cast:
      - Actor A
      - Actor B
      - Actor C
    special_guests:
      - Actor X
      - Actor Y
      - Actor Z
terminology:
  CloudCannon: A CMS for static websites.
  Input: An editing interface for structured data.
  new_term: ''

---

Blog content goes here.

```

> For Object inputs to function correctly, they must contain at least one entry. You can add entries to an Object using the [Source Editor](/documentation/user-articles/what-is-the-source-editor/). Alternatively, you can configure a structure or a mutable Object with an entry input type to allow team members to populate and empty Object.

## Input configuration options

General configuration options are available for all input types. You can define the label, comment, and context box for your Object input, whether it is hidden or disabled, and how CloudCannon should handle configuration at multiple levels of the configuration cascade.

Specific configuration options for Object inputs include defining the format of the input, enabling structures, configuring groups and previews, and how CloudCannon handles empty values. For mutable Objects, you can also configure allowed keys, assigned structures, and label formatting.

Here is an example of an Object input using some of the most commonly used configuration keys.

File: `cloudcannon.config.yml`

```YAML

_inputs:
  homepage_feature:
    type: object
    options:
      subtype: object
      structures: _structures.feature_template
      groups:
        - heading: SEO
          comment: Values for search engines to read
          inputs:
            - title
            - description
            - image
      place_groups_below: false
      preview:
        text: Homepage Feature Image
        subtext: Edit the main image in the header of the homepage.
        icon: photo_library
        image:
          - key: image
      empty_type: string

```

For a complete list of configuration keys available for inputs please read our [Inputs](/documentation/developer-reference/configuration-file/types/_inputs/) reference documentation.

> If you want to configure the root Object in a Structure Value (i.e. `_structures.*.values[*]._inputs.$`), please configure the `tabbed` (replaces the `subtype` key on Object inputs), `groups`, `place_groups_below`, `preview`, `picker_preview`, `comment`, and `documentation` keys on the [Structure Value](/documentation/developer-reference/configuration-file/types/structure/values/[*]/tabbed/) itself.

These keys configure the appearance and functionality of Object inputs in CloudCannon.

**`_inputs.*.options.subtype`** string

This key determines the appearance and function of the input. Defaults to `object`.

Value must be one of the following:

- `object` — clicking on the Object card will open the second scope containing all nested inputs.
- `mutable` — all nested inputs appear on the top scope with controls to add, delete, clone, rename, or remove inputs from within the Object.
- `tabbed` — all nested objects appear as tabs in the top scope.

**`_inputs.*.options.structures`** string or object

This key determines which predefined templates to use for populating the Object Input. When configured, team members can select a [structure](/documentation/developer-articles/what-is-a-structure/) to populate the Object with input/input groups. This key has no default.

If configured as an object, CloudCannon will use the values directly.

If configured as a string, CloudCannon will use the matching structures value defined under `_structures` in the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

> This key looks similar to `entries.structures`. However, the `structures` key applies to the Object input itself, while `entries.structures` applies to the entries within the object.

**`_inputs.*.options.groups`** array of keys

This key allows you to group nested inputs within the Object Input together without changing the data structure. The following nested keys are available:

- `heading`
- `comment`
- `collapsed`
- `inputs`
- `documentation`

Each group should be a new item in the array. Ungrouped inputs appear below groups by default.

This key does not apply to Structured or Mutable Object Inputs.

**`_inputs.*.options.groups[*].heading`** text

This key determines the title text displayed at the top of the group. This text is visible whether a group is expanded or collapsed.

**`_inputs.*.options.groups[*].comment`** text

This key determines the subtitle text displayed at the top of the group. This text is visible whether a group is expanded or collapsed.

**`_inputs.*.options.groups[*].collapsed`** boolean

This key determines whether a group is collapsed by default. Defaults to `false`.

**`_inputs.*.options.groups[*].inputs`** array of strings

This key determines the inputs included in this group. These key names must match a key within the Object Input. Defaults to `[]`.

**`_inputs.*.options.groups[*].documentation`** object

This key enables you to add a custom link below the heading of the group. The following nested keys are available:

- `url` — determines the `href` value of the link (String). This field is required.
- `text` — determines the visible text used in the link (String). Defaults to `Documentation`.
- `icon` — determines the icon displayed next to the link. Must be a [Material Icon](https://fonts.google.com/icons?icon.set=Material+Icons) name. Defaults to `auto_stories`.

**`_inputs.*.options.place_groups_below`** boolean

This key determines whether ungrouped inputs appear below groups or above groups. Defaults to `false`. Has no affect if `groups` is not configured.

**`_inputs.*.options.preview`** object

This key defines the appearance of a Card. You can configure Card preview for [Collections](/documentation/user-articles/what-is-a-collection/), [Schemas](/documentation/developer-articles/what-is-a-schema/), [Object inputs](/documentation/user-articles/what-is-an-object-input/), [Array inputs](/documentation/user-articles/what-is-an-array-input/), [Select inputs](/documentation/user-articles/what-is-a-select-input/), [Structures](/documentation/developer-articles/what-is-a-structure/), the Structure modal, [Snippets](/documentation/developer-articles/what-is-a-snippet/), and the Snippet modal.

The following nested keys are available:

- `text`
- `subtext`
- `icon`
- `icon_color`
- `icon_background_color`
- `image`
- `metadata`
- `gallery`

This key defaults to:

File: `cloudcannon.config.yml`

```YAML
preview:
  text:
    - key: title
    - key: name
  icon:
    - key: icon
```

For more information about previews, please read our documentation on [configuring card previews](/documentation/developer-articles/configure-your-card-previews/).

In this example, we have configured the appearance of file Cards in the *Collection browser*.

File: `cloudcannon.config.yml`

```YAML
collections_config:
  blog:
    preview:
      text:
        - key: title
      subtext:
        - key: author
      icon: edit_note
      icon_color:
        - key: color
        - '#ff0000'
      image:
        - key: image
      metadata:
        - template: [url]
        - icon: event
          text:
            - template: 'Published on {date|date_long}'
      gallery:
        - key: featured_image
```

In this example, we have configured the appearance of Cards in inputs using the Structure `staff`.

File: `cloudcannon.config.yml`

```YAML
_structures:
  staff:
    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
```

**`_inputs.*.options.preview.text`** array, string, or boolean

This key determines the title text displayed on a default Object Input card. This key has no default, and falls back to the first nested value found (prioritizing text-based values).

If set to `false`, no text is displayed.

**`_inputs.*.options.preview.subtext`** array, string, or boolean

This key determines the subtitle text displayed on a default Object Input card. This key has no default, and falls back to listing the `label` of each nested input. `subtext` is hidden if text and subtext are the same. If there is no text, subtext will appear in the place of text.

If set to `false`, no text is displayed.

**`_inputs.*.options.preview.icon`** Array, string or boolean

This key determines the icon displaye beside the text and subtext on a Card. The value must match a name from the [Google's Material Icons](https://fonts.google.com/icons) list.

This key defaults to checking the `icon` key, then falls back to the `notes` icon.

If set to `false`, no icon is displayed.

If `image` is defined, the image replaces `icon` when loaded successfully.

This key supports cascading options, which can be either an Array or a single value. Value can be one of the following:

- A String of the exact value (e.g `"edit_note"`)
- A reference to a key within the connected item (e.g `key: icon` in YAML or `{ "key": "icon" }` in JSON)
- A String with placeholders that will be replaced with values (e.g. `template: {icon_type}` in YAML or `{ "template": "{icon_type}" }` in JSON)

In this example, we configure a static icon for the card.

File: `cloudcannon.config.yml`

```YAML
preview:
  icon: edit_note
```

In this example, we use a dynamic icon from the data.

File: `cloudcannon.config.yml`

```YAML
preview:
  icon:
    - key: icon_type
    - support_agent
```

**`_inputs.*.options.preview.icon_color`** Array, string or boolean

This key determines the color of the icon displayed on a Card.

This key supports cascading options, which can be either an Array or a single value. Value can be one of the following:

- A String of the exact value (e.g `"#ff0000"`)
- A reference to a key within the connected item (e.g `key: color` in YAML or `{ "key": "color" }` in JSON)
- A String with placeholders that will be replaced with values (e.g. `template: {color_code}` in YAML or `{ "template": "{color_code}" }` in JSON)

By default, this key is `#000000` (black).

In this example, we configure a dynamic icon color from the data with a fallback to red.

File: `cloudcannon.config.yml`

```YAML
preview:
  icon: edit_note
  icon_color:
    - key: color
    - '#ff0000'
```

In this example, we use a static icon color.

File: `cloudcannon.config.yml`

```YAML
preview:
  icon: nature_people
  icon_color:
    - '#00ff00'
```

**`_inputs.*.options.preview.icon_background_color`** Array, string or boolean

This key determines the background color of the icon displayed on a Card. This is useful if your `icon_color` value has poor contrast on a white background.

This key supports cascading options, which can be either an Array or a single value.Value can be one of the following:

- A String of the exact value (e.g `"#ff0000"`)
- A reference to a key within the connected item (e.g `key: color` in YAML or `{ "key": "color" }` in JSON)
- A String with placeholders that will be replaced with values (e.g. `template: {color_code}` in YAML or `{ "template": "{color_code}" }` in JSON)

This key has no default.

In this example, we configure a dynamic icon background color from the data with a fallback to red.

File: `cloudcannon.config.yml`

```YAML
preview:
  icon: edit_note
  icon_background_color:
    - key: color
    - '#ff0000'
```

In this example, we use a static icon background color.

File: `cloudcannon.config.yml`

```YAML
preview:
  icon: nature_people
  icon_background_color:
    - '#00ff00'
```

**`_inputs.*.options.preview.image`** array, string, or boolean

This key determines the image displayed on a default Object Input card. This key has no default, and falls back to `thumbnail_image`, `thumbnail_image_path`, `image`, and `image_path` in that order. If no image is found, `icon` is displayed instead.

If set to `false`, no image is displayed.

**`_inputs.*.options.empty_type`** String

This key determines how CloudCannon handles an empty value. This key does not apply to existing empty values.

Value must be one of the following:

- `string` - an empty value for this input will be stored as "".
- `null` - an empty value for this input will be stored as a null value (default). This does not apply to TOML files.

**`_inputs.*.options.required`** Boolean

This key toggles whether CloudCannon requires this Input to have a value. If set to `true`, CloudCannon will require you to enter a value to save your changes, or discard your unsaved changes.

By default, this key is `false` (i.e, CloudCannon does not require this Input to have a value).

This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.

In this example, we want to require our team to enter an `author` value for markup files with this Input.

File: `cloudcannon.config.yml`

```YAML
  _inputs:
    author:
      type: text
      comment: Enter the name of the author for this blog post.
      options:
        required: true

```

**`_inputs.*.options.required_message`** String

This key defines a custom error message that explains why a value has failed the validation criteria from `options.required`. This key requires you to define `options.required`.

This key has no default.

This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.

In this example, we prompt our team to use enter an Input value using a required message.

File: `cloudcannon.config.yml`

```YAML
  _inputs:
    author:
      type: text
      comment: Enter the name of the author for this blog post.
      options:
        required: true
        required_message: You are not allowed to leave this blank.

```

If the input is a mutable Object, the following options are also available:

File: `cloudcannon.config.yml`

```YAML

_inputs:
  example:
    type: object
    options:
      subtype: mutable
      entries:
        allowed_keys:
          - image
          - link
          - link_or_image
        structures:
          values:
            - id: image_template
              label: Image
              icon: image
              value:
                image:
                caption:
            - id: link_template
              label: External link
              icon: link
              value:
                url:
                title:
        assigned_structures:
          link:
            - link_template
          image:
            - image_template
          link_or_image:
            - image_template
            - link_template
        comment: Select a key name.
        documentation:
          url: /documentation/user-articles/what-is-an-object-input/
          text: Documentation
          icon: help
      allow_label_formatting: true

```

**`entries`** object

This key enables you to define the appearance and function of entries in a mutable object. The following nested keys are available:

- `allowed_keys`
- `structures`
- `assigned_structures`
- `comment`
- `documentation`

Available for Mutable Objects only.

**`entries.allowed_keys`** array

This key defines a limited set of key names for nested keys within your Object Input. This affects entries when adding or renaming nested keys. Defaults to `[]`.

Available for Mutable Objects only.

**`entries.structures`** string or object

This key determines which predefined templates to use for populating entries nested in the Object Input. When configured, team members can select a [structure](/documentation/developer-articles/what-is-a-structure/) to populate the Object with input/input groups. This key has no default.

If configured as an object, CloudCannon will use the values directly.

If configured as a string, CloudCannon will use the matching structures value defined under `_structures` in the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

Available for Mutable Objects only.

> This key looks similar to `structures`. However, the `structures` key applies to the Object input itself, while `entries.structures` applies to the entries within the object.

**`entries.assigned_structures`** object

This key enables you to assign structures to specific key names for entries in the Object Input. When selecting an entry key name, CloudCannon will prompt to to choose one of the assigned structures for that allowed key. Structure values are referred to by their `id`.

Available for Mutable Objects only.

**`entries.comment`** text

This key determines the subtitle text above the key input. This key has no default, and supports a limited selection of Markdown formatting in value text: links, bold, italic, subscript, superscript, inline code elements are allowed.

Available for Mutable Objects only.

**`entries.documentation`** object

This key enables you to add a custom link above the key input. The following nested keys are available:

- `url` - determines the `href` value of the link (String). This field is required.
- `text` - determines the visible text used in the link (String). Defaults to `Documentation`.
- `icon` - determines the icon displayed next to the link. Must be a [Material Icon](https://fonts.google.com/icons?icon.set=Material+Icons) name. Defaults to `auto_stories`.

Available for Mutable Objects only.

**`allow_label_formatting`** boolean

This key determines whether labels on mutable object entries are formatted. Defaults to `false`.

Available for Mutable Objects only.

## Valid values

Here are some examples of valid values for an Object input.

**YAML:**

Empty/null value:

- `object: `

Any valid nested key-value pairs:

```yaml
object:
  key1: value1
  key2: value2
  nested_object:
    key3: value3
```

**TOML:**

Any valid nested key-value pairs:

```toml
[object]
key1 = "value1"
key2 = "value2"

[object.nested_object]
key3 = "value3"
```

**JSON:**

Empty/null value:

- `"object": null`

Any valid nested key-value pairs:

```json
{
  "object": {
    "key1": "value1",
    "key2": "value2",
    "nested_object": {
      "key3": "value3"
    }
  }
}
```

## Unconfigured Object inputs

In some cases, CloudCannon can still detect an Object input even if you have not configured it.

CloudCannon will interpret any unconfigured input with nested keys as an Object input. You cannot create structured or mutable Object inputs without configuration.

File: `data.yml`

```YAML

company_photo:
  image:
  date:
  description:

```

This behavior is convenient if you have simple inputs or do not want to configure inputs. It is also beneficial for new websites on CloudCannon where you have yet to create any CloudCannon-specific configuration.

> We recommend configuring your inputs for greater control over their functionality and appearance.


---

---
title: Configure an upstream commit message template
description: Learn how to configure the commit message template for merges that update your Site from its upstream Publish Branch.
url: https://cloudcannon.com/documentation/developer-articles/configure-an-upstream-commit-message-template/
content_type: developer article
last_modified: 2026-04-11
---

[Updating from a Publish Branch](/documentation/user-articles/update-from-a-publish-branch/) will merge upstream changes with a merge commit or pull request. You can configure a commit message for these merges in your [CloudCannon configuration file](/documentation/developer-articles/create-your-cloudcannon-configuration-file/). Configuring a commit message will help you to maintain a consistent format.

Upstream commit messages use [template strings](/documentation/developer-articles/configure-your-template-strings/). To add an upstream commit template, add the key `upstream_commit_template` to the root level of your global configuration file.

Your `upstream_commit_template` should look something like this:

File: `/cloudcannon.config.yml`

```YAML

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

```

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


---

---
title: Configure Array Editable Regions
description: Learn how to configure Array and Array Item Editable Regions to enable array editing in the Visual Editor.
url: https://cloudcannon.com/documentation/developer-articles/configure-array-editable-regions/
content_type: developer article
last_modified: 2026-02-12
---

> **Permissions required**
> 
> Members of the Owners, Developers, and Technical Editors [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `site:source-editor:write` permission, can add *Editable Regions* to files using the Source Editor in CloudCannon.

Array and Array Item *Editable Regions* are one type of [Editable Region](/documentation/developer-articles/what-are-editable-regions/) you can add to your layout and HTML-like files to enable visual editing. Array *Editable Regions* allow you to add, remove, and reorder array values stored in structured data or front matter that populate templating in layout files. You can use Array *Editable Regions* to edit array components or support page building in the Visual Editor.

> To avoid misconfiguration issues where CloudCannon cannot find the data property you want to edit, always add *Editable Regions* to values closest to the root of the file first (i.e., work from parent elements towards child elements).

These instructions assume you know if you have a simple or complex array, have configured your [build settings](/documentation/developer-articles/configure-your-first-build/), and are comfortable editing HTML layouts, either in CloudCannon's [Source Editor](/documentation/user-articles/what-is-the-source-editor/) or your local development environment.

To configure Array *Editable Regions* in the [Visual Editor](/documentation/user-articles/what-is-the-visual-editor/):

1. Identify the file to which you want to add an Array *Editable Regions*.
2. If you have a complex array, you must register each type of array item as a component. For more information, please read our documentation on [configuring Component Editable Regions](/documentation/developer-articles/configure-component-editable-regions/).
3. Open the file in CloudCannon's Source Editor or your local development environment.
4. Identify the templating responsible for looping over your array and add the `data-editable="array"` HTML attribute to the immediate parent element tag. If no appropriate tags are available, wrap the templating in the `<editable-array>` web component.
5. Add the `data-prop=""` HTML attribute to the same DOM element, or to the `<editable-array>` web component. The value of `data-prop` should be the path the to data property you want to edit.
6. If you have a complex array, you must add the `data-id-key` HTML attribute to the same DOM element, or to the `<editable-array>` web component. The value of `data-id-key` should be the structured data key that stores the name of your array item (e.g., `block_name`).
7. If you have a complex array, you must add the `data-component-key` HTML attribute to the same DOM element, or to the `<editable-array>` web component. The value of `data-component-key` should be the structured data key that stores the name of your component (e.g., `block_name`).
8. Identify the HTML attribute within your array templating that contains your array item and add the `data-editable="array-item"` HTML attribute. If no appropriate tags are available, wrap the content of the array item in the `<editable-array-item>` web component.
9. If you have a complex array, you must add the `data-id` HTML attribute to the same DOM element, or to the `<editable-array-item>` web component. The value of `data-id` should be a templating that will populate with the value of the `data-id-key` key (i.e. `{block_name}`).
10. If you have a complex array, you must add the `data-component` HTML attribute to the same DOM element, or to the `<editable-array-item>` web component. The value of `data-component` should be a templating that will populate with the value of the `data-component-key` key (i.e. `{block_name}`).
11. Optional. If you also want to edit the contents of each array item in the Visual Editor, add [Text Editable Regions](/documentation/developer-articles/configure-text-editable-regions/) or [Image Editable Regions](/documentation/developer-articles/configure-image-editable-regions/) to the content inside each array item.
12. Save the change to your *Site*. CloudCannon will automatically rebuild your *Site*.

When you open the file in the Visual Editor, CloudCannon will show yellow *Editable Region* boxes around each array item. When you hover an array item, CloudCannon will show a small toolbar in the top right, containing an *Edit* button and a *Drag* handler. Clicking the *Edit* button will open a dropdown with options to move an array item one position to the left or right, and to delete the item. Clicking and holding the *Drag* handler allows you to visually move an array item to any position in the array.

> **Where should the Array and Array Item*****Editable Regions*** **go?**
> 
> The Array attribute or web component should be the immediate parent element of your array templating. The Array Item attribute or web component should be the first child element of your array templating. This way, Array and Array Item should flank the templating for looping over your array.
> 
> Try to avoid any nested elements between them; they should be as close together as possible, regardless of whether you use HTML attributes, web components, or both.

## Examples

Here are a few examples of different Array *Editable Regions*.

In this example of a simple array, the `testimonials.md` file contains array items with the same structure.

File: `testimonials.md`

```Markdown

---
layout: ../layouts/TestimonialsLayout.astro
testimonials:
  - image: /astro-blog/blog-placeholder-2.jpg
    image_alt: Profile photo of D. Gale
    name: D. Gale
    job_title: CEO at Yellow Brick Industries
    quote: >-
      "In pretium libero sed velit posuere sagittis."
  - image: /astro-blog/blog-placeholder-3.jpg
    image_alt: Profile photo of S. Crow
    name: S. Crow
    job_title: CBO at Yellow Brick Industries
    quote: >-
      "Mauris at augue quis orci egestas eu in nulla."
  - image: /astro-blog/blog-placeholder-4.jpg
    image_alt: Profile photo of T. Man
    name: T. Man
    job_title: CHO at Yellow Brick Industries
    quote: >-
      "Nunc ut sem vitae tortor volutpat varius."
  - image: /astro-blog/blog-placeholder-5.jpg
    image_alt: Profile photo of C. Lion
    name: C. Lion
    job_title: CCO at Yellow Brick Industries
    quote: >-
      "Aenean pharetra orci ac tincidunt lobortis."
---

```

File: `TestimonialsLayout.astro`

```Astro
```

---
const { testimonials } = Astro.props.frontmatter;
---

<!doctype html>
<html lang="en">
  <body>
    <main>
      <section>
        <ul data-editable="array" data-prop="testimonials"> /*1*/
          {
            testimonials.map((testimonial) => (
              <li data-editable="array-item" >
                {testimonial.image && (
                  <img
                    data-editable="image"
                    data-prop-src="image"
                    data-prop-alt="image_alt"
                    width={720}
                    height={360}
                    src={testimonial.image}
                    alt={testimonial.image_alt}
                  /> /*2*/
                )}
                <h4 class="name" data-editable="text" data-prop="name">{testimonial.name}</h4> /*3*/
                <p class="job" data-editable="text" data-prop="job_title">{testimonial.job_title}</p> /*4*/
                <p class="quote" data-editable="text" data-prop="quote">{testimonial.quote}</p> /*5*/
              </li>
            ))
          }
        </ul>
      </section>
    </main>
  </body>
</html>

```

**[1]** The `data-editable` attribute defines what kind of data this element contains, and the `data-prop` attribute defines the path to the data we want to edit. In this case, we want an Array *Editable Region*, so the value of `data-editable` is `array`, and we want to edit the `testimonials` structured data key in the file front matter.

**[2]** This `<img>` element contains `data-editable="image"`, `data-prop-src="image"`, and `data-prop-alt="image_alt"` to define an Image *Editable Region*.

**[3]** This `<h4>` element contains `data-editable="text"` and `data-prop="name"` to define a Text *Editable Region*.

**[4]** This `<p>` element contains `data-editable="text"` and `data-prop="job_title"` to define a Text *Editable Region*.

**[5]** This `<p>` element contains `data-editable="text"` and `data-prop="quote"` to define a Text *Editable Region*.
```

In this example of a complex array, the `about.md` file contains array items with different structures.

File: `src/scripts/register-components.js`

```JavaScript
```

import { registerAstroComponent } from '@cloudcannon/editable-regions/astro';
import '@cloudcannon/editable-regions/astro-react-renderer'; /*1*/
import HeroBlock from '../components/HeroBlock.astro';
import StatsBlock from '../components/StatsBlock.astro';
import ContactBlock from '../components/ContactBlock.astro';

// Register your components
registerAstroComponent('HeroBlock', HeroBlock);
registerAstroComponent('StatsBlock', StatsBlock);
registerAstroComponent('ContactBlock', ContactBlock);

```

**[1]** This import is only necessary if you use React components nested inside your Astro components.
```

File: `about.md`

```Markdown

---
layout: ../layouts/AboutLayout.astro
contentBlocks:
  - _name: HeroBlock
    title: We're on a mission
    description: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce lobortis mi sed est dapibus, sit amet consectetur quam euismod. Cras pretium quam vitae malesuada placerat. Curabitur ac sagittis ligula. Nunc sed ultrices leo. Vestibulum malesuada lobortis nisl, a feugiat est viverra et.
  - _name: StatsBlock
    stats:
      - figure: $200m
        text: Venture capital raised
      - figure: "2016"
        text: Established in
      - figure: 40+
        text: Amazing team members
      - figure: 44325+
        text: Active users and growing
  - _name: ContactBlock
    text: Want to get in contact with us?
    button: Click here
    image: https://preview.astro.new/blog/_astro/blog-placeholder-about.BtEdEmGp_1cKsnD.webp
---

```

File: `AboutLayout.astro`

```Astro

---
const components = {};
const componentImports = import.meta.glob("../components/**/*.astro", {
  eager: true,
});
Object.entries(componentImports).forEach(([path, obj]) => {
  const name = path.replace("../components/", "").split(".")[0];
  components[name] = obj.default;
});

const { contentBlocks } = Astro.props.frontmatter;
---

<main data-editable="array" data-prop="contentBlocks" data-id-key="_name" data-component-key="_name">
  {
    contentBlocks.map((block) => {
      const Component = components[block._name];
      return (
        <section data-editable="array-item" data-id={block._name} data-component={block._name}>
          <Component {...block} />
        </section>
      );
    })
  }
</main>

```

## Misconfigured Array *Editable Regions*

CloudCannon will display an orange warning box in the Visual Editor if your Array *Editable Regions* is misconfigured.

Array *Editable Regions* are misconfigured if:

- You did not define the `data-prop` HTML attribute.
- The *Editable Region* has an invalid data type (e.g., your Text region has a number or object, instead of a string).
- You have one or more orphaned Array Item *Editable Regions* that are not contained within an Array *Editable Region*.


---

---
title: Configure authenticated routes
description: Learn about authenticated routes and how you can use them to require authentication for specific parts of your website.
url: https://cloudcannon.com/documentation/developer-articles/configure-authenticated-routes/
content_type: developer article
last_modified: 2026-04-11
---

> This feature is only available for Sites [hosted through CloudCannon](/documentation/user-articles/what-is-web-hosting/#hosting-on-cloud-cannon). If you host your Site externally, or use CloudCannon in [Headless Mode](/documentation/developer-articles/what-is-headless-mode/), this feature will not work.

An authenticated route is a URL that requires visitors to authenticate their identity before they can see the content.

When you [enable password authentication](/documentation/developer-articles/enable-password-authentication/), [enable user account authentication](/documentation/developer-articles/enable-user-account-authentication/), or [enable SAML authentication](/documentation/developer-articles/enable-saml-authentication/), CloudCannon requires authentication on all routes by default. However, you can specify authenticated routes to require authentication for specific parts of your Site. For example, you could require password authentication for a "Staff Only" section of your website while the other pages remain publicly available.

You can specify which routes should use authentication in an `auth-routes.txt` file. This file should be in the root directory of your output Site. Where this is in your Site repository will depend on your SSG (e.g., the root of the repository for Jekyll, the static folder for Hugo, etc.).

To specify authenticated routes:

1. Navigate to the root directory of your output Site using the *File browser*.
2. Create a file called `auth-routes.txt`.
3. For each URL you want to authenticate, add the route on a new line of the file.
4. Save your page to your Site.
5. Navigate to the *Authentication* page under *Site Settings*.
6. Enable password, user account, or SAML authentication.

CloudCannon will apply the authentication method you select to the routes specified in the `auth-routes.txt` file.

> You can use the `*` character in a route to specify multiple subfolders or files.

Here is an example of a basic authenticated routes file:

File: `auth-routes.txt`

```

/internal-news.html
/staff/*

```


---

---
title: Configure caching between builds
description: Learn how to cache files and folders between builds to speed up subsequent builds.
url: https://cloudcannon.com/documentation/developer-articles/configure-caching-between-builds/
content_type: developer article
last_modified: 2026-04-11
---

CloudCannon lets you choose certain files and folders to cache between builds. This can let you bypass install steps, speeding up subsequent builds.

### Preserved paths

Preserved Paths let you set a comma-separated list of paths that should not be deleted in subsequent builds. These can be folders or full filenames.

Be careful caching files, as this could result in files sticking around after deleting them from the repo. A good rule is that these paths should also be good examples of paths for your `.gitignore` file.

If you are doing any image processing or plugin-level caching, specify that directory, or the full filename. A specific example would be caching your `node_modules/` directory, which would allow `npm install` commands to run more quickly on subsequent builds.

To update your preserved paths:

1. Navigate to the *Configuration* tab under *Site Settings*, and *Builds*.
2. Click on the *Caching Options* card to expand it.
3. Enter a comma-separated list of file paths you want to preserve between builds.
4. Click the *Update Configuration* button.

> Your preserved paths may not be retrieved from cache if your build is allocated to a different server, or if the server has been restarted since your last build.

## Caching Gem installs

Installing your Gems can take quite some time.

To save time on consecutive builds CloudCannon does the following:

1. Installs your gems to a local folder
2. Caches that folder based on your `Gemfile.lock`
3. When no local gems are found, CloudCannon will build your site using the cached installs from your previous build

To disable this feature, go to *Site Settings* / *Build*.

> Older Jekyll sites on CloudCannon will have this caching disabled to prevent changes to their build environment. Enabling this can greatly improve editing experience.


---

---
title: Configure CloudCannon DNS
description: Learn how to configure CloudCannon DNS for your Site.
url: https://cloudcannon.com/documentation/developer-articles/configure-cloudcannon-dns/
content_type: developer article
last_modified: 2026-03-29
---

CloudCannon DNS allows you to manage your DNS records within CloudCannon for each [Custom Domain](/documentation/developer-articles/what-is-a-custom-domain/) added to your [Organization](/documentation/user-articles/what-is-an-organization/). If you use CloudCannon DNS, you can also use a free [auto-generated SSL certificate](/documentation/developer-articles/add-an-auto-generated-ssl-certificate/) for your Sites.

Before configuring your Site's DNS, you must [add a Custom Domain](/documentation/developer-articles/add-a-custom-domain-to-your-site/).

## Enable CloudCannon DNS

CloudCannon enables CloudCannon DNS for your Site by default. If you want to switch back to CloudCannon DNS from an external DNS service or confirm that you have CloudCannon DNS enabled, you can check the *Domain Settings* page.

> Updating your DNS provider can cause downtime for anything connected to your domain, such as your website or custom email address. Please make sure you have a copy of your existing DNS records before you change providers.
> 
> If you need help updating your DNS, please contact our friendly [support team](/support/).

To switch to CloudCannon DNS:

1. Click the *Domains* button in the *App Sidebar*. CloudCannon will open the *Domain Browser*.
2. Select the domain for which you want to configure DNS by clicking on the *Domain Card*. CloudCannon will open the *Domain* page.
3. Click the *Domain Settings* tab.
4. Under *DNS Provider*, select the *CloudCannon DNS* option.
5. Click the *Update Domain* button.

CloudCannon will now manage your DNS records.

![A screenshot of the Domain Settings page shows the DNS Provider radio button is set to CloudCannon DNS.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Domain-Settings-CloudCannon-DNS.webp)

## Configure your nameservers

If you have yet to configure your nameservers or have done so incorrectly, CloudCannon will display a warning with setup instructions. You can find this warning in two places: the *Network* tab of your *Domain* page, and the *Custom Domain* page under *Site Settings*.

![A screenshot of the Domain Network page shows the nameserver setup instructions for a domain with misconfigured nameservers.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Domain-Network-Nameserver-Setup.webp)

![A screenshot of the Custom Domain page under Site Settings shows the nameserver setup warning.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Custom-Domain-Nameserver-Warning.webp)

Configuring your nameservers requires you to use the services provided by your domain registrar. For support, please contact your domain registrar.

To configure your nameservers:

1. Log in to your third-party domain registrar with the account details used when you purchased your domain name. If you don't know who your domain registrar is, you can enter the domain name into the [ICANN website](https://lookup.icann.org/en/lookup) and scroll down to Registrar Information.
2. Update the nameserver configuration on your domain registrar to the *Expected Nameservers* listed on the *Custom Domain* page. Normally, these are *asa.ns.cloudflare.com* and *roan.ns.cloudflare.com*.

CloudCannon will update the *Custom Domain* page once your registrar has propagated the updated nameservers. To refresh the page, click the *Check again* button at the bottom.

> Domain registrars typically process nameserver updates within 24 hours.

![A screenshot of the Domain Network page shows that nameservers are correctly configured.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Domain-Network-Nameserver-Success.webp)

![A screenshot of the Custom Domain page under Site Settings shows that nameservers are correctly configured.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Custom-Domain-Nameserver-Success.webp)

## Add DNS records

[DNS records](/documentation/developer-articles/what-is-dns/#what-are-dns-records) are instructions for a Domain Name managed by an authoritative nameserver. By enabling CloudCannon DNS, you allow CloudCannon's servers to manage your DNS records.

To add a DNS record:

1. Click the *Domains* button in the *App Sidebar*. CloudCannon will open the *Domain Browser*.
2. Select the domain for which you want to configure DNS by clicking on the *Domain Card*. CloudCannon will open the *Domain* page.
3. Click the *DNS* tab.
4. Click the *Add Record* button.
5. In the *Add DNS record* modal, use the *Type* dropdown to select the type of record. Valid options include *A*, *AAAA*, *CNAME*, *MX*, *SPF*, *SRV*, and *TXT*. CloudCannon will update the available fields depending on the record type.
6. Enter the details for your DNS record.
7. (Optional.) Add a *Comment* to your DNS record to help your team members understand the purpose of the record.
8. Click the *Add Record* button.

CloudCannon will add the DNS record to your DNS settings.

![A screenshot of the DNS tab on the Domain page showing the Add DNS Record modal with fields for Type, Name, IPv4 Address and TTL.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Domain-DNS-Add-Record-Modal.webp)

You can edit or delete existing DNS records by clicking the *Context Menu* button for a record and selecting the *Update* or *Remove* option.

### CloudCannon CNAME records

When you enable CloudCannon DNS, CloudCannon will add two CNAME records to your DNS records.

1. *.example.com is an alias for sites.cloudcannon.com
2. example.com is an alias for sites.cloudcannon.com

These records instruct servers completing a DNS lookup for your Site's base domain (and all its subdomains) to search for the IP address of sites.cloudcannon.com. This allows users looking for your website to find the IP address of the CloudCannon server hosting your Site.


---

---
title: Configure Component Editable Regions
description: Learn how to configure Component Editable Regions to edit Astro or React components in the Visual Editor.
url: https://cloudcannon.com/documentation/developer-articles/configure-component-editable-regions/
content_type: developer article
last_modified: 2026-03-29
---

> **Permissions required**
> 
> Members of the Owners, Developers, and Technical Editors [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `site:source-editor:write` permission, can add *Editable Regions* to files using the Source Editor in CloudCannon.

Component *Editable Regions* are one type of [Editable Region](/documentation/developer-articles/what-are-editable-regions/) you can add to your layout and HTML-like files to enable visual editing. Component *Editable Regions* allow you to re-render your components in the Visual Editor when you edit the values in the data panel or sidebar.

Component *Editable Regions* are also required to edit Text or Image *Editable Regions* nested inside a component.

> To avoid misconfiguration issues where CloudCannon cannot find the data property you want to edit, always add *Editable Regions* to values closest to the root of the file first (i.e., work from parent elements towards child elements).

These instructions assume you have configured your [build settings](/documentation/developer-articles/configure-your-first-build/), are comfortable editing HTML layouts, either in CloudCannon's [Source Editor](/documentation/user-articles/what-is-the-source-editor/) or your local development environment, and are using Astro or React components.

To configure Component *Editable Regions* in the [Visual Editor](/documentation/user-articles/what-is-the-visual-editor/):

1. Install the CloudCannon *Editable Regions* NPM package by opening your website project in your local development environment and running the `npm install @cloudcannon/editable-regions` command in your terminal.
2. Create a registration file for your components (e.g., `src/scripts/register-components.js`).
3. Identify the file to which you want to add a Component *Editable Region*. We recommend any layout file that references a component and outputs to an HTML page at build time.
4. Open the file in CloudCannon's Source Editor or your local development environment.
5. At the top of your layout file, import the component registration file. Optionally, you can import your registration file only if the window is in Editor Mode (i.e., your webpage is open in CloudCannon's Visual Editor).
6. Identify the component HTML element and add the HTML attribute `data-editable="component"` . If no DOM element is available, you can wrap the templating in the `<editable-component>` web component.
7. Add the `data-prop=""` HTML attribute to the same DOM element, or to the `<editable-component>` web component. The value of `data-prop` should be the path the to data property you want to edit.
8. Add the `data-component=""` HTML attribute to the same DOM element, or to the `<editable-component>` web component. The value of `data-component` should be the name of the component in your registration script file.
9. Optional. If you also want to edit the text or image contents of your component in the Visual Editor, add other types of *Editable Regions* to the component layout file.
10. Save the change to your *Site*. CloudCannon will automatically rebuild your *Site*.

When you open the file in the Visual Editor, CloudCannon will show a yellow *Editable Regions* box around the component in the Visual Editor. If you added Text or Image *Editable Regions* to your component file, yellow *Editable Regions* boxes will also appear around the content.

![A screenshot of the Visual Editor shows a yellow Editable Region box around the Call to Action component on the blog page.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Visual-Editor-Component-Editable-Region.webp)

When you click into the Component *Editable Region*, CloudCannon will open a data panel with inputs for all structured data keys in the component.

## Examples

Here is an example of files required for a Component *Editable Region*:

File: `src/scripts/register-components.js`

```JavaScript

import { registerAstroComponent } from '@cloudcannon/editable-regions/astro';
import CTA from '../components/CTA.astro';

// Register your components
registerAstroComponent('cta', CTA);

```

File: `first-post.mdx`

```Markdown

---
title: 'First post'
author: 'C. Kent'
heroImage: '../../assets/blog-banner.jpg'
heroImageTitle: 'Blog gradient'
heroImageAlt: 'An eye-catching color gradient banner.'
cta:
  description: "Need a little more help? Send a message to our friendly support team."
  link: "https://www.cloudcannon.com/support/"
  buttonText: "Send a message"
  buttonColor: "#034AD8"
---

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Vitae ultricies leo integer malesuada nunc vel risus commodo viverra.

```

File: `BlogPost.astro`

```Astro
```

---
import CTA from '../components/CTA.astro';
---

<html lang="en">
	<body>
		<main>
			<article>
                <!-- Blog HTML here -->
			</article>
			<CTA {...Astro.props.cta} /> /*1*/
		</main>
	</body>
</html>

```

**[1]** The `<CTA>` component uses structured data in the front matter of the files in the Blog collection.
```

File: `components/CTA.astro`

```Astro
```

---
const { description, link, buttonText, buttonColor } = Astro.props;
---

<p data-editable="text" data-prop="description">{description}</p>
<a href={link}>
    <button data-editable="text" data-prop="buttonText" style={`background-color: ${buttonColor}`}>{buttonText}</button>
</a>

```

**[1]** This `<p>` element contains `data-editable="text"` and `data-prop="description"` to define a Text *Editable Region*.

**[2]** This `<button>` element contains `data-editable="text"` and `data-prop="buttonText"` to define a Text *Editable Region*.
```

## Misconfigured Component *Editable Regions*

If you accidentally misconfigure your *Editable Regions*, CloudCannon will display a red warning box in the Visual Editor.

Component *Editable Regions* are misconfigured if:

- You did not define the `data-prop` or `data-component`HTML attributes.
- The *Editable Region* has an invalid data type (e.g., your Text region has a number or object, instead of a string).
- You reference a component that does not exist, or has not been registered.
- Component rendering errors
- Invalid component return values


---

---
title: Configure custom routing
description: Configure your Site's hosting by configuring a single JSON file.
url: https://cloudcannon.com/documentation/developer-articles/configure-custom-routing/
content_type: developer article
last_modified: 2026-04-11
---

> This feature is only available for Sites [hosted through CloudCannon](/documentation/user-articles/what-is-web-hosting/#hosting-on-cloud-cannon). If you host your Site externally, or use CloudCannon in [Headless Mode](/documentation/developer-articles/what-is-headless-mode/), this feature will not work.

Custom routing allows you to control which content is delivered to your visitors when they enter a URL in their internet browser. You can create custom routing by creating a `routing.json` file in your `.cloudcannon` folder. When a visitor requests your webpage, CloudCannon will also load the `routing.json` file to extend the default routing behavior.

Your custom routing file can specify [redirects](/documentation/developer-articles/configure-custom-routing/#custom-redirects) and [headers](/documentation/developer-articles/configure-custom-routing/#custom-headers) using JSON data.

- **Custom redirect** — an instruction to redirect a visitor from one URL to another.
- **Custom header** — additional information passed between the web server and the client (e.g., visitor's browser).

> Invalid JSON data in the `routing.json` file will cause your Site [builds](/documentation/developer-articles/what-is-a-site-build/) to fail, protecting the live version of your Site. You can troubleshoot your JSON using the [build output logs](/documentation/developer-articles/what-is-a-site-build/#reading-your-build-output-logs).

To create a blank custom routing file:

1. Navigate to the `.cloudcannon` folder using the *File browser*, or create one in the root of your Site.
2. Click the *+ Add* button at the top right of the browser and select the *+ Create new file* option from the dropdown. CloudCannon will open a blank `.txt` file in the Source Editor.
3. Click the *Save* button in the top right of the editing interface. CloudCannon will open the *Review changes* modal.
4. Edit the file path to "/.cloudcannon/routing.json" and click the *Save selected* button in the bottom right of the modal.

CloudCannon will save a blank `routing.json` file in your `.cloudcannon` folder.

If you would prefer, you can also create a `routing.json` file using your local development environment.

For a complete list of options available in the `routing.json` file, please read our [routing reference](/documentation/developer-reference/routing-file/) documentation.

## Custom Routes

When CloudCannon loads the `routing.json` file each time a visitor requests a URL, the first matching routing rule can control what content is delivered to the visitor by redirecting them to a different URL or serving a different content without changing the URL (i.e., a proxy). You can specify the type of custom route using an [HTTP status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes).

CloudCannon supports the following redirect codes:

- **301** — Indicates the requested URL has been changed permanently.
- **302** — Indicates the requested URL has been changed temporarily, and the visitor's browser should continue to use the original URL in future requests.
- **307** — Indicates the requested URL has been changed temporarily and the visitor's browser should continue to use the original URL in future requests. This is similar to a 302 code however it does not allow the HTTP method to change.
- **308** — Indicates the requested URL has been changed permanently. This is similar to a 301 code however it does not allow the HTTP method to change.

CloudCannon supports the following proxy codes:

- **200** — Indicates the request was successful.
- **404** — Indicates the requested URL could not be found.
- **410** — Indicates the requested URL has been permanently deleted, and search engines should de-index this page.

When configuring custom routing, most users will only need the 307, 308, and 404 status codes.

We recommend redirecting your old page URLs with 307 or 308 redirects whenever you change the URL of a page or the architecture of your Site in a way that affects the URL structure. Redirecting old URLs will:

- Preserve your SEO scores if you want to rank highly in search engine results.
- Maintain external links to your website.
- Prevent visitors from seeing incorrect or missing content when they attempt to load any of your old URLs.

We also recommend [configuring a 404 page](/documentation/developer-articles/configure-a-404-page/) and routing all unrecognized subpaths to that page.

> CloudCannon reads your routes in order, and will use the earliest matching rule for a given `from` URL. Duplicate rules are ignored.

> You can redirect to, but not from a URL fragment (e.g. example.com/blog/#heading). The URL fragment is not passed to the server so, it cannot be processed by the redirect.

> You can use routing to load a single HTML file on multiple URL routes and use JavaScript to load different content (e.g., as a single-page app, or SPA).

You must configure three keys for a custom redirect: the `from` URL, the `to` URL, and the `status` code.

- **From** — Specifies which URL should trigger this redirect rule.
- **To** — Specifies which URL the visitor should be redirected or proxied to.
- **Status** — Tells the visitor's browser the reason for the route using an [HTTP status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes).

To add custom routes to your `routing.json` file:

1. Navigate to the `.cloudcannon` folder in your *File browser* and click on the `routing.json` file. CloudCannon will open `routing.json` in the Source Editor.
2. Create a JSON array under the `routes` key. Each entry in the array could include the keys `from`, `to`, and `status`.
3. When you are happy with your routing file, save your changes.

After a successful build, CloudCannon will route visitors according to the rules in your `routing.json` file.

Here are a few examples:

File: `.cloudcannon/routing.json`

```json

{
  "routes": [
    {
      "from": "/cloudcannon/(.*)",
      "to": "https://cloudcannon.com/$1",
      "status": 302
    },
    {
      "from": "/documentation/developer-articles/choosing-your-ssg/",
      "to": "/documentation/developer-articles/select-your-ssg/",
      "status": 301
    },
    {
      "from": "/app/(.*)",
      "to": "/app/",
      "status": 200
    }
  ]
}

```

For more a complete list of configuration keys available for custom routing, please read our [routing reference documentation](/documentation/developer-reference/routing-file/).

### Generating redirects

If your Site requires it, you can generate your routing file at build time.

For example, if you only want to redirect URLs on your production Site, you could add the following Liquid templating:

File: `routing.json`

```JSON

{
  routes: [
    {% if environment == 'production' %}
      {from: '/example-1',
      to: '/example-2'}
    {% endif %}
  ]
}

```

You can create a build process to generate your routing file with the correct content, depending on the environment. In this case, the build process should generate the file to `_cloudcannon/routing.json` in your site output directory. CloudCannon will use this file instead of  `.cloudcannon/routing.json` from your source.

For more information, please contact our friendly [support team](/support/).

## Custom Headers

Custom HTTP headers allow you to pass more information between your web server and the visitor's browser every time someone loads a web page. Custom headers are often used to change some website behavior, meet security requirements, or allow other origins to load resources.

In CloudCannon, you can configure headers using the `routing.json` file. Whenever a visitor loads a web page from your Site, all relevant header rules from your routing file are applied in order.

> CloudCannon supports a specific set of headers. For a complete list, please read our [routing](/documentation/developer-reference/routing-file/) reference documentation.

To add custom headers to your `routing.json` file:

1. Navigate to the `.cloudcannon` folder in your *File browser* and click on the `routing.json` file. CloudCannon will open `routing.json` in the Source Editor.
2. Create a JSON array under the `headers` key.
3. Within the `headers` key, add an object labeled `match` and a second `headers` array. The value of the `match` object should be a REGEX string of all URLs to which you want to add a header.
4. Within the second `headers` array, add an entry for each custom header. Each entry in the array should include the keys `name` and `value`.
5. When you are happy with your routing file, save your changes.

After a successful build, CloudCannon will load your custom headers whenever a page loads.

File: `.cloudcannon/routing.json`

```json

{
  "headers": [
    {
      "match": "*",
      "headers": [
        {
          "name": "Access-Control-Allow-Origin",
          "value": "https://example.com"
        },
        {
          "name": "X-Content-Type-Options",
          "value": "nosniff"
        },
        {
          "name": "X-Robots-Tag",
          "value": "noindex, nofollow"
        }
      ]
    }
  ]
}

```

For more a complete list of configuration keys available for custom routing, please read our [routing reference documentation](/documentation/developer-reference/routing-file/).


---

---
title: Configure extensionless URLs
description: Learn how to configure extensionless URLs for your Site hosted on CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/configure-extensionless-urls/
content_type: developer article
last_modified: 2026-03-29
---

> This feature is only available for Sites [hosted through CloudCannon](/documentation/user-articles/what-is-web-hosting/#hosting-on-cloud-cannon). If you host your Site externally, or use CloudCannon in [Headless Mode](/documentation/developer-articles/what-is-headless-mode/), this feature will not work.

Extensionless URLs do not end with a trailing `/` character or a file extension. For example, a URL with an extension might look like `https://example.com/about/` or `https://example.com/about.html`, whereas the extensionless URL would be `https://example.com/about`. In this example, all these URLs would serve the same content.

Extensionless URLs are optional. However, some web developers prefer extensionless URLs for several reasons:

- They have a cleaner appearance.
- Visitors must remember fewer characters when typing your URL into their Internet browser.
- You can change the underlying file format of the page without updating the URL, future-proofing your URLs.

On CloudCannon, you can elect to serve the same content on URLs with extensions and extensionless URLs. You can also redirect all URLs with extensions to their extensionless counterparts. This ensures each page only has a single URL rather than serving the same content on two different URLs.

> By default, CloudCannon serves all content on both URLs with extensions and extensionless URLs.

To serve files on extensionless URLs:

1. Navigate to the *Routing* page under *Site Settings*.
2. Tick the *Serve Extensionless URLs* checkbox.
3. (Optional.) If you want to redirect all URLs to their extensionless counterparts, tick the *Redirect to Extensionless URLs* checkbox.
4. Click the *Update routing details* button.

![A screenshot of the Routing Page under Site Settings shows the checkboxes for Serve Extensionless URLs and Redirect to Extensionless URLs.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Routing-Extensionless-URLs.webp)


---

---
title: Configure external DNS
description: Use your own DNS servers.
url: https://cloudcannon.com/documentation/developer-articles/configure-external-dns/
content_type: developer article
last_modified: 2026-03-29
---

External DNS allows you to host your Site on CloudCannon but manage your [DNS records](/documentation/developer-articles/what-is-dns/#what-are-dns-records) elsewhere. You can set up external DNS through a different provider (e.g., Cloudflare) or your own servers.

Before configuring your Site's DNS, you must [add a Custom Domain](/documentation/developer-articles/add-a-custom-domain-to-your-site/).

> If you are using Cloudflare as your DNS provider, you will need to configure your DNS records differently. For more information, please read the section on [configuring Cloudflare proxy](/documentation/developer-articles/configure-external-dns/#configure-cloudflare-proxy).

## Enable external DNS

By default, CloudCannon will enable CloudCannon DNS for your Site.

Edit the settings on the *Domain Settings* page to switch to external DNS for a site hosted on CloudCannon.

> Updating your DNS provider can cause downtime for anything connected to your domain, such as your website or custom email address. Please make sure you have a copy of your existing DNS records before you change providers.
> 
> If you need help updating your DNS, please contact our friendly [support team](/support/).

To switch to External DNS:

1. Navigate to the *Domain browser* by clicking the globe icon in your *App Navigation*.
2. Select the domain for which you want to configure DNS.
3. Under the *Domain Settings* tab, open the *DNS* section.
4. Select the *External DNS* option in the *DNS Provider* dropdown.
5. Click the *Update DNS Provider* button.

You can now manage your DNS records through an external provider.

![A screenshot of the Domain Settings page shows the DNS Provider dropdown is set to External DNS.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Domain-Settings-External-DNS.webp)

### Load balancing on external DNS

Load balancing is a method of distributing incoming traffic requests across multiple servers, providing redundancy in case one or more servers are offline. This reduces the potential downtime risk for your Site.

If you use an external DNS provider, CloudCannon will not be able to dynamically load balance incoming traffic to your Site. We recommend using CloudCannon DNS, particularly for Sites on your base domain, or investigating if your third-party DNS service provides load balancing.

### CloudCannon DNS records

When you enable external DNS for a Site hosted on CloudCannon, CloudCannon will ask you to add three DNS records to your DNS provider: two A Records and a CNAME Record.

The two A Records specify the IP addresses of the appropriate CloudCannon hosting servers for the your base domain. The CNAME Record will direct queries for any subdomains to CloudCannon's hosting servers.

> If you use a Cloudflare, setting up a CNAME Record for your base domain while using external DNS will result in a 1001 DNS Error.

## Configure Cloudflare Proxy

CloudCannon hosting uses Cloudflare. If you are using Cloudflare as your DNS provider and have Cloudflare's Proxy feature enabled for your DNS records, you will not be able to proxy directly to the normal CloudCannon CNAME (i.e., sites.cloudcannon.com).

To resolve this issue, you can either turn off Orange Cloud or set up Cloudflare Proxy with CloudCannon Origin and add a CNAME record to your DNS provider.

To set up Cloudflare Proxy with CloudCannon Origin:

1. Navigate to the *Custom Domain* page under *Site Settings*.
2. Under the *Setup* tab, select the *Cloudflare Proxy with CloudCannon Origin* option in the *Hosting Setup* dropdown.
3. Click the *Switch to Cloudflare Proxy with CloudCannon Origin* to confirm.

![A screenshot of the Custom Domain page shows the Cloudflare Proxy with CloudCannon Origin option in the Hosting Setup dropdown.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Custom-Domain-Orange-Cloud.webp)

To add a CNAME record:

1. Log in to Cloudflare and navigate to your DNS settings.
2. Add a CNAME record pointing to your Domain Name (e.g., example.com) at *orange-cloud.cloudcannon.com*.

> Your Site might be cached externally if you use Cloudflare Proxy. In this case, your Site won't show any updates until you manually clear your cache.

## Single Origin

> We do not recommend this option unless you have specific set up requirements. For assistance setting up your DNS, please contact our friendly [support team](/support/).

In some cases, you may need to configure your DNS records to point directly at CloudCannon's host origin rather than *sites.cloudcannon.com*. This bypasses the normal benefits of hosting on CloudCannon:

- The ability for CloudCannon to auto-generate a wildcard SSL certificate for your domain and its subdomains.
- Faster DNS lookup speed due to a globally distributed edge caching network.

Most commonly, you might use this setup if you need to point your base domain at CloudCannon while also using an external DNS.

To achieve this, you can set up Single Origin hosting and add DNS records to your DNS provider.

To set up Single Origin hosting:

1. Navigate to the *Custom Domain* page under *Site Settings*.
2. Under the *Setup* tab, select the *Single Origin* option in the *Hosting Setup* dropdown.
3. Click the *Switch to Single Origin* to confirm.

![A screenshot of the Custom Domain page shows the Single Origin option in the Hosting Setup dropdown.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Custom-Domain-Single-Origin.webp)

To add a DNS records:

1. Log in to your third-party DNS provider.
2. Add the CNAME record displayed on the *Setup* tab of the *Custom Domain* page. If your DNS provider does not allow CNAME records on a base domain, add the two A records instead.


---

---
title: Configure geolocation
description: Learn how to customize your web page content based on the location of the visitor.
url: https://cloudcannon.com/documentation/developer-articles/configure-geolocation/
content_type: developer article
last_modified: 2026-03-29
---

> This feature is only available for Sites [hosted through CloudCannon](/documentation/user-articles/what-is-web-hosting/#hosting-on-cloud-cannon). If you host your Site externally, or use CloudCannon in [Headless Mode](/documentation/developer-articles/what-is-headless-mode/), this feature will not work.

Geolocation allows you to serve different web page content to your visitors, depending on their location.

When you enable geolocation, CloudCannon will automatically inject the visitor's country code as a class for HTML elements as it serves your content. For example, if a visitor is from New Zealand, CloudCannon will inject the class `country-nz`:

File: `index.html`

```html

<html class="country-nz">

```

To enable geolocation:

1. Navigate to the *Routing* page under *Site Settings*.
2. Tick the *Enable geolocation* checkbox.
3. Click the *Update routing details* button.

![A screenshot of the Routing Page under Site Settings shows the checkbox labeled Enable Geolocation.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Routing-Geolocation.webp)

Once you have enabled geolocation, you can:

- Use CSS to show and hide elements depending on the country.
- Run custom JavaScript depending on the country.

File: `styles.css`

```css

.new-zealand-content {
  display: none;
}

.country-nz .new-zealand-content {
  display: block;
}

```

File: `script.js`

```javascript

var htmlElement = document.documentElement,
  countryClass = htmlElement.className.match(/\bcountry\-([a-z0-9]{2})\b/);

if (countryClass) {
  console.log(countryClass[1]); // logs your country code - check your console
} else {
  console.log("No country found :(");
}

```

CloudCannon supports the following country codes:

File: `countries.yml`

```yaml

- code: "a1"
  name: "Anonymous Proxy"
- code: "a2"
  name: "Satellite Provider"
- code: "o1"
  name: "Other Country"
- code: "ad"
  name: "Andorra"
- code: "ae"
  name: "United Arab Emirates"
- code: "af"
  name: "Afghanistan"
- code: "ag"
  name: "Antigua and Barbuda"
- code: "ai"
  name: "Anguilla"
- code: "al"
  name: "Albania"
- code: "am"
  name: "Armenia"
- code: "ao"
  name: "Angola"
- code: "ap"
  name: "Asia/Pacific Region"
- code: "aq"
  name: "Antarctica"
- code: "ar"
  name: "Argentina"
- code: "as"
  name: "American Samoa"
- code: "at"
  name: "Austria"
- code: "au"
  name: "Australia"
- code: "aw"
  name: "Aruba"
- code: "ax"
  name: "Aland Islands"
- code: "az"
  name: "Azerbaijan"
- code: "ba"
  name: "Bosnia and Herzegovina"
- code: "bb"
  name: "Barbados"
- code: "bd"
  name: "Bangladesh"
- code: "be"
  name: "Belgium"
- code: "bf"
  name: "Burkina Faso"
- code: "bg"
  name: "Bulgaria"
- code: "bh"
  name: "Bahrain"
- code: "bi"
  name: "Burundi"
- code: "bj"
  name: "Benin"
- code: "bl"
  name: "Saint Bartelemey"
- code: "bm"
  name: "Bermuda"
- code: "bn"
  name: "Brunei Darussalam"
- code: "bo"
  name: "Bolivia"
- code: "bq"
  name: "Bonaire, Saint Eustatius and Saba"
- code: "br"
  name: "Brazil"
- code: "bs"
  name: "Bahamas"
- code: "bt"
  name: "Bhutan"
- code: "bv"
  name: "Bouvet Island"
- code: "bw"
  name: "Botswana"
- code: "by"
  name: "Belarus"
- code: "bz"
  name: "Belize"
- code: "ca"
  name: "Canada"
- code: "cc"
  name: "Cocos (Keeling) Islands"
- code: "cd"
  name: "Congo, The Democratic Republic of the"
- code: "cf"
  name: "Central African Republic"
- code: "cg"
  name: "Congo"
- code: "ch"
  name: "Switzerland"
- code: "ci"
  name: "Cote d'Ivoire"
- code: "ck"
  name: "Cook Islands"
- code: "cl"
  name: "Chile"
- code: "cm"
  name: "Cameroon"
- code: "cn"
  name: "China"
- code: "co"
  name: "Colombia"
- code: "cr"
  name: "Costa Rica"
- code: "cu"
  name: "Cuba"
- code: "cv"
  name: "Cape Verde"
- code: "cw"
  name: "Curacao"
- code: "cx"
  name: "Christmas Island"
- code: "cy"
  name: "Cyprus"
- code: "cz"
  name: "Czech Republic"
- code: "de"
  name: "Germany"
- code: "dj"
  name: "Djibouti"
- code: "dk"
  name: "Denmark"
- code: "dm"
  name: "Dominica"
- code: "do"
  name: "Dominican Republic"
- code: "dz"
  name: "Algeria"
- code: "ec"
  name: "Ecuador"
- code: "ee"
  name: "Estonia"
- code: "eg"
  name: "Egypt"
- code: "eh"
  name: "Western Sahara"
- code: "er"
  name: "Eritrea"
- code: "es"
  name: "Spain"
- code: "et"
  name: "Ethiopia"
- code: "eu"
  name: "Europe"
- code: "fi"
  name: "Finland"
- code: "fj"
  name: "Fiji"
- code: "fk"
  name: "Falkland Islands (Malvinas)"
- code: "fm"
  name: "Micronesia, Federated States of"
- code: "fo"
  name: "Faroe Islands"
- code: "fr"
  name: "France"
- code: "ga"
  name: "Gabon"
- code: "gb"
  name: "United Kingdom"
- code: "gd"
  name: "Grenada"
- code: "ge"
  name: "Georgia"
- code: "gf"
  name: "French Guiana"
- code: "gg"
  name: "Guernsey"
- code: "gh"
  name: "Ghana"
- code: "gi"
  name: "Gibraltar"
- code: "gl"
  name: "Greenland"
- code: "gm"
  name: "Gambia"
- code: "gn"
  name: "Guinea"
- code: "gp"
  name: "Guadeloupe"
- code: "gq"
  name: "Equatorial Guinea"
- code: "gr"
  name: "Greece"
- code: "gs"
  name: "South Georgia and the South Sandwich Islands"
- code: "gt"
  name: "Guatemala"
- code: "gu"
  name: "Guam"
- code: "gw"
  name: "Guinea-Bissau"
- code: "gy"
  name: "Guyana"
- code: "hk"
  name: "Hong Kong"
- code: "hm"
  name: "Heard Island and McDonald Islands"
- code: "hn"
  name: "Honduras"
- code: "hr"
  name: "Croatia"
- code: "ht"
  name: "Haiti"
- code: "hu"
  name: "Hungary"
- code: "id"
  name: "Indonesia"
- code: "ie"
  name: "Ireland"
- code: "il"
  name: "Israel"
- code: "im"
  name: "Isle of Man"
- code: "in"
  name: "India"
- code: "io"
  name: "British Indian Ocean Territory"
- code: "iq"
  name: "Iraq"
- code: "ir"
  name: "Iran, Islamic Republic of"
- code: "is"
  name: "Iceland"
- code: "it"
  name: "Italy"
- code: "je"
  name: "Jersey"
- code: "jm"
  name: "Jamaica"
- code: "jo"
  name: "Jordan"
- code: "jp"
  name: "Japan"
- code: "ke"
  name: "Kenya"
- code: "kg"
  name: "Kyrgyzstan"
- code: "kh"
  name: "Cambodia"
- code: "ki"
  name: "Kiribati"
- code: "km"
  name: "Comoros"
- code: "kn"
  name: "Saint Kitts and Nevis"
- code: "kp"
  name: "Korea, Democratic People's Republic of"
- code: "kr"
  name: "Korea, Republic of"
- code: "kw"
  name: "Kuwait"
- code: "ky"
  name: "Cayman Islands"
- code: "kz"
  name: "Kazakhstan"
- code: "la"
  name: "Lao People's Democratic Republic"
- code: "lb"
  name: "Lebanon"
- code: "lc"
  name: "Saint Lucia"
- code: "li"
  name: "Liechtenstein"
- code: "lk"
  name: "Sri Lanka"
- code: "lr"
  name: "Liberia"
- code: "ls"
  name: "Lesotho"
- code: "lt"
  name: "Lithuania"
- code: "lu"
  name: "Luxembourg"
- code: "lv"
  name: "Latvia"
- code: "ly"
  name: "Libyan Arab Jamahiriya"
- code: "ma"
  name: "Morocco"
- code: "mc"
  name: "Monaco"
- code: "md"
  name: "Moldova, Republic of"
- code: "me"
  name: "Montenegro"
- code: "mf"
  name: "Saint Martin"
- code: "mg"
  name: "Madagascar"
- code: "mh"
  name: "Marshall Islands"
- code: "mk"
  name: "Macedonia"
- code: "ml"
  name: "Mali"
- code: "mm"
  name: "Myanmar"
- code: "mn"
  name: "Mongolia"
- code: "mo"
  name: "Macao"
- code: "mp"
  name: "Northern Mariana Islands"
- code: "mq"
  name: "Martinique"
- code: "mr"
  name: "Mauritania"
- code: "ms"
  name: "Montserrat"
- code: "mt"
  name: "Malta"
- code: "mu"
  name: "Mauritius"
- code: "mv"
  name: "Maldives"
- code: "mw"
  name: "Malawi"
- code: "mx"
  name: "Mexico"
- code: "my"
  name: "Malaysia"
- code: "mz"
  name: "Mozambique"
- code: "na"
  name: "Namibia"
- code: "nc"
  name: "New Caledonia"
- code: "ne"
  name: "Niger"
- code: "nf"
  name: "Norfolk Island"
- code: "ng"
  name: "Nigeria"
- code: "ni"
  name: "Nicaragua"
- code: "nl"
  name: "Netherlands"
- code: "no"
  name: "Norway"
- code: "np"
  name: "Nepal"
- code: "nr"
  name: "Nauru"
- code: "nu"
  name: "Niue"
- code: "nz"
  name: "New Zealand"
- code: "om"
  name: "Oman"
- code: "pa"
  name: "Panama"
- code: "pe"
  name: "Peru"
- code: "pf"
  name: "French Polynesia"
- code: "pg"
  name: "Papua New Guinea"
- code: "ph"
  name: "Philippines"
- code: "pk"
  name: "Pakistan"
- code: "pl"
  name: "Poland"
- code: "pm"
  name: "Saint Pierre and Miquelon"
- code: "pn"
  name: "Pitcairn"
- code: "pr"
  name: "Puerto Rico"
- code: "ps"
  name: "Palestinian Territory"
- code: "pt"
  name: "Portugal"
- code: "pw"
  name: "Palau"
- code: "py"
  name: "Paraguay"
- code: "qa"
  name: "Qatar"
- code: "re"
  name: "Reunion"
- code: "ro"
  name: "Romania"
- code: "rs"
  name: "Serbia"
- code: "ru"
  name: "Russian Federation"
- code: "rw"
  name: "Rwanda"
- code: "sa"
  name: "Saudi Arabia"
- code: "sb"
  name: "Solomon Islands"
- code: "sc"
  name: "Seychelles"
- code: "sd"
  name: "Sudan"
- code: "se"
  name: "Sweden"
- code: "sg"
  name: "Singapore"
- code: "sh"
  name: "Saint Helena"
- code: "si"
  name: "Slovenia"
- code: "sj"
  name: "Svalbard and Jan Mayen"
- code: "sk"
  name: "Slovakia"
- code: "sl"
  name: "Sierra Leone"
- code: "sm"
  name: "San Marino"
- code: "sn"
  name: "Senegal"
- code: "so"
  name: "Somalia"
- code: "sr"
  name: "Suriname"
- code: "ss"
  name: "South Sudan"
- code: "st"
  name: "Sao Tome and Principe"
- code: "sv"
  name: "El Salvador"
- code: "sx"
  name: "Sint Maarten"
- code: "sy"
  name: "Syrian Arab Republic"
- code: "sz"
  name: "Swaziland"
- code: "tc"
  name: "Turks and Caicos Islands"
- code: "td"
  name: "Chad"
- code: "tf"
  name: "French Southern Territories"
- code: "tg"
  name: "Togo"
- code: "th"
  name: "Thailand"
- code: "tj"
  name: "Tajikistan"
- code: "tk"
  name: "Tokelau"
- code: "tl"
  name: "Timor-Leste"
- code: "tm"
  name: "Turkmenistan"
- code: "tn"
  name: "Tunisia"
- code: "to"
  name: "Tonga"
- code: "tr"
  name: "Turkey"
- code: "tt"
  name: "Trinidad and Tobago"
- code: "tv"
  name: "Tuvalu"
- code: "tw"
  name: "Taiwan"
- code: "tz"
  name: "Tanzania, United Republic of"
- code: "ua"
  name: "Ukraine"
- code: "ug"
  name: "Uganda"
- code: "um"
  name: "United States Minor Outlying Islands"
- code: "us"
  name: "United States"
- code: "uy"
  name: "Uruguay"
- code: "uz"
  name: "Uzbekistan"
- code: "va"
  name: "Holy See (Vatican City State)"
- code: "vc"
  name: "Saint Vincent and the Grenadines"
- code: "ve"
  name: "Venezuela"
- code: "vg"
  name: "Virgin Islands, British"
- code: "vi"
  name: "Virgin Islands, U.S."
- code: "vn"
  name: "Vietnam"
- code: "vu"
  name: "Vanuatu"
- code: "wf"
  name: "Wallis and Futuna"
- code: "ws"
  name: "Samoa"
- code: "ye"
  name: "Yemen"
- code: "yt"
  name: "Mayotte"
- code: "za"
  name: "South Africa"
- code: "zm"
  name: "Zambia"
- code: "zw"
  name: "Zimbabwe"

```


---

---
title: Configure HTTP redirects
description: Learn how to redirect HTTP URLs to their more secure HTTPS counterparts.
url: https://cloudcannon.com/documentation/developer-articles/configure-http-redirects/
content_type: developer article
last_modified: 2026-03-29
---

> This feature is only available for Sites [hosted through CloudCannon](/documentation/user-articles/what-is-web-hosting/#hosting-on-cloud-cannon). If you host your Site externally, or use CloudCannon in [Headless Mode](/documentation/developer-articles/what-is-headless-mode/), this feature will not work.

Once you have your [SSL certificate](/documentation/developer-articles/what-is-an-ssl-certificate/) is enabled, users can visit your Site on the more secure [HTTPS](/documentation/developer-articles/what-is-an-ssl-certificate/#http-vs-https) URL. We highly recommend redirecting all your HTTP URLs to the more secure HTTPS URLs.

> You must have configured an SSL certificate before following these instructions.  For more information, please read our documentation on [adding an auto-generated SSL certificate](/documentation/developer-articles/add-an-auto-generated-ssl-certificate/) or [adding a custom SSL certificate](/documentation/developer-articles/add-a-custom-ssl-certificate/).

To redirect visitors to HTTPS:

1. Navigate to the *Routing* page under *Site Settings*.
2. Ensure the *Redirect all HTTP traffic to HTTPS* checkbox is ticked.
3. Click the *Update Routing Details* button.

CloudCannon will now reroute all visitors using the HTTP URL address to the correct HTTPS URL address.

![A screenshot of the Routing page shows the Redirect all HTTP traffic to HTTPS checkbox is ticked](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Routing-HTTPS-Redirect.webp)


---

---
title: Configure Image Editable Regions
description: Learn how to configure Image Editable Regions to enable image, title, and alt text editing in the Visual Editor.
url: https://cloudcannon.com/documentation/developer-articles/configure-image-editable-regions/
content_type: developer article
last_modified: 2026-03-29
---

> **Permissions required**
> 
> Members of the Owners, Developers, and Technical Editors [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `site:source-editor:write` permission, can add *Editable Regions* to files using the Source Editor in CloudCannon.

Image *Editable Regions* are one type of [Editable Region](/documentation/developer-articles/what-are-editable-regions/) you can add to your layout and HTML-like files to enable visual editing. Image *Editable Regions* allow you to upload images from your local storage, select existing images from your repository or DAM, and manage image details like title or alt text.

> To avoid misconfiguration issues where CloudCannon cannot find the data property you want to edit, always add *Editable Regions* to values closest to the root of the file first (i.e., work from parent elements towards child elements).

These instructions assume you have configured your [build settings](/documentation/developer-articles/configure-your-first-build/) and are comfortable editing HTML layouts, either in CloudCannon's [Source Editor](/documentation/user-articles/what-is-the-source-editor/) or your local development environment.

To configure Image *Editable Regions* in the [Visual Editor](/documentation/user-articles/what-is-the-visual-editor/):

1. Identify the file to which you want to add an Image *Editable Region*. We recommend any layout files that contain templating that is populated by content files at build time.
2. Open the file in CloudCannon's Source Editor or your local development environment.
3. Identify the `<img>` HTML tag that contains your templating and add the HTML attribute `data-editable="image"` . If no DOM element is available, you can wrap the templating in the `<editable-image>` web component.
4. Add the `data-prop-src=""` HTML attribute to the same DOM element, or to the `<editable-image>` web component. The value of `data-prop-src` should be the path the to data property you want to edit.
5. Optional. If you store image title or alt text data in your content files, add the `data-prop-title=""` and `data-prop-alt=""` HTML attributes to the same DOM element, or to the `<editable-image>` web component. The value of these attributes should be the path the to data property you want to edit.
6. Save the change to your *Site*. CloudCannon will automatically rebuild your *Site*.

When you open the file in the Visual Editor, CloudCannon will show yellow *Editable Region* boxes around the image. CloudCannon will show a data panel for selecting your image when you click into the *Editable Region*.

![A screenshot of the Visual Editor shows a yellow Editable Region box around the image and the Edit Image Data Panel.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Visual-Editor-Frontmatter-Image-Editable-Region.webp)

> **Want to make a standalone HTML-like file visually editable?**
> 
> We recommend configuring [Source Editable Regions](/documentation/developer-articles/configure-source-editable-regions/) for standalone HTML-like files (i.e., files that contain HTML structure and templating, like `.astro` or `.liquid`) rather than several Image and Text *Editable Regions*.

## Examples

Here are a few examples of different Image *Editable Regions*:

File: `BlogPost.astro`

```Astro
```

<div class="hero-image">
    {heroImage &&
      <img
        data-editable="image" /*1*/
        data-prop-src="heroImage" /*2*/
        data-prop-alt="heroImageAlt" /*3*/
        data-prop-title="heroImageTitle" /*4*/
        width={1020}
        height={510}
        src={heroImage}
        title={heroImageTitle}
        alt={heroImageAlt}
      />
    }
</div>

```

**[1]** The `data-editable` attribute defines what kind of data this element contains. In this case, the value is `image`.

**[2]** The `data-prop-src` attribute passes the value of `heroImage` to the Image Editable Region with the `src` key.

**[3]** The `data-prop-title` attribute passes the value of `heroImageTitle` to the Image Editable Region with the `title` key.

**[4]** The `data-prop-alt` attribute passes the value of `heroImageAlt` to the Image Editable Region with the `alt` key.
```

## Expected data property format

Image *Editable Regions* expect the data defined by `data-prop` to be in the `key: string` format. By using the `data-prop-*` attribute, we can append a key to the value passed to the Image *Editable Region*.

For example, `data-prop="theme_color"` pointing at the front matter object `theme_color: red` would pass the value "red" to the *Editable Region* in the Visual Editor. If we use `data-prop-color="theme_color"` instead, we can pass "color: red" to the *Editable Region*.

## Misconfigured Image *Editable Regions*

CloudCannon will display an orange warning box in the Visual Editor if your Image *Editable Regions* is misconfigured.

Image *Editable Regions* are misconfigured if:

- You did not define the `data-prop` HTML attribute.
- The *Editable Region* has an invalid data type (e.g., your Text region has a number or object, instead of a string).
- There is no `<img>` child element in the Image *Editable Region* web component.
- Upload failures


---

---
title: Configure Source Editable Regions
description: Learn how to configure Source Editable Regions in standalone HTML-like files to enable rich text editing in the Visual Editor.
url: https://cloudcannon.com/documentation/developer-articles/configure-source-editable-regions/
content_type: developer article
last_modified: 2026-03-29
---

> **Permissions required**
> 
> Members of the Owners, Developers, and Technical Editors [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `site:source-editor:write` permission, can add *Editable Regions* to files using the Source Editor in CloudCannon.

Source *Editable Regions* are one type of [Editable Region](/documentation/developer-articles/what-are-editable-regions/) you can add to your layout and HTML-like files to enable visual editing. Source *Editable Regions* allow you to edit rich text stored in HTML.

> To avoid misconfiguration issues where CloudCannon cannot find the data property you want to edit, always add *Editable Regions* to values closest to the root of the file first (i.e., work from parent elements towards child elements).

These instructions assume you have configured your [build settings](/documentation/developer-articles/configure-your-first-build/) and are comfortable editing HTML layouts, either in CloudCannon's [Source Editor](/documentation/user-articles/what-is-the-source-editor/) or your local development environment.

To configure Source *Editable Regions* in the [Visual Editor](/documentation/user-articles/what-is-the-visual-editor/):

1. Identify the file to which you want to add a Source *Editable Regions*. We recommend any HTML files that contain templating that is populated by content files at build time.
2. Open the file in CloudCannon's Source Editor or your local development environment.
3. Identify the HTML tag that contains your templating and add the HTML attribute `data-editable="source"` . If no DOM element is available, you can wrap the templating in the `<editable-source>` web component.
4. Add the `data-path=""` HTML attribute to the same DOM element, or to the `<editable-source>` web component. The value of `data-path` should be the path the to file you want to edit.
5. Add the `data-key=""` HTML attribute to the same DOM element, or to the `<editable-source>` web component. The value of `data-key` should be a unique identifier for that section of your file (e.g., main, header, article).
6. Save the change to your *Site*. CloudCannon will automatically rebuild your *Site*.

When you open the file in the Visual Editor, CloudCannon will show a yellow *Editable Region* box. CloudCannon will also show a WYSIWYG toolbar for formatting your content when you click into text inside the *Editable Region* and a Snippet for all images inside the region.

![A screenshot of the Visual Editor shows yellow Editable Region boxes around the rich text content on the Home webpage.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Visual-Editor-Source-Editable-Region.webp)

> Do not nest Text or Image *Editable Regions* inside Source *Editable Regions*.

## Examples

Here are a few examples of different Text *Editable Regions*:

File: `index.astro`

```Astro
```

<!doctype html>
<html lang="en">
	<body>
        <main data-editable="source" data-path="/src/pages/index.astro" data-key="main"> /*1*/
            <img src="/smiling-robot.jpg">
			<h1>Hello!</h1>
			<p>
                Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
                labore et dolore magna aliqua. Vitae ultricies leo integer malesuada nunc vel risus commodo
                viverra. Adipiscing enim eu turpis egestas pretium.
			</p>
			<p>Varius sit amet mattis vulputate enim. Habitasse platea dictumst:</p>
			<ul>
				<li>Morbi tristique senectus et netus.</li>
				<li>Id semper risus in hendrerit gravida rutrum quisque non tellus.</li>
			</ul>
		</main>
	</body>
</html>

```

**[1]** The `data-editable` attribute defines what kind of data this element contains, the `data-path` attribute defines the path to the file we want to edit, and the `data-key` attribute defines the unique identifier for this region if there are multiple regions in the file. In this case, we want a Source *Editable Region*, so the value of `data-editable` is `source`, we want to edit the `/src/pages/index.astro` file, and the unique key is `main`.
```

## Misconfigured Source *Editable Regions*

CloudCannon will display an orange warning box in the Visual Editor if your Source *Editable Regions* is misconfigured.

Source *Editable Regions* are misconfigured if:

- You did not define the `data-path` HTML attribute.
- You did not define the `data-key` HTML attribute.
- The file path defined by `data-path` does not exist.
- There are *Editable Regions* with the same `data-key` value. This value should be unique.


---

---
title: Configure Text Editable Regions
description: Learn how to configure Text Editable Regions in your layout files to enable plain and rich text editing in the Visual Editor.
url: https://cloudcannon.com/documentation/developer-articles/configure-text-editable-regions/
content_type: developer article
last_modified: 2026-04-11
---

> **Permissions required**
> 
> Members of the Owners, Developers, and Technical Editors [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `site:source-editor:write` permission, can add *Editable Regions* to files using the Source Editor in CloudCannon.

Text *Editable Regions* are one type of [Editable Region](/documentation/developer-articles/what-are-editable-regions/) you can add to your layout and HTML-like files to enable visual editing. Text *Editable Regions* allow you to edit text values stored in front matter, content, or HTML with plain text or rich text formatting options.

> To avoid misconfiguration issues where CloudCannon cannot find the data property you want to edit, always add *Editable Regions* to values closest to the root of the file first (i.e., work from parent elements towards child elements).

These instructions assume you have configured your [build settings](/documentation/developer-articles/configure-your-first-build/) and are comfortable editing HTML layouts, either in CloudCannon's [Source Editor](/documentation/user-articles/what-is-the-source-editor/) or your local development environment.

To configure Text *Editable Regions* in the [Visual Editor](/documentation/user-articles/what-is-the-visual-editor/):

1. Identify the file to which you want to add a Text *Editable Regions*. We recommend any layout files that contain templating that is populated by content files at build time.
2. Open the file in CloudCannon's Source Editor or your local development environment.
3. Identify the HTML tag that contains your templating and add the HTML attribute `data-editable="text"` . If no DOM element is available, you can wrap the templating in the `<editable-text>` web component.
4. Add the `data-prop=""` HTML attribute to the same DOM element, or to the `<editable-text>` web component. The value of `data-prop` should be the path the to data property you want to edit.
5. Save the change to your *Site*. CloudCannon will automatically rebuild your *Site*.

When you open the file in the Visual Editor, CloudCannon will show yellow *Editable Region* boxes around the text field. If your text field contains rich text, CloudCannon will show a WYSIWYG toolbar for formatting your content when you click into the *Editable Region*.

![A screenshot of the Visual Editor shows a yellow Editable Regions box around the blog content and a WYSIWYG toolbar.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Visual-Editor-Content-Text-Editable-Region.webp)

> **Want to make a standalone HTML-like file visually editable?**
> 
> We recommend configuring [Source Editable Regions](/documentation/developer-articles/configure-source-editable-regions/) to HTML-like files (i.e., files that contain HTML structure and templating, like `.astro` or `.liquid`) rather than several Text and Image *Editable Regions*.

## Examples

Here are a few examples of different Text *Editable Regions*:

File: `BlogPost.astro`

```Astro
```

<h1 data-editable="text" data-prop="title" >{title}</h1> /*1*/

```

**[1]** The `data-editable` attribute defines what kind of data this element contains, and the `data-prop` attribute defines the path to the data we want to edit. In this case, we want a Text *Editable Region*, so the value of `data-editable` is `text`, and we want to edit the `title` structured data key in the file front matter.
```

File: `BlogPost.astro`

```Astro
```

<p>By: <editable-text data-prop="author">{author}</ editable-text></p> /*1*/

```

**[1]** The `<editable-text>` web component defines what kind of data this element contains, and the `data-prop` attribute defines the path to the data we want to edit. In this case, we used the web component to wrap the `{author}` templating specifically, and we want to edit the `author` structured data key in the file front matter.
```

File: `BlogPost.astro`

```Astro
```

<text-editable data-prop="@content"> /*1*/
    <slot />
</text-editable>

```

**[1]** The `<editable-text>` web component defines what kind of data this element contains, and the `data-prop` attribute defines the path to the data we want to edit. In this case, we used the web component to wrap the `<slot />` element, which will be populated by Markdown content at build time, and we want to edit the Markdown content of the file, as signified by the special value `@content`.
```

## WYSIWYG toolbar formatting options

Depending on whether your *Editable Region* contains plain text or rich text, CloudCannon may show you a WYSIWYG toolbar with different formatting options. These options are controlled by the `data-type` HTML attribute. You can manually define this attribute, or rely of CloudCannon's default behavior.

The `data-type` attribute accepts three values: `span` for plain text, `text` for paragraph-level rich text formatting options (e.g., bold, links, superscript), or `block` for multi-paragraph rich text formatting (e.g., bulleted lists, quote blocks).

When `data-type` is not defined, CloudCannon uses `block` or `text` for any Source *Editable Regions*, `data-prop="@content"`, or Rich Text Inputs, and `span` where Input type is not Rich Text, or is not configured.

![An illustration of the flowchart CloudCannon uses to decide if rich text formatting is appropriate for an element.](assets/diagrams/CloudCannon-Documentation-Editables-Data-Type-Flowchart.png)

> If you want to specify exactly which formatting tools are available, you can manually define your WYSIWYG toolbar under the `_editables` key in your CloudCannon Configuration File. For more information, please read our documentation on [Configuring your rich text editors](/documentation/developer-articles/configure-your-rich-text-editors/#editable-regions).

## Misconfigured Text *Editable Regions*

CloudCannon will display an orange warning box in the Visual Editor if your Text *Editable Regions* is misconfigured.

Text *Editable Regions* are misconfigured if:

- You did not define the `data-prop` HTML attribute.
- The *Editable Region* has an invalid data type (e.g., your Text region has a number or object, instead of a string).
- You have an unsupported value for `data-type`. It must be `span`, `text`, or `block`.


---

---
title: Configure the Add button in collections
description: Learn how to create or change actions for the add menu in the collection file list.
url: https://cloudcannon.com/documentation/developer-articles/configure-the-add-button-in-collections/
content_type: developer article
last_modified: 2026-03-29
---

CloudCannon provides a good default set of actions in the *+Add menu* in the collection file list. These actions are generated from [schemas](/documentation/developer-articles/what-is-a-schema/) configured for that collection. If there are no schemas, actions are generated based on the first file in that collection.

You can override these default actions with the `add_options` option when [configuring your collections](/documentation/developer-articles/configure-your-collections/).

> You can make actions for the current collection, other collections, and external links.

### Examples

Some example configurations are shown below:

File: `cloudcannon.config.yml`

```YAML
collections_config:
  posts:
    add_options:
      - name: Add Post
        editor: content
      - name: Add Draft
        editor: content
        collection: drafts
        schema: default
```

File: `cloudcannon.config.yml`

```YAML
collections_config:
  pages:
    add_options:
      - name: New page
      - name: New contact page
        default_content_file: content/pages/contact.html
  people:
    add_options:
      - name: Add Staff Member
        schema: staff
      - name: Add Author
        icon: edit
        schema: author
        base_path: authors
    schemas:
      staff:
        path: schemas/staff.json
      author:
        path: schemas/author.json
  offices:
    add_options:
      - name: Add Office
        editor: data
      - name: Add Office Location
        icon: public
        href: "edit?editor=data&path=_data/office-locations.yml"
      - name: Open external link
        icon: search
        href: "https://www.example.com/"
```

For the `offices` collection, this will result in the following menu:

![A closeup of the Offices collection Add dropdown shows options for Add Office, Add Office Location, and Open external link.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Add-Options-Offices.webp)

### Options

Each `add_options` entry has the following options:

**`name`** String

The text displayed for the menu item. Defaults to using `name` from the matching `schema` if set.

**`icon`** String

The icon next to the text in the menu item. Must match a [Material Icon](https://material.io/tools/icons/) name. Defaults to using `icon` from the matching `schema` if set, then falls back to `add`.

**`href`** String

The link that opens when the option is clicked. Can either be an external or internal link. If internal, the link is relative to the current site.

If this is set, the `collection`, `editor`, `base_path` and `schema` options are ignored. Since this acts as an override, we recommend using those options directly in favor of this if possible.

**`editor`** String

The editor to open the new file in. Must be one of `content`, `data`, or `visual`. Defaults to an appropriate editor for new file's type if possible. If no default editor can be calculated, or the editor does not support the new file type, a warning is shown in place of the editor.

**`base_path`** String

Enforces a path for new files to be created in, regardless of path the user is currently navigated to within the collection file list. Relative to the `path` of the collection defined in `collection`. Defaults to the path within the collection the user is currently navigated to.

**`collection`** String

Sets which [collection](/documentation/user-articles/what-is-a-collection/) this action is creating a file in. This is used when matching the value for `schema`. Defaults to the containing collection these `add_options` are configured in.

**`schema`** String

The [schema](/documentation/developer-articles/what-is-a-schema/) that new files are created from with this action. This schema is not restricted to the containing collection, and is instead relative to the collection specified with `collection`. Defaults to `default` if schemas are configured for the collection.

Although useful, it's not required to configure schemas for the initial contents of new files.

**`default_content_file`** String

The path to a file used to populate the initial contents of a new file if no schemas are configured. We recommend using schemas, and this is ignored if a `schema` is available.


---

---
title: Configure the Client Dashboard support links
description: Learn how to configure the support links on the Client Dashboard.
url: https://cloudcannon.com/documentation/developer-articles/configure-the-client-dashboard-support-links/
content_type: developer article
last_modified: 2026-03-29
---

You can configure three links for the Client Dashboard to help Clients find the necessary resources for your Site.

- **Preview URL** — Links to the preview of your live Site (e.g., the custom domain or [.cloudvent.net testing domain](/documentation/user-articles/what-is-a-testing-domain/)).
- **Documentation URL** — Links to the location where Clients can find documentation for your Site.
- **Support URL** — Links to the location where Clients can find support (e.g., a mailto with your support email address).

These links will appear in the *Site Navigation* and on the *Site Dashboard.*

![A screenshot of the Settings tab on the Client Sharing page shows the three fields for Preview URL, Documentation URL, and Support URL.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Client-Sharing-Settings-Tab.webp)

To configure the links on the Client Dashboard:

1. Navigate to the *Client Sharing* page under *Site settings*.
2. Click on the *Settings* tab.
3. Enter the preview link in the *Preview URL* field.
4. Enter the documentation link in the *Documentation URL* field.
5. Enter the support link in the *Support URL* field.
6. Click the *Update* button at the bottom of the page.

CloudCannon will update the links on the Client Dashboard. Clients must refresh their page to see the updated links.


---

---
title: Configure the Client Login Page
description: Learn how to configure the settings for your Site's Client Login Page.
url: https://cloudcannon.com/documentation/developer-articles/configure-the-client-login-page/
content_type: developer article
last_modified: 2026-03-29
---

You can change the URL subpath for the Client Login Page. You may need to do this if you already have a page at the subpath “/update”.

To change the URL subpath for the Client Login Page:

1. Navigate to the *Client Sharing* page under *Site settings*.
2. Click on the *Settings* tab.
3. Enter the new subpath for the Client Login Page in the URL subpath field.
4. Click the *Update* button at the bottom of the page.

![A screenshot of the Settings tab on the Client Sharing pages shows a field to update the URL subpath of your Client Login page and a checkbox to prevent browsers asking to save Client passwords.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Client-Sharing-Settings-Tab.webp)

You can also prevent the Client’s browser from asking to save the Client Sharing password by ticking the checkbox for *Prevent password save prompt* at the bottom of the *Settings* tab.


---

---
title: Configure the commit details for Clients
description: Learn how to configure the commit details for a Client.
url: https://cloudcannon.com/documentation/developer-articles/configure-the-commit-details-for-clients/
content_type: developer article
last_modified: 2026-03-29
---

By default, when a Client edits your Site, the commit details will contain the name “CloudCannon” and email address “support@cloudcannon.com”.

You can configure the commit details for Clients to create a more accurate history of changes made to your Site.

To configure the commit details for a Client:

1. Navigate to the *Client Sharing* page under *Site settings*.
2. Click on the *Author* tab.
3. Under the *Author* tab, enter the name and email address you want to appear in the commit history.
4. Click the *Update* button.

![A screenshot of the Author tab on the Client Sharing page shows two fields for the name and email address applied to commits made by Clients.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Client-Sharing-Author-Tab.webp)


---

---
title: Configure your card previews
description: CloudCannon uses configurable cards to represent your data in different places across the app
url: https://cloudcannon.com/documentation/developer-articles/configure-your-card-previews/
content_type: developer article
last_modified: 2026-04-11
---

## What are cards?

CloudCannon uses cards to represent your data. A card is a configurable UI element that gives you a preview of that data. Depending on the type of data stored, this could include an image, title, subtitle, icon, and metadata.

![The anatomy of a card preview](assets/diagrams/preview-options.svg)

Cards appear in different places across the app, including:

1. Snippets
  
  - [Hugo Shortcodes](/documentation/developer-articles/snippets-using-hugo-shortcodes/)
  - [Eleventy Shortcodes](/documentation/developer-articles/snippets-using-eleventy-shortcodes/)
2. Snippet Picker
3. [Structures](/documentation/developer-articles/what-is-a-structure/)
4. [Structure Picker](/documentation/developer-articles/create-a-structure/)
5. [Select-style inputs](/documentation/user-articles/what-is-a-select-input/)
6. [Object inputs](/documentation/user-articles/what-is-an-object-input/)
7. [Collection](/documentation/user-articles/what-is-a-collection/) file lists

These cards are configurable using the `preview` key.

> Select-style inputs, Object inputs and Structure and non-structure inputs inside Array inputs support a subset of these options. The specifics are documented on each page.

## Configure your card previews

The `preview` configuration has a number of different keys which correspond to different parts of the card display.

### Preview reference

**`text`** Array, or String

The highest level of text shown in the preview.

**`subtext`** Array, or String

The second highest level of text which is displayed over at most two lines.

**`_inputs.*.options.preview.icon`** Array, string or boolean

This key determines the icon displaye beside the text and subtext on a Card. The value must match a name from the [Google's Material Icons](https://fonts.google.com/icons) list.

This key defaults to checking the `icon` key, then falls back to the `notes` icon.

If set to `false`, no icon is displayed.

If `image` is defined, the image replaces `icon` when loaded successfully.

This key supports cascading options, which can be either an Array or a single value. Value can be one of the following:

- A String of the exact value (e.g `"edit_note"`)
- A reference to a key within the connected item (e.g `key: icon` in YAML or `{ "key": "icon" }` in JSON)
- A String with placeholders that will be replaced with values (e.g. `template: {icon_type}` in YAML or `{ "template": "{icon_type}" }` in JSON)

In this example, we configure a static icon for the card.

File: `cloudcannon.config.yml`

```YAML
preview:
  icon: edit_note
```

In this example, we use a dynamic icon from the data.

File: `cloudcannon.config.yml`

```YAML
preview:
  icon:
    - key: icon_type
    - support_agent
```

**`_inputs.*.options.preview.icon_color`** Array, string or boolean

This key determines the color of the icon displayed on a Card.

This key supports cascading options, which can be either an Array or a single value. Value can be one of the following:

- A String of the exact value (e.g `"#ff0000"`)
- A reference to a key within the connected item (e.g `key: color` in YAML or `{ "key": "color" }` in JSON)
- A String with placeholders that will be replaced with values (e.g. `template: {color_code}` in YAML or `{ "template": "{color_code}" }` in JSON)

By default, this key is `#000000` (black).

In this example, we configure a dynamic icon color from the data with a fallback to red.

File: `cloudcannon.config.yml`

```YAML
preview:
  icon: edit_note
  icon_color:
    - key: color
    - '#ff0000'
```

In this example, we use a static icon color.

File: `cloudcannon.config.yml`

```YAML
preview:
  icon: nature_people
  icon_color:
    - '#00ff00'
```

**`_inputs.*.options.preview.icon_background_color`** Array, string or boolean

This key determines the background color of the icon displayed on a Card. This is useful if your `icon_color` value has poor contrast on a white background.

This key supports cascading options, which can be either an Array or a single value.Value can be one of the following:

- A String of the exact value (e.g `"#ff0000"`)
- A reference to a key within the connected item (e.g `key: color` in YAML or `{ "key": "color" }` in JSON)
- A String with placeholders that will be replaced with values (e.g. `template: {color_code}` in YAML or `{ "template": "{color_code}" }` in JSON)

This key has no default.

In this example, we configure a dynamic icon background color from the data with a fallback to red.

File: `cloudcannon.config.yml`

```YAML
preview:
  icon: edit_note
  icon_background_color:
    - key: color
    - '#ff0000'
```

In this example, we use a static icon background color.

File: `cloudcannon.config.yml`

```YAML
preview:
  icon: nature_people
  icon_background_color:
    - '#00ff00'
```

**`image`** Array, or String

Defines an image to display beside the text and subtext on the card. Once the image loads it will cover the icon.

**`metadata`** Array

A list of items that can contain an image, icon and text. Great for related data. See metadata reference below.

**`gallery`** Object

Defines large image/icon preview for the card. See gallery metadata below.

### metadata reference

Metadata is a great way to show related data in the card.

![The layout of a cards metadata](assets/diagrams/metadata.svg)

**`text`** Array, or String

The text to be displayed on the metadata item.

**`icon`** Array, String, or Boolean

Defines an icon from [Google’s Material Icons](https://material.io/tools/icons/) beside the text on the metadata. Must match [Material Icon](https://material.io/tools/icons/) name.

**`icon_color`** Array, or String

This key determines the color of the icon displayed on a Card.

This key supports cascading options, which can be either an Array or a single value. Value can be one of the following:

- A String of the exact value (e.g `"#ff0000"`)
- A reference to a key within the connected item (e.g `key: color` in YAML or `{ "key": "color" }` in JSON)
- A String with placeholders that will be replaced with values (e.g. `template: {color_code}` in YAML or `{ "template": "{color_code}" }` in JSON)

By default, this key is `#000000` (black).

In this example, we configure a dynamic icon color from the data with a fallback to red.

File: `cloudcannon.config.yml`

```YAML
preview:
  icon: edit_note
  icon_color:
    - key: color
    - '#ff0000'
```

In this example, we use a static icon color.

File: `cloudcannon.config.yml`

```YAML
preview:
  icon: nature_people
  icon_color:
    - '#00ff00'
```

**`image`** Array, or String

Defines an image path to load over the icon.

### gallery reference

The gallery will render an icon if it is defined, an image over the icon once loaded and if neither exist the text will be displayed.

![Different states of the gallery option](assets/diagrams/gallery-load-order.svg)

**`text`** Array, or String

Defines text to display in the centre of the gallery area if there is no icon or image.

**`icon`** Array, String, or Boolean

Defines an icon from [Google’s Material Icons](https://material.io/tools/icons/) to display in the centre of the gallery area. match [Material Icon](https://material.io/tools/icons/) name.

**`icon_color`** Array, or String

This key determines the color of the icon displayed on a Card.

This key supports cascading options, which can be either an Array or a single value. Value can be one of the following:

- A String of the exact value (e.g `"#ff0000"`)
- A reference to a key within the connected item (e.g `key: color` in YAML or `{ "key": "color" }` in JSON)
- A String with placeholders that will be replaced with values (e.g. `template: {color_code}` in YAML or `{ "template": "{color_code}" }` in JSON)

By default, this key is `#000000` (black).

In this example, we configure a dynamic icon color from the data with a fallback to red.

File: `cloudcannon.config.yml`

```YAML
preview:
  icon: edit_note
  icon_color:
    - key: color
    - '#ff0000'
```

In this example, we use a static icon color.

File: `cloudcannon.config.yml`

```YAML
preview:
  icon: nature_people
  icon_color:
    - '#00ff00'
```

**`image`** Array, or String

Defines an image to display in the gallery area. Covers text and icon once the image is loaded.

**`fit`** String

Sets how image is displayed in the gallery. Must be `cover` (default) or `contain`.

## How cascading options work

Most of the keys within `preview` are the same type of structure, which we call cascading options. This is either an Array or a single value of the following types:

- A String of the exact value (e.g `"My Item"`)
- A reference to a key within the connected item (e.g `key: title` in YAML or `{ "key": "title" }` in JSON)
- A String with placeholders that will be replaced with values (e.g. `template: {date|date_long}` in YAML or `{ "template": "{date|date_long}" }` in JSON)

```yaml
# String option
preview_option: Fallback String

# or, Array cascading option
preview_option:
- key: some_key
- key: object.subkey
- template: '{date|date_long}'
- Fallback String
```

When using an Array each item is read in order. If no content is found, the next item in the array is used. If no content is valid, the corresponding `preview` option will be hidden.

Below is an example of some data representing a Figure that needs previewed:

```yaml
_type: figure
image_path: /image.png
alt_text: An image

```

When displaying this Figure we want to:

1. Always display the `image` icon (A String example)
2. In the text, display the `image_path` key falling back to the String ‘Image missing’ (An Array example)
3. In the subtext, display the `alt_text` key falling back to the String ‘No alternative text’ (Another Array example)

Writing this as a set of `preview` options will look like this:

```yaml
preview:
  icon: image
  text:
    - key: image_path
    - Image missing
  subtext:
    - key: alt_text
    - No alternative text
```

### Template strings in previews

You can use [template strings](/documentation/developer-articles/configure-your-template-strings/) in your card previews. Template strings are a mixture of literal text and dynamic placeholders that are replaced with data. You can use template strings to populate your card previews with more complex strings.

The `template` key can reference keys from within the object you want to preview.

> When using a template string, all placeholders within the string must resolve to an output. If any placeholder resolves to an empty result, CloudCannon cannot display that template string. In this case, CloudCannon will use the next item in the array.

Let's walk through an example. We want to add the author of a file to the card metadata field. We want the metadata field to have a person icon and the text "By [author name]". If no author name is available, the text should read "No author".

To achieve this, we will create an array of `metadata.text` options. The first array item is our template string, with the value of `template` set to `By {author.name}`. The second array item is the string `No author`.

File: `cloudcannon.config.yml`

```YAML
collections_config:
  posts:
    preview:
      metadata:
        - text:
            - template: 'By {author.name}'
            - No author
          icon: person
```

In the above example, if the `author.name` key in our object is set to "Heather", the card preview will display "By Heather" in the metadata field.

For more information, including a list of all available placeholder values, read our documentation on [template strings](/documentation/developer-articles/configure-your-template-strings/).

## Picker specific options

There are two states where cards can be displayed:

1. A card connected to an existing item with it’s own data (e.g an instance of a snippet or structure on a page)
2. A card used in a “picker” where the type of item needs to be selected (e.g. adding a snippet or structure)

When a card is used in a “picker”, it is useful to override the options from the `preview` config. For this we use the `picker_preview` config which merges on top of the `preview` options. The options within `picker_preview` are the same as the options in `preview`.

For the same figure example we used above we want to:

1. Show the String ‘Figure’ for the `text`
2. Disable the `subtext` to prevent showing the String ‘No alternative text’

```yaml
figure:
  picker_preview:
    text: Figure # Used in a picker
    subtext: false # Disables the subtext in the picker
  preview: # Used in each figure item
    icon: image
    text:
      - key: image_path
      - Image missing
    subtext:
      - key: alt_text
      - No alternative text
```


---

---
title: Configure your collections
description: Learn how to configure your Collections in CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/configure-your-collections/
content_type: developer article
last_modified: 2026-04-11
---

> 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](https://non-unified.cloudcannon.com/documentation/developer-articles/define-your-collections/).

After syncing your Site files, configuring your Collections is one of the first steps in creating your CloudCannon configuration file. During your initial Site setup, CloudCannon only requires minimal Collection configuration: a name and path for each Collection.

You can configure your Collections at any time to customize the experience for your team members.

To configure your Collections:

1. Navigate to the *Editing* page, under *Site Settings*, and click the *Edit your configuration file* button to open your [CloudCannon configuration file](/documentation/developer-articles/what-is-the-cloudcannon-configuration-file/) in the Data Editor.
2. Identify the *Collections* array under the *Collections and paths* section.
3. Click on an existing Collection in the array or click the *+ Add Collection* button to add a new Collection.
4. Edit your Collection configuration. The CloudCannon configuration file is organized into four sections for each Collection: *Collection setup*, *Collection display*, *Collection editing interfaces*, and *Creating and updating pages*. You can click on any section to open editing interfaces for each Collection configuration key.
5. Once you are happy with your configuration, [save your changes](/documentation/user-articles/save-your-changes/) by clicking the *Save* button in the top right of your editing interface.

CloudCannon will commit your Collection configuration to your Git repository.

If you would prefer to, you can configure your Collections in the [Source Editor](/documentation/user-articles/what-is-the-source-editor/) or your local development environment. The following code is an example of the minimum configuration required for two Collections in CloudCannon.

File: `cloudcannon.config.yml`

```YAML
```

collections_config___1___:
  blog___2___:
    path___3___: content/posts
  data:
    path: _data

```

**[1]** Configure all your Collections under the `collections_config` key in your CloudCannon configuration file.

**[2]** Each Collection must have a unique key name.

**[3]** The `collections.[*].path` key tells CloudCannon where to find the files for your Collection. The value for this key is relative to your Site [source folder](/documentation/developer-articles/what-is-the-cloudcannon-configuration-file/#the-source-folder).
```

For more information about options you can configure in your Collections, please read our [Collections](/documentation/developer-reference/configuration-file/collections_config/) reference documentation.


---

---
title: Configure your command line options
description: Learn how to configure your command line options in CloudCannon, including your Install Command, Build Command, and Output Path.
url: https://cloudcannon.com/documentation/developer-articles/configure-your-command-line-options/
content_type: developer article
last_modified: 2026-03-12
---

Command line options instruct CloudCannon how to run your Static Site Generator and your *Site*.

You can configure the following options:

- **Install Command** — the command to install any dependencies required for your *Site*.
- **Build Command** — the command to build your *Site*.
- **Output Path** — the location to which your *Site* will build.

> If you have yet to [configure your first Site build](/documentation/developer-articles/configure-your-first-build/), CloudCannon will suggest command line options based on your Static Site Generator and the contents of your *Site* files.

To configure your command line options:

1. Navigate to the *Build configuration* page under *Site Settings*.
2. Under *Command line options*, enter your *Install Command*, *Build Command*, and *Output Path*.
3. Click the *Update Configuration and Build* button.

CloudCannon will save your updated command line options and trigger a new build.

![A screenshot of the Build Configuration page shows text fields for configuring your command line options.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Build-Configuration-Command-Line-Options.webp)

Command line options are often used in conjunction with environment variables. For more information, please read our documentation on [configuring your environment variables](/documentation/developer-articles/configure-your-environment-variables/).


---

---
title: Configure your commit messages
description: Learn how to configure commit messages to describe each commit and provide a record of the changes to your website.
url: https://cloudcannon.com/documentation/developer-articles/configure-your-commit-messages/
content_type: developer article
last_modified: 2026-03-29
---

A commit message is a short piece of text used to describe changes you make to you website. Commit messages provide a record of your changes for you and your team members. If you have commit messages configured, the *Review changes* modal will prompt you to add a commit message every time you [save your changes](/documentation/user-articles/save-your-changes/).

Commit messages in CloudCannon use predefined templates to maintain a consistent format. These templates use template strings to populate the commit message with a mix of text and data. For more information, please read our documentation on [template strings](/documentation/developer-articles/configure-your-template-strings/).

You can configure a commit message by adding the array key `commit_templates` to your [CloudCannon Configuration file](/documentation/developer-articles/what-is-the-cloudcannon-configuration-file/).

### Commit messages and external integrations

Depending on your Git provider, some external programs can integrate with your repository and read your commit messages. For example, the Jira and GitHub integration enables commits to your repository that use a specific commit message format to close Jira tickets.

It is important to configure your template string correctly if you need your commit message to match a particular format for an integration.

## Configure a commit template

To configure a basic commit message:

1. Navigate to your global configuration file and open it in the Source Editor.
2. Identify the `commit_templates` key, or create one at the top level of your configuration file.
3. Add a `template_string` item within the `commit_templates` array.
4. Save your changes to the global configuration file.

Here is an example of a simple commit message using a text string.

File: `cloudcannon.config.yml`

```YAML
```
commit_templates___1___:
  - template_string___2___: "{message}"
```

**[1]** The `commit_templates` key contains all the commit message templates in an array.

**[2]** The `template_string` key contains the template for your commit. In this example the template string uses the dynamic placeholder `{message}`. As the key "message" is undefined, CloudCannon will provide a text input.
```

Once you have saved the changes to your global configuration file, the *Review changes* modal in CloudCannon will update to include a commit message.

![The Save Changes modal with a commit message describing the changes made to the site.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Save-Changes-Modal-Commit-Message-Element.webp)

### Placeholders in commit templates

Commit templates can use placeholders. When CloudCannon reads a placeholder in a commit message, it will replace it with the data it references before sending the commit message to your Git repository.

There are two types of placeholders:

- **Data placeholders** — Replaced with data you have defined. These placeholders use `{ }` brackets.
- **Fixed placeholders** — Replaced with data defined by CloudCannon. These placeholders use `[ ]` brackets.

For commit message templates, data placeholders reference inputs you have defined in your global configuration file under `commit_templates._inputs`. If you do not define a data placeholder used by your commit template, CloudCannon will use the default input type based on the placeholder name (e.g., a date picker for `{date}`, or a text input for `{message}`).

CloudCannon recognizes the following fixed placeholders in commit templates:

- `[changes]` creates a bulleted list of all changes in the commit (edits, additions, and deletions).
- `[date]` reads as the current date.
- `[author]` reads as the email address of the person making the commit.
- `[default_commit_message]` creates the default commit message that CloudCannon would generate. This will resolve to a sentence like "Added/Updated X file(s)".

You can use a mix of data and fixed placeholders in your commit templates.

File: `cloudcannon.config.yml`

```YAML
```
commit_templates:
  - template_string___1___: |
     {ticket_number}: {subject}
     Committed by [author] at [date]
    _inputs:
      ticket_number:
        type: number
```

**[1]** The `template_string` contains two data placeholders, one defined and one undefined, and two fixed placeholders.
```

> If your commit template does not include any placeholders, any literal text in the template string will appear in a text area on the *Review changes* modal.

For more information on placeholders in general, please read our documentation on [configuring your template strings](/documentation/developer-articles/configure-your-template-strings/).

### Filters in commit templates

Commit templates can use filters to modify placeholders. Filters should occur after the placeholder name, separated by a `|` character. You can apply multiple filters to a single placeholder. For example, `{title|trim|uppercase}` will remove leading and trailing whitespace, then uppercase, a data placeholder called "title".

For more information, including a full list of filters, please read our documentation on [configuring your template strings](/documentation/developer-articles/configure-your-template-strings/).

### Multiple commit templates

You can configure multiple commit message template strings in your global configuration file. When you or a team member save changes to your website, the *Review changes* modal will prompt you to select which template to use. In this case, adding a `label` to each template string is important.

Here is an example of multiple commit message templates.

File: `cloudcannon.config.yml`

```YAML
```
commit_templates:
  - label___1___: Custom message
    template_string: "{message}"
  - label___2___: Structured message
    template_string___3___: "{commit_type}: {message|trim}"
    _inputs___4___:
      commit_type___5___:
        type: select
        options:
          values:
            - feature
            - fix
            - refactor
```

**[1]** The `label` key provides a name for the first template in the array.

**[2]** The `label` key provides a name for the second template in the array.

**[3]** This template uses two placeholders and a filter. The key `commit_type` is defined below. The key `message` is undefined and will appear as a text input with the trim filter applied to the content.

**[4]** All data placeholders used in the commit template must be defined under the `_inputs` key. If a placeholder is not defined, CloudCannon will use the default input type for that placeholder name, falling back to an empty text input.

**[5]** `commit_type` defines this key as a select input with three options, "feature", "fix", or "refactor".
```

![The Save Changes modal shows a commit message with a select and a text input.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Save-Changes-Modal-Multiple-Commit-Templates-Element.webp)

### Commit templates from a file

Rather than configure a template string in your global configuration file, you can configure a `template_path` to point at a file containing your commit template. CloudCannon will use the content of this file as your template string.

This could be a better option if you already have a file containing your commit message template or want to prevent a long commit template from taking up space in your global configuration file.

File: `cloudcannon.config.yml`

```YAML
```
commit_templates:
  - label: Commit message from file
    template_path___1___: /.git/commit-message.txt
```

**[1]** The `template_path` key value is the path of the file containing your commit template, relative to the root directory.
```

### Extra data

In some cases, you may need to create nested template strings. You can define another template string using the `extra_data` key. Anything defined under `extra_data` is processed sequentially and before `template_path` or `template_string`.

Let’s walk through an example.

We want to create an optional text field called “Breaking Change Message” for our team members to fill out when they commit a breaking change to our repository. To draw attention to the breaking change message, want the message to appear after a blank line and a ⚠️ warning emoji. When the breaking change input contains no text, we do not want any formatting associated with this message to appear in the commit.

File: `cloudcannon.config.yml`

```YAML
```
commit_templates:
  - template_string___1___: "{message}{breaking_change|if=breaking_change_message}"
    _inputs:
      breaking_change_message___2___:
        type: text
    extra_data:
      breaking_change___3___: |-

        ⚠️ {breaking_change_message}
```

**[1]** This `template_string` contains an `{message}` data placeholder (defaults to a text input) and a `{breaking_change}` and `{breaking_change_message}` data placeholder. An `if` filter means that `{breaking_change}` will not appear if `{breaking_change_message}` is empty.

**[2]** We have defined the `{breaking_change_message}` placeholder as a text input.

**[3]** The `breaking_change` placeholder functions as a nested template string, containing literal text and a `{breaking_change_message}` data placeholder.
```

In the *Review changes* modal, this will appear as two text fields. If no text is entered into the field for *Breaking Change Message*, then the extra formatting does not appear in the commit message.

![The Save Changes modal shows two fields for Message and Breaking Changes Message.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Save-Changes-Modal-Extra-Data-Element.webp)

## Options

Commit templates have the following configuration options available:

**`extra_data`** Object

Define extra variable which function as additional template strings. Use extra data to build nested templates. Extra data values are processed sequentially, before `template_string` or `template_path`.

**`_inputs`** Object

Define inputs used to populate data placeholders in your commit template. For more information, please read our documentation on [inputs](/documentation/user-articles/what-are-inputs/).

**`label`** String

Used to identify a commit template when multiple commit templates are available.

**`template_path`** String

Sets the path for a file containing your commit template. The file path should be relative to your root directory. CloudCannon will use the contents of this file as the commit template.

**`template_string`** String

Set the string for the commit template. This will only be used if `template_path` is not set.


---

---
title: Configure your environment variables
description: Learn how to configure the environment variables for your Site in CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/configure-your-environment-variables/
content_type: developer article
last_modified: 2026-04-03
---

> If you have yet to [configure your first Site build](/documentation/developer-articles/configure-your-first-build/), CloudCannon will suggest environment variables based on your SSG and the contents of your Site files.

Environment variables may be required for your site to build correctly. For example, Jekyll sites may want to set the `JEKYLL_ENV` environment variable to `production` when hosting a live site.
Environment variables can also be used to change behavior for different deployment targets. For example, you might use a different CDN for your development, staging and production sites.

To configure your environment variables:

1. Navigate to the *Build configuration* page under *Site Settings*.
2. Under *Command line options*, enter the *Key* and *Value* for your *Environment Variables*.
3. Click the *Add Environment Variable* button to add more text fields as needed.
4. Click the *Update Site* button.

![A screenshot of the Build Configuration page shows a text field for configuring your environment variables and an Add Environment Variable button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Build-Configuration-Environment-Variables.webp)

Environment variables are often used in conjunction with command line options. For more information, please read our documentation on [configuring your command line options](/documentation/developer-articles/configure-your-command-line-options/).


---

---
title: Configure your first build
description: Learn how to configure builds for your Site and trigger your first build.
url: https://cloudcannon.com/documentation/developer-articles/configure-your-first-build/
content_type: developer article
last_modified: 2026-04-03
---

Building on CloudCannon is optional; however, it is required for web hosting and visual editing.

To build through CloudCannon, you must configure any command line options and build system options required for your Site. You can do this by starting the *Set up Visual Editing* or *Host your website on the Internet* in-app guides.

![A screenshot of the Configure your Site's build settings task shows the Configure your build button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Configure-Build-Task.webp)

To configure your first Site build:

1. Start the *Set up Visual Editing* or *Host your website on the Internet* in-app guide by navigating to the *Guides* tab of your *Site Dashboard*.
2. On the *Summary* tab of your *Site Dashboard*, click the *Configure your build* button under the *Configure your Site's build settings* task. CloudCannon will open the *Configure your build* modal.
3. Enter your *Command line options* and *Build system options.* You can click on CloudCannon's suggested values to use them in your configuration.
4. Click the *Update Configuration and Build* button.

CloudCannon will attempt to build your Site. Once the build is successful, you can mark the *Configure your Site's build settings* task as complete.

![A screenshot of the Configure your build modal shows gray boxes containing CloudCannon's suggestions for your command line options.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Dashboard-Configure-Build-Modal.webp)

> CloudCannon will suggest options based on your SSG and the contents of your Site files.

You can edit your build configuration at any time on the *Configuration* page under *Site Settings*.

![A screenshot of the Build Configuration page shows blue boxes containing CloudCannon's suggestions for your command line options.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Build-Configuration.webp)

You can monitor the outcome of your first build on the *Builds* tab of your *Site Dashboard*.

![A screenshot of the Status page Builds tab shows the first build of a Site is running.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Dashboard-Builds-Tab.webp)

After a successful first build, CloudCannon will build your Site every time it syncs an update from your repository, or when you [choose to trigger a build](/documentation/developer-articles/what-is-a-site-build/#starting-a-build). This ensures your most recent content is always live.

If your build fails for any reason, CloudCannon will suggest common solutions to troubleshoot your build. For assistance configuring your builds, please contact our friendly [support team](/support/).


---

---
title: Configure your initial Site settings
description: Learn how to configure the SSG, hosting mode, and build configuration in an initial Site settings file.
url: https://cloudcannon.com/documentation/developer-articles/configure-your-initial-site-settings/
content_type: developer article
last_modified: 2026-04-11
---

When you create a new Site on CloudCannon, the syncing and building steps require you to provide values for your Site configuration (e.g., SSG, hosting mode, and build commands). Rather than enter these details during Site creation, you can configure them in an initial site settings file.

The `/.cloudcannon/initial-site-settings.json` file is useful for streamlining your Site creation process. If you manage website templates or a Site repository that you might upload to CloudCannon multiple times, specifying your build configuration in advance will make this process more efficient.

To create an initial Site settings file:

1. Using your local development environment, navigate to the `.cloudcannon` folder in your root of your repository, or create one.
2. Create a new file named `initial-site-settings.json`.
3. Configure your settings.
4. Save your initial Site settings file to you Git repository.

The next time you use this repository to create a Site, CloudCannon will skip the relevant steps during syncing and build configuration.

You can update these values in your *Site Settings* at any time. CloudCannon only uses the initial Site settings file during Site creation.

> If you create a Site by branching an existing one, CloudCannon will copy the Site settings from the original branch and ignore the initial Site settings file.

## Options

File: `/.cloudcannon/initial-site-settings.json`

```JSON

{
  "ssg": "hugo",
  "mode": "hosted",
  "build": {
    "install_command": "[ -f package.json ] && npm i",
    "build_command": "hugo -b /",
    "output_path": "public",
    "environment_variables": [
      {
        "key": "HUGO_CACHEDIR",
        "value": "/usr/local/__site/src/.hugo_cache/"
      }
    ],
    "preserved_paths": "resources/,.hugo_cache/",
    "preserve_output": false,
    "include_git": false,
    "manually_configure_urls": false,
    "hugo_version": "0.128.1",
    "ruby_version": "2.7.3",
    "node_version": "18",
    "deno_version": "1.40.2"
  }
}

```

Your initial Site settings file has the following options available:

**`ssg`** String

This key determines which Static Site Generator CloudCannon uses to provide build suggestions.

Value must be one of:

`astro` `bridgetown` `docusaurus` `eleventy` `gatsby` `hugo` `jekyll` `legacy` `lume` `mkdocs` `nextjs` `nuxtjs` `other`* `static` `sveltekit`

Note: The `other` value is called Custom SSG in the CloudCannon interface.

**`mode`** String

This key determines the hosting mode for your Site. Defaults to `hosted`.

Value must be either:

- `hosted` - enables builds, visual editing, the Testing and Custom Domains, and page previews in the collection browser.
- `headless` - disables builds for dynamic and externally-hosted Sites.

If you have not defined `mode` in your initial Site settings file, CloudCannon will build your Site during Site creation by default.

**`build`** Object

This key determines the initial build configuration settings for your Site. These options are ignored if `mode` is set to `headless`.

**`build.install_command`** String

This key determines the command to install any dependencies required for your Site to build.

**`build.build_command`** String

This key determines the command to build your Site.

**`build.output_path`** String

This key determines the location your Site will build to.

**`build.environment_variables`** Array

This key determines the environment variables required for your Site to build.

**`build.preserved_paths`** String

This key determines which paths to cache between builds. Value must be a comma separated list of path prefixes.

**`build.preserve_output`** Boolean

This key toggles whether CloudCannon will cache the files in your output directory between builds. Defaults to `false`.

**`build.include_git`** Boolean

This key toggles whether CloudCannon will include your Git folder in your build. Defaults to `false`.

**`build.manually_configure_urls`** Boolean

This key toggles whether CloudCannon will skip automatic URL detection and rely on the URLs specified in your CloudCannon configuration file. This is useful for larger Sites.

Setting this key to true will prevent CloudCannon from automatically assigning URLs to your files.

By default, this key is false (i.e., CloudCannon will automatically assign URLs to your files).

For more information, please read our documentation on [manually configuring URLs](/documentation/developer-articles/manually-configure-urls/).

**`build.hugo_version`** String

This key determines which version of Hugo is installed in your build environment.

**`build.ruby_version`** String

This key determines which version of Ruby is installed in your build environment.

**`build.node_version`** String

This key determines which version of Node is installed in your build environment.

**`build.deno_version`** String

This key determines which version of Deno is installed in your build environment.


---

---
title: Configure your Markdown engine
description: Learn how to configure CloudCannon's Markdown engine (CommonMark or Kramdown) for editing and previewing your content.
url: https://cloudcannon.com/documentation/developer-articles/configure-your-markdown-engine/
content_type: developer article
last_modified: 2026-04-11
---

CloudCannon needs to parse Markdown content into HTML to preview and edit it. Additionally, CloudCannon needs to save your Markdown in a format recognized by your SSG to build your content.

You can use the top-level `markdown` key in your [global configuration file](/documentation/developer-articles/create-your-cloudcannon-configuration-file/) to define how CloudCannon should parse and save your Markdown content.

File: `cloudcannon.config.yml`

```YAML
markdown:
  engine: 'commonmark'
  options:
    table: true
    code_block_fences: '```'
```

CloudCannon supports CommonMark and Kramdown using `markdown-it` (JavaScript) and `kramdown` (Ruby). You can use any Markdown engine you want when building your site. This article only concerns the way CloudCannon parses and saves your Markdown while you're editing.

**`engine`** string

Determines which Markdown engine to use while editing in CloudCannon. Supported values are `kramdown` and `commonmark`. Defaults to `commonmark`.

**`options.xhtml`** boolean

Ensure '/' is added to self-closing HTML tags (e.g. `<br />`) when saved back to your file.

**`options.breaks`** boolean

This key allows you to configure how the Visual Editor renders newline characters. You can use this key to match the Visual Editor's behavior to your SSG's Markdown engine.

If `true`, CloudCannon will render newline characters within paragraphs as `<br>` tags in the Visual Editor. CloudCannon will also change all `<br>` tags in the file into newline characters before saving to preserve your original formatting.

If `false`, CloudCannon will render newline characters within paragraphs normally when converted to HTML in the Visual Editor (i.e., collapsed by default). You can use Shift + Enter to add a linebreak within a paragraph. CloudCannon will save this as a `<br>` to ensure the linebreak appears when the site is built.

> In Kramdown, this option will only work if `options.gfm` is also enabled.

**`options.spaced_lists`** boolean

If `true`, list items will be saved with an extra trailing newline.

**`options.code_block_fences`** string

This should be either `~~~` or `````.
If set, this determines which styles for fences to use for code blocks in your Markdown.

Defaults to `````.

**`options.treat_indentation_as_code`** boolean

**Supported for CommonMark only.** In Kramdown, this behaviour is always enabled.

If `true`, text indented with 4 spaces will be treated as a code block.

> Most Jekyll and Hugo sites will want to set this to `true`.

**`options.escape_snippets_in_code_blocks`** boolean

If `true`, snippets inside code blocks will be always rendered as plain text instead of editable elements.

This behavior is always on when editing MDX files.

**`options.table`** boolean

If `true`, tables are saved in Markdown format. If `false`, tables are converted to HTML.

Enable this option only if your SSG's Markdown engine recognizes this syntax.

> Most Jekyll sites will want to set this to `true`.

**`options.strikethrough`** boolean

If `true`, strikethrough elements (`<del>`, `<s>`, `<strike>`) are wrapped with double tildes (e.g. ~~example~~), instead of being output as HTML.

Enable this option only if your SSG's Markdown engine recognizes this syntax.

**`options.subscript`** boolean

If `true`, subscript elements (`<sub>`) are wrapped with tildes (e.g. ~example~), instead of being output as HTML.

Enable this option only if your SSG's Markdown engine recognizes this syntax.

**`options.superscript`** boolean

If `true`, subscript elements (`<sup>`) are wrapped with carets (e.g. ^example^), instead of being output as HTML.

Enable this option only if your SSG's Markdown engine recognizes this syntax.

**`options.attributes`** boolean

If `true`, HTML attributes will be saved in Markdown format. Otherwise, elements with attributes may be converted to HTML to preserve the attributes.

Enable this option only if your SSG's Markdown engine recognizes this syntax.

**`options.attributes_elements`** object

This key determines how to save Markdown format attributes for different elements. For example, different SSGs may require Markdown attributes to appear on a newline for paragraphs, but on the same line for images.In most cases you should not need to set this option.

Allowed keys are:

- `p`, `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `hr`, `ul`, `ol`, `li`, `table`, `blockquote`, and `img`: These specify how to save Markdown attributes for specific HTML elements.
- `inline`: specifies how to save "inline" HTML elements, when not overridden by a more specific key.
- `block`: specifies how to save "block" HTML elements, when not overridden by a more specific key.

Allowed values are:

- `none`: don't allow Markdown attributes to be saved on this element type
- `right`: Markdown attributes are saved directly following the element
- `space right`: Markdown attributes are saved directly following the element, with a space in-between
- `below`: Markdown attributes are saved after a newline
- `newline below`: Markdown attributes are saved after two newlines
- `right-of-prefix`: This option only relates to list items (`li`). Markdown attributes are saved after the list prefix.

For example:

File: `example.md`

```Markdown
This example shows how different options would impact attributes on list items.

* None
* Right{.red}
* Space Right {.red}
* Below
{.red}
* Space Below

{.red}
* {.red} Right of prefix
```

Read the section below to learn more about how to configure this, and the default values for different SSGs.

**`options.gfm`** boolean

Enables extra parsing options consistent with GitHub Flavored Markdown.

Defaults to `true`.

### Display-only options

Display-only Markdown options in `markdown.options` can transform your content to render displays but cannot affect the saved content in your files.

Display-only options facilitate [visual data previews](/documentation/developer-articles/what-are-visual-data-previews/) in the [Visual Editor](/documentation/user-articles/what-is-the-visual-editor/), comments on [Inputs](/documentation/user-articles/what-are-inputs/), and descriptions for [Collections](/documentation/developer-articles/configure-your-collections/).

> If your site uses [visual data previews](/documentation/developer-articles/what-are-visual-data-previews/) to enable live editing from your rich text front matter fields, CloudCannon will use all the above options when parsing your Markdown and passing it into the Visual Editor.
> 
> CloudCannon does not automatically communicate your Markdown settings with any third-party libraries you might use to render visual data previews within the editor. If those libraries need to reparse your Markdown and do not also read your Markdown settings, they may inconsistently render some content in the previews.

**`options.linkify`** boolean

**Supported for CommonMark only.**

Automatically converts URL-like text to links.

**`options.typographer`** boolean

**Supported for CommonMark only.**

Enables automatic typograhic replacement. For example "(c)" becomes "©", and "..." becomes "…".

**`options.quotes`** string

**Supported for CommonMark only.**

This should be a string with 4 characters, representing (in order) your desired opening double quote, closing double quote, opening single quote, and closing single quote characters. Normal quote characters will be replaced with these when rendered.

For example, `„“‚‘`.

> This option will only work if `typographer` is also enabled.

**`options.heading_ids`** boolean

**Supported for CommonMark only.**

If `true`, headings within your Markdown will automatically be given ID attributes. Since `heading_ids` is a display-only option, this is only relevant for previews if your site implements special behavior for headings with IDs (e.g. an on-hover style).

### Configuring line breaks

If your SSG requires a particular format of line break within paragraphs, you can use the `breaks` and `xhtml` options to configure this.

File: `about.md`

```Markdown
This is a single paragraph
with a line break in the middle.
```

- `breaks: true` means that the newline will be preserved as `\n`.
- `breaks: false` and `xhtml: false` means that the newline will be changed to `<br>`.
- `breaks: false` and `xhtml: true` means that the newline will be changed to `<br />`.

### Constraints on Markdown tables

The GitHub Flavored Markdown (GFM) specification allows tables to be rendered in Markdown format, but requires all tables to have exactly one header row (Kramdown's implementation of GFM is an exception to this).

If you have configured CloudCannon to use GFM and to render tables as Markdown, CloudCannon will automatically add a header row when you add a table in the rich text editor. Controls for removing this header row will be disabled.

File: `cloudcannon.config.yml`

```YAML
markdown:
  engine: 'commonmark'
  options:
    table: true
    gfm: true
```

With this configuration, tables will be rendered as HTML if they violate this constraint, to preserve your content.

### Default element attribute options

CloudCannon uses sensible defaults for `markdown.options.attributes_elements` based on the configured engine.

If your `markdown.engine` is `kramdown`, `markdown.options.attributes_elements` will default to:

File: `cloudcannon.config.yml`

```YAML
markdown:
  options:
    attributes_elements:
      inline: right
      block: below
      li: right-of-prefix
```

If your `markdown.engine` is `commonmark`, `markdown.options.attributes_elements` will default to:

File: `cloudcannon.config.yml`

```YAML
markdown:
  options:
    attributes_elements:
      inline: none
      block: space right
      img: right
      ul: below
      ol: below
      li: space right
      table: newline below
      blockquote: below
```

> Hugo sites use Goldmark for Markdown processing, which has different behavior to other CommonMark parsers.
> 
> If you encounter issues with Markdown format attributes on Hugo sites, we recommend the following configuration:
> 
> File: `cloudcannon.config.yml`
> 
> ```YAML
> 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
> ```


---

---
title: Configure your rich text editors
description: Learn how to configure the Content Editor, editable regions, and Rich Text inputs in CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/configure-your-rich-text-editors/
content_type: developer article
last_modified: 2026-04-11
---

You can configure your [rich text editors](/documentation/developer-articles/what-are-rich-text-editors/) to control which text and image formatting tools are available in the WYSIWYG toolbar, the upload paths or filenames for any assets uploaded through an editor, and how CloudCannon should handle custom markup.

There are multiple ways to configure your rich text editors, depending on which editor you want to configure: [the Content Editor](/documentation/user-articles/what-is-the-content-editor/), [editable regions](/documentation/developer-articles/define-editable-regions-in-your-html/) in the [Visual Editor](/documentation/user-articles/what-is-the-visual-editor/), or [Rich Text inputs](/documentation/user-articles/what-is-a-rich-text-input/).

For a complete list of options available for rich text editors, please read our [rich text editor reference](/documentation/developer-reference/configuration-file/types/_editables/).

## The Content Editor

To configure your Content Editor:

1. Navigate to your global configuration file and open it in the Source Editor.
2. Identify the `_editables` key, or create one at the top level of your configuration file.
3. Add the `content` key under `_editables`.
4. Add any keys you want to configure under the `content` key.
5. [Save your changes](/documentation/user-articles/save-your-changes/) to the global configuration file.

Let's walk through an example. We want to allow our team members to be able to apply bold, italic, and underline formatting to text in the Content Editor. The global configuration file should look like this:

File: `cloudcannon.config.yml`

```YAML
```

_editables___1___:
  content___2___:
    bold: true
    italic: true
    underline: true

```

**[1]** Configure the Content Editor and all editable regions under the `_editables` key anywhere in the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

**[2]** Configuration options for the Content Editor are nested keys under `content`. As soon as you define one key, CloudCannon will interpret any omitted keys as false and disable those options.
```

## Rich Text inputs

To configure your Rich Text inputs:

1. Navigate to your global configuration file and open it in the Source Editor.
2. Identify the `_inputs` key, or create one at the top level of your configuration file.
3. Enter the key name for your input under the `_inputs` key.
4. Add the `options` key under your input name.
5. Add any keys you want to configure under the `options` key.
6. [Save your changes](/documentation/user-articles/save-your-changes/) to the global configuration file.

File: `cloudcannon.config.yml`

```YAML
```

_inputs___1___:
  example___2___:
    type___3___: html
    options___4___:
      bold: true
      italic: true
      underline: true

```

**[1]** Configure a Rich Text input under the `_inputs` key anywhere in the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

**[2]** Enter the key name of the input here. In this example, the input name is `example`.

**[3]** This input is an HTML Rich Text input. For more information, please read our documentation on [Rich Text inputs](/documentation/user-articles/what-is-a-rich-text-input/).

**[4]** Configuration options for the Rich Text inputs are nested keys under `options`.
```

## Editable regions

There are four types of editable regions in the Visual Editor:

- `text` for inline editable regions (e.g. `<p>` or `<h1>`)
- `block` for block editable regions (e.g. `<div>` or `<section>`)
- `link` for inline editable regions on `<a>` tags
- `image` for image editable regions (i.e. `<img>`)

To configure your editable regions:

1. Navigate to your global configuration file and open it in the Source Editor.
2. Identify the `_editables` key, or create one at the top level of your configuration file.
3. Add the key for the type of editable region under `_editables` (i.e., `text`, `block`, `link`, or `image`).
4. Add any keys you want to configure under the editable region key.
5. [Save your changes](/documentation/user-articles/save-your-changes/) to the global configuration file.

File: `cloudcannon.config.yml`

```YAML
```

_editables___1___:
  text___2___:
    bold: true
    italic: true
    underline: true
  block___3___:
    format: p h3
    undo: true
    redo: true
  link___4___:
    bold: true
    italic: true
    underline: true
  image___5___:
    mime_type: image/png
    allowed_sources:
      - site-files

```

**[1]** Configure the Content Editor and all editable regions under the `_editables` key anywhere in the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).

**[2]** Configuration options for the text editable regions are nested keys under `text`.

**[3]** Configuration options for the block editable regions are nested keys under `block`.

**[4]** Configuration options for the link editable regions are nested keys under `link`.

**[5]** Configuration options for the image editable regions are nested keys under `image`.
```

Alternatively, you can configure options directly on the element with a JSON value in the `data-cms-options` attribute.

File: `page.html`

```HTML
<p class="editable" data-cms-options='{ "bold": true, "italic": true, "underline": true}'>
  ...
</p>
```


---

---
title: Configure your Structure previews
description: Learn how to configure the appearance of Structures in Array or Object Inputs for a better editing experience.
url: https://cloudcannon.com/documentation/developer-articles/configure-your-structure-previews/
content_type: developer article
last_modified: 2026-03-29
---

You can alter how your [Structures](/documentation/developer-articles/what-is-a-structure/) appear by configuring the preview for each structure. When you have [many structures under the same key](/documentation/developer-articles/create-a-structure/#add-multiple-structures-to-the-same-key), configuring the appearance of these structures is a good way to differentiate between them and create an intuitive experience for your team members.

CloudCannon uses a [data card](/documentation/developer-articles/configure-your-card-previews/) to represent each structure in [objects](/documentation/user-articles/what-is-an-object-input/) and [arrays](/documentation/user-articles/what-is-an-array-input/). These cards are configurable UI elements that give you a preview of that data. Cards representing your structures appear in the dropdown menu, [pop-up modal](/documentation/developer-articles/create-a-structure/#add-multiple-structures-to-the-same-key), and in the [Data Editor](/documentation/user-articles/what-is-the-data-editor/) or sidebar of the [Visual](/documentation/user-articles/what-is-the-visual-editor/) or [Content Editor](/documentation/user-articles/what-is-the-content-editor/).

You can configure how card previews look using the `preview` key. For each structure, you can configure the values for the text, subtext, image, and icon within the `preview` key. The `text`, `subtext`, `image`, and `icon` keys can contain a string, a key, or an array of strings or keys.

- `text` — Add a title to your structure preview.
- `subtext` — Add a subtitle to your structure preview underneath your title. (If `text` is not configured, then the string for `subtext` will appear in the title.)
- `image` — Add an image to your structure preview.
- `icon` — Add an icon from Google’s [Material Icons](https://fonts.google.com/icons?icon.set=Material+Icons) list to your structure preview. The name of your icon must match the Material Icon name.

> Icons and images appear in the same place on your preview. If your image fails to load or has no value, it will fall back to an icon (if one is configured).

Let’s go over an example of how you would configure the preview of a structure.

We want to create an array of staff members for our staff web page. The staff array can contain items that use either an “Employee” or “Manager” template. We’ll create these item templates using two structures. The Employee structure will have fields for a name, job description, and profile picture. The Manager structure will have the same fields but also include a URL field for a link to their calendar. We will configure these fields under the `value` key in each structure.

We can configure how these structures look under the `preview` key. Let’s implement the following:

- Make the staff member’s name, job description, and profile picture appear on each card in the array.
- When no name, job description, or profile picture is selected, the fields fall back to a string or icon.

Here is our structure configuration:

File: `cloudcannon.config.yml`

```YAML
```

_inputs___1___:
  staff:
    type: array
    options:
      structures: _structures.staff
  profile_picture:
    type: image
  job_description:
    type: textarea

_structures___2___:
  staff___3___:
    style: modal
    values:
      - value___4___:
          _type: Employee
          name:
          job_description:
          profile_picture:
        preview___5___:
          text:
            - key: name
            - Employee
          subtext:
            - key: job_description
            - Description of position
          image:
            - key: profile_picture
          icon: support_agent
      - value___6___:
          _type: Manager
          name:
          job_description:
          profile_picture:
          url:
        preview___7___:
          text:
            - key: name
            - Manager
          subtext:
            - key: job_description
            - Description of position
          image:
            - key: profile_picture
          icon: face

```

**[1]** The `_inputs` key contains all the inputs defined at a given level of the configuration cascade.

**[2]** The `_structures` key contains all the structures defined at a given level of the configuration cascade.

**[3]** The key name of your structure. In this code, we have called our structure `staff`.

**[4]** This is the first structure in the group named `staff`. This structure has `value` and `preview` defined. Under value we have added fields for `name`, `job_description`, and `profile_picture`. For more information on `_type`, read our reference documentation on structures.

**[5]** Under the `preview` key in the first structure, “Employee”, we have defined `text`, `subtext`, `image`, and `icon`. In some cases, we have added an array of values for these keys to provide fallback options.

**[6]** This is the second structure in the group named `staff`. This structure has `value` and `preview` defined. Under value we have added fields for `name`, `job_description`, `profile_picture`, and `url`.

**[7]** Under the `preview` key in the second structure, “Manager”, we have defined `text`, `subtext`, `image`, and `icon`. In some cases, we have added an array of values for these keys to provide fallback options.
```

In our configuration file, the objects `preview.text` and `preview.subtext` contain arrays. These arrays initially set the object value to the keys `name` or `job_description` but also have a fallback string if no values are found. For the object `preview.text`, the fallback string is either “Employee” or “Manager”, depending on the structure. For the object `preview.subtext`, the fallback string is “Description of position”.

In both structures, we have configured the object `preview.image` to equal the value of the `profile_picture` key. If no value is found, we have configured the object `preview.icon` to equal an icon from Google’s [Material Icons](https://fonts.google.com/icons?icon.set=Material+Icons) list. The icon is `face` or `support_agent`, depending on the structure.

At the top of this configuration file, we have also defined a few inputs (i.e., `staff`, `profile_picture`, and `job_description`). For more information on this, read our documentation on configuring your [Inputs](/documentation/user-articles/what-are-inputs/).

Here is the front matter of the file containing our array:

File: `staff_page.md`

```markdown
staff: []
```

Let’s populate the array to see the previews in action.

We have added a Manager “Karen Key” and an Employee “Billy Mills”. We entered the names of each staff member in the `name` field, a short sentence about their position in the `job_description` field, and the image path in the `profile_picture` field.

We have also added two blank objects to the array, one using the Manager option and one using the Employee option.

Here is how the array looks in the sidebar of the Content Editor.

![The sidebar of the Content Editor shows an array with structure options configured.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Array-Input-Structure-Preview.webp)

Our blank array items look a little different. The text and subtext for each card match the fallback strings we configured for these options. Also, with no image path selected, the cards have fallen back to the icons we configured.

These fallback values also appear in the dropdown menu or pop-up modal when selecting an option for new array items. In the image above, the dropdown shows the value of `preview.icon` and `preview.text`. In the image below, we see the value of `preview.icon`, `preview.text`, and `preview.subtext`, when the array style is switched to a pop-up modal.

![The dropdown shows options for an array with structure options configured.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Array-Input-Structure-Modal.webp)

For more information about data cards in CloudCannon, read our documentation on [configuring your card previews](/documentation/developer-articles/configure-your-card-previews).


---

---
title: Configure your template strings
description: Learn how to configure template strings using Data or Fixed placeholders to create a dynamic string value.
url: https://cloudcannon.com/documentation/developer-articles/configure-your-template-strings/
content_type: developer article
last_modified: 2026-04-11
---

## What are template strings?

Template strings are a mixture of literal text and dynamic placeholders that are replaced with data. You can use template strings to populate complex strings.

Template strings are commonly used in:

- [Configuring your Create paths for new files](/documentation/developer-articles/set-the-path-for-new-files/)
- [Configuring your Uploads paths for new assets](/documentation/developer-articles/adjusting-the-uploads-path/)
- [Configuring your card previews](/documentation/developer-articles/configure-your-card-previews/)
- [Configuring your commit messages](/documentation/developer-articles/configure-your-commit-messages/)

Please read these articles for more specific information about the best placeholders for each use case.

## Placeholders

Placeholders reference front matter or data values. When CloudCannon reads a placeholder, it will replace the content with the data it references.

There are two types of placeholders.

- **Data placeholder** — Reads data you defined in your front matter or other data values. These placeholders use `{ }` brackets.
- **Fixed placeholder** — Reads fixed data defined by CloudCannon. These placeholders use `[ ]` brackets.

## Filters

Placeholders support several filters. Filters occur after the placeholder key, with a `|` character separating each key and filter. You can use multiple filters in sequence.

### Generic filters

- `uppercase` transforms text to uppercase
- `lowercase` transforms text to lowercase
- `deburr` converts Latin-1 Supplement and Latin Extended-A letters to basic Latin letters and removes combining diacritical marks.
- `slugify` converts non-alphanumeric characters into hyphens, then collapses sequential hyphens, then removes leading/trailing and hyphens.
- `trim` removes leading and trailing whitespace

### Date filters

- `year` gets a 4-digit year from a date
- `month` gets a 2-digit month from a date
- `day` gets a 2-digit day from a date
- `time` gets the time from a date, in a 12-hour format (e.g. 12:30pm)
- `timezone` gets the timezone from a date
- `date_short` gets a short date format (e.g. 7/12/2022)
- `date_medium` gets a medium date format (e.g. 7 Dec 2022)
- `date_long` gets a long date format (e.g. 7 December 2022)
- `date_full` gets a longer date format (e.g. Tuesday, 7 December 2022)
- `time` gets the time (e.g. 1:00pm)
- `time_short` gets a short time format (e.g. 1:00 pm)
- `time_medium` gets a medium time format (e.g. 1:00:00 pm)
- `time_long` gets a long time format (e.g. 1:00:00 pm NZDT)
- `time_full` gets a longer time format (e.g. 1:00:00 pm New Zealand Daylight Time)

> All the time and date filters format the date using the site's timezone and the user's locale.

### Filters with parameters

For some filters, you can provide extra parameters for more flexibility. Add extra parameters by including a `=` character after the filter name.

- `truncate` removes any extra characters beyond a specified number. For example, `{title|truncate=10}` will resolve to the first 10 characters of a message.
- `default` allows you to provide a fallback value, in case the data is empty
- `if` resolves to the data, if the parameter is "truthy"
- `unless` resolves to the data, if the parameter is "falsy"
- `substring` extracts a section of a string, using the [JavaScript substring method](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substring). You can specify a start and end index separated by a comma. For example, `{title|substring=1}` resolves to every character after the first. `{title|substring=1,2}` resolves to the 1 character only.
- `strip_leading_date` removes a date from the start of a string (or after a single `/`). The date can be any string composed of three numbers, where one number is 4 digits long and the other two are 1 or 2 digits, and which are separated by dashes, underscores, periods, or commas. For example `"/2025-12-01-blog.md"|strip_leading_date` will resolve to `/blog.md`.

### Filtering examples

Let's go through some examples for the following file:

File: `short-message.mdx`

```yaml

date: 2020-01-02
empty_value:
message: "Hello World"
draft: false

```

In the above file we have four keys containing different data types: `date`, `empty_value`, `message`, and `draft`.

Here are some examples of how we can transform this data using different filters:

```annotated
```

{date|day}-{date|month}-{date|year} {date|time} ({date|timezone}) #1
// 01-02-2020 00:00am (Etc/UTC)

{message|uppercase|truncate=5} #2
// HELLO

{message|if=message} #3
// Hello World

{message|unless=empty_value} #4
// Hello World

{empty_value|default="Nothing here!"} #5
// Nothing here!

{"Unpublished"|if=draft|default="Published"} #6
// Published

```

**[1]** We can use multiple date filters to control the output string. This template string uses dynamic data placeholders and literal text characters, such as `-` and `()`.

**[2]** We can convert text strings to `uppercase` and `truncate` the number of characters to five.

**[3]** We can print the value of a key if a value exists using the `if` filter.

**[4]** We can print the value of a key based on the value of another key using the `unless` filter. In this case, we print the value of `message` because `empty_value` is falsy.

**[5]** We can create a fallback option when a placeholder resolves to an empty result using the `default` filter. In this case, "Nothing here!" is printed because `empty_value` contains no value.

**[6]** We can use multiple filters to check if a key contains a value and create a fallback string if that key is falsy.
```

### Filtering nested keys and arrays

Data placeholders can reference nested keys in your front matter or other data values.

Here is an example file:

```YAML

links:
  - url: /documentation
    text: Learn more
  - url: /blog
    text: Read more
  - url:
    text:
seo:
  description: Description goes here
  tags:
    - 'sales'
    - 'documentation'

```

In the above file, we have several nested keys and arrays. You can reference these keys in a template string by using the relative path of the key, by specifying the position within an array, or by searching each item in an array using `[*]`.

Here are some examples of how we can transform this data using different filters:

> When you use `[*]` to reference each item within an array, CloudCannon will join the final output into a single string, separating each value with a comma and a space.

```annotated
```

{seo.description} #1
// Description goes here

{links.text[0].description} #2
// Learn more

{seo.tags[*]|uppercase} #3
// SALES, DOCUMENTATION

{links[*].text|default="No text"} #4
// Learn more, Read more, No text

```

**[1]** We can print the value of a nested key.

**[2]** We can print the value of a specific key within an array.

**[3]** We can print the value of every item within an array and filter the result with `uppercase`. CloudCannon automatically joins the final output into a single string.

**[4]** We can search an array using and print the value of a key each time it appears in that array. If one key is empty, we can use a fallback value using the `default` filter.
```


---

---
title: Connect a Custom Domain to your Organization
description: Learn how to connect a Custom Domain to your Organization so you can host your website through CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/connect-a-custom-domain-to-your-organization/
content_type: developer article
last_modified: 2026-02-10
---

> **Permissions required**
> 
> Members of the Owners or Developers [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `base-domain:create` permission, can connect Custom Domains to an Organization.

A Custom Domain is a unique address used to identify a website (e.g., [cloudcannon.com](https://cloudcannon.com/)). Once you have purchased a domain from a Domain Registrar, you can connect that Custom Domain to CloudCannon and use it on any Site in your Organization.

After you have connected a Custom Domain to your Organization, you can manage your Custom Domain settings and [add your Custom Domain to a Site](/documentation/developer-articles/add-a-custom-domain-to-your-site/).

These instructions assume that you want to host your website through CloudCannon and know which DNS provider is right for your Custom Domain. For more information, please read our documentation on [web hosting](/documentation/user-articles/what-is-web-hosting/) and [DNS](/documentation/developer-articles/what-is-dns/) in general.

There are two ways to connect a Custom Domain to your Organization: from the *Domains* *browser*, or from the *Custom Domain* page under your *Site Settings*.

## Connect a domain from your *Domains browser*

To connect a Custom Domain from the *Domains browser*:

1. Log in to CloudCannon and select the Organization to which you want to connect the Custom Domain.
2. Click the *Domains* button in the *App Sidebar*.  CloudCannon will open the *Domains browser*.
3. Click the *+ Connect a Domain* button in the top right of the *Domains browser*. CloudCannon will open the *Connect a Domain* page.
4. Enter your Custom Domain name in the *Base Domain* text input.
5. Select the *CloudCannon DNS* or *External DNS* option under the *DNS Provider* radio buttons.
6. Click the *Connect Domain* button.

CloudCannon will connect the Custom Domain to your Organization and open the *Domain* page for this Custom Domain.

![A screenshot of the Connect a Domain page shows a text field for your base domain name and radio buttons for your DNS provider.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Domains-Connect-a-Domain-Page.webp)

If you do not have at least one Custom Domain connected to your Organization, the *Domains* button in the *App Sidebar* will open the *Connect your first domain* page.

![A screenshot of the Connect your first Domain page.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Domains-Connect-First-Domain-Page.webp)

## Connect a domain from your *Site Settings*

To connect a Custom Domain from the *Custom Domain* page under *Site Settings*:

1. Log in to CloudCannon and select the Organization to which you want to connect the Custom Domain.
2. Click the *Sites* button in the *App Sidebar*. CloudCannon will open the *Sites browser*.
3. Navigate to the *Custom Domain* page under *Site Settings*.
4. Click the *Base Domain* dropdown and select the *+ Connect a Domain* option. CloudCannon will open the *Connect a Domain* modal.
5. Enter your Custom Domain name in the *Base Domain* text input.
6. Select the *CloudCannon DNS* or *External DNS* option under the *DNS Provider* radio buttons.
7. Click the *Connect Domain* button.

CloudCannon will connect the Custom Domain to your Organization and open the *Domain* page for this Custom Domain.

![A screenshot of the Custom Domains page under Site Settings shows the Base Domain dropdown open with the option to Connect a Domain.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Custom-Domain-Empty.webp)

![A screenshot of the Custom Domains page under Site Settings shows the Connect a Domain model with inputs for Base Domain and DNS Provider.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Custom-Domain-Connect-Domain-Modal.webp)


---

---
title: Connect a Publish Branch
description: Learn how to set up a Publish Branch in CloudCannon, using immediate merging or pull requests.
url: https://cloudcannon.com/documentation/developer-articles/connect-a-publish-branch/
content_type: developer article
last_modified: 2026-03-13
---

The CloudCannon publishing workflow lets your team edit your content on a branch site. Team members can merge their changes into the **Publish Branch** directly or with a pull request.

Connecting a *Publish Branch* allows you to create a staging site to test changes without affecting your live site.

- **Publish Branch** — This is the site to which you publish your changes. This could be your live site.
- **Branch Site** — This is the site on which you make or test your changes. This could be your staging site.

> CloudCannon enables publishing workflows for branched sites inside a [Project](/documentation/user-articles/what-is-a-project/) by default.

## Connect a Publish Branch

You must have two or more branches in your repository and two or more sites on CloudCannon to enable publishing.

To connect the branched site to your *Publish Branch*:

1. Navigate to the *Publishing* tab under *Site Settings*.
2. Search for the name of the branch connected to your *Publish Branch* and click *Add Publish Branch*.

![A screenshot of the Publishing page shows the empty state with a search field and button to add a Publish Branch.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Publishing-No-Branch.webp)

Your team can now publish changes to your *Publish Branch* via the *Publish* button in the sidebar of the branch site.

## Change your publish mode

CloudCannon offers two publishing modes: merge immediately or via pull request.

Merge immediately means that your team members can publish changes from a branch site to the *Publish Branch* without approval. This mode is great for small teams or when you want less overhead.

Pull request mode requires approval from another team member before changes can be merged with your *Publish Branch*. You can also configure Pull Requests to trigger external builds and workflows.

To change your publish mode:

1. Navigate to the *Publishing* tab under *Site Settings*.
2. Select *Merge changes immediately* or *Create a Pull Request for approval*.
3. Click *Update Publish Settings*.

CloudCannon will save your publishing mode preference for this *Site*.

![A screenshot of the Publishing page shows a connected Publish Branch with options for merge mode, pull requests, and delete after publishing.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Publishing-Connected.webp)

For more information about these two methods of publishing, please read our documentation on [Merging and Pull Requests](/documentation/developer-articles/merging-and-pull-requests/).

## Delete after publishing

You can choose to delete your branch site after a successful merge. Deleting branch sites is useful if your team creates branch sites for defined changes that require no further development after merging.

CloudCannon automatically enables this setting for branched sites inside a [Project](/documentation/developer-articles/create-a-project/).

To change your delete setting:

1. Navigate to the *Publishing* tab under *Site Settings*.
2. Check or uncheck the box labeled *Delete this site after publishing*.
3. Click *Update Publish Settings*.

CloudCannon will update your post-publishing behavior for this *Site*.


---

---
title: Connecting a Bitbucket repository as your source
description: Learn how to connect a Bitbucket repository to your site with CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/connecting-a-bitbucket-respository-as-your-source/
content_type: developer article
last_modified: 2026-03-29
---

Connecting Bitbucket allows you to work on your websites locally and have the changes sync to CloudCannon. File changes made on CloudCannon also get synced back to Bitbucket.

To connect a Bitbucket repository and start syncing files, follow these instructions:

1. Go to *Site Settings* / *Syncing*
2. Select **Bitbucket repository**
3. Click **Authenticate**

![The Site Settings Syncing page with Bitbucket repository selected from the provider dropdown and an Authenticate button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Syncing-Select-Bitbucket-No-Authorization.webp)

This redirects you to Bitbucket. Log in and authorize CloudCannon access to your Bitbucket account. You'll be redirected back to CloudCannon to pick a repository to connect. If you don't have one for this website, create a new one in Bitbucket and refresh this page.

![The Site Settings Syncing page with a Bitbucket repository selected from the repository dropdown.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Syncing-Select-Bitbucket-Complete.webp)

> Any existing files on your website will be replaced with the contents of the selected repository. Click **Backup and Sync** to continue, or exit the page to cancel the process.

Bitbucket is now connected. Changes you push to the Git repository are pulled in by CloudCannon. Any changes made on CloudCannon are automatically committed and pushed.


---

---
title: Connecting a GitHub Enterprise Server repository as your source
description: Learn how to connect a GitHub Enterprise Server repository as your source with CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/connecting-a-github-enterprise-server-repository-as-your-source/
content_type: developer article
last_modified: 2026-03-29
---

> **This feature is available on our**[**Enterprise plan**](/pricing/)**.**
> 
> Want to chat about whether this feature is right for you? Our support team is always [happy to hear from you](mailto:success@cloudcannon.com?subject=A%20question%20about%20custom%20Permission%20Groups).

Connecting to your GitHub Enterprise Server allows you to work on your websites locally and have the changes synced to CloudCannon. File changes made on CloudCannon also get synced back to your GitHub Enterprise Server repository.

> To connect to a GitHub.com repository instead, follow the instructions listed for [GitHub](/documentation/developer-articles/connecting-a-github-repository-as-your-source/).

### Creating a GitHub App

Before configuring your GitHub Enterprise Server, you need to [Create a new GitHub App](https://docs.github.com/en/enterprise-server@3.7/developers/apps/building-github-apps/creating-a-github-app). You only need to do this once per server. We recommend creating the App under a GitHub Organisation.

1. On your GitHub Enterprise Server instance, navigate to **Settings > Developer Settings > GitHub Apps** and select **New GitHub App.**
2. Fill the **Register new GitHub App** with the following:
  
  - **GitHub App name**: `CloudCannon`
  - **Homepage URL**: `https://app.cloudcannon.com`
  - **Callback URL**: `https://app.cloudcannon.com/github_enterprise_server/authorize`
  - **Setup URL**: `https://app.cloudcannon.com/github_enterprise_server/install`
  - **Redirect on update**: `true`
  - **Webhook URL**: `https://app.cloudcannon.com/hooks/github_enterprise_server/{organization_id}` (The organization specific URL can be found on *CloudCannon / Organization / Settings / GitHub Enterprise Server*)
  - **Webhook secret**: A random [string with high entropy](https://docs.github.com/en/developers/webhooks-and-events/webhooks/securing-your-webhooks#setting-your-secret-token)
3. Set the **Permissions** as follows:
  
  - **Repository permissions**
    
    - **Commit statuses**: `Read and Write`
    - **Contents**: `Read and Write`
    - **Metadata**: `Read-only`
    - **Pull requests**: `Read and Write`
  - **User permissions**
    
    - **Email addresses**: `Read-only`
4. Under **Subscribe to events** select the following events:
  
  - **Meta**
  - **Push**
5. Choose the best option for your team on the **Where can this GitHub App be installed?** option.

### Generate client secret and private key

After creating your GitHub App, you will be able to generate a client secret and a Private Key. Those keys along with other details will be used to authenticate CloudCannon requests on your GitHub Enterprise Server.

1. Under **General** settings select **Generate a new client secret.** Make sure you copy the generated secret to be used later.
2. Under **General** settings select **Generate a private key.** This will generate a PEM file and will be automatically downloaded. Keep this in a safe place to be used later.

### **Configuring your GitHub Enterprise Server**

Before syncing with a repository in your GitHub Enterprise Server, you need to configure your instance on CloudCannon. You only need to do this once per account. To connect to your GitHub Enterprise Server instance:

1. Go to *Settings / GitHub Enterprise Server*
2. Enter the details for your GitHub Enterprise Server instance:
  
  - **Endpoint**: The URL where your instance can be accessed.`https://HOSTNAME`
  - **Authorize URL**: `https://HOSTNAME/login/oauth/authorize`
  - **Token UR**L: `https://HOSTNAME/login/oauth/access_token`
  - **GitHub App ID**: Values assigned by GitHub.
  - **GitHub App Name**: `CloudCannon` (The same name used when creating the App in the [Creating a GitHub App](#creating-a-git-hub-app) step)
  - **Client ID**: Values assigned by GitHub.
  - **Client Secret**: [Previously generated](#generate-client-secret-and-private-key)
  - **WebHook Secret**: The random string with high entropy previously generated.
  - **Private Key**: Contents of the PEM file [previously generated](#generate-client-secret-and-private-key).
3. Click **Configure GitHub Enterprise Server**

![The Organization Settings page for GitHub Enterprise Server showing the initial configuration form with fields for Endpoint, Authorize URL, Token URL, GitHub App details, and keys.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-GitHub-Enterprise-Config-Form.webp)

![A screenshot of the Organization Settings page for GitHub Enterprise Server shows the configured and authenticated state with Authentication, Server, and Danger Zone tabs.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-GitHub-Enterprise-Authenticated.webp)

### Syncing with a repository

To connect a GitHub Enterprise Server repository and start syncing files, follow these instructions:

1. Go to *Site Settings / Syncing*
2. Select **GitHub Enterprise Server** repository
3. Click **Authenticate**

![The Site Settings Syncing page with GitHub Enterprise Server repository selected, showing a connected repository and branch.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Syncing-Select-GitHub-Enterprise-Complete.webp)

From there you can follow the same instructions as [configuring a GitHub.com repository](/documentation/developer-articles/connecting-a-github-repository-as-your-source/).


---

---
title: Connecting a GitHub repository as your source
description: Learn how to connect a GitHub repository to your site with CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/connecting-a-github-repository-as-your-source/
content_type: developer article
last_modified: 2026-03-29
---

Connecting GitHub allows you to work on your websites locally and have the changes sync to CloudCannon. File changes made on CloudCannon are also synced back to GitHub.

To connect a GitHub repository and start syncing files, follow these instructions:

1. Go to *Site Settings* / *Syncing*
2. Select **GitHub repository**
3. Click **Authenticate**

![The Site Settings Syncing page with GitHub repository selected from the provider dropdown and an Authenticate button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Syncing-Select-GitHub-No-Authorization.webp)

This redirects you to GitHub. Enter your credentials to continue.

![GitHub authentication screen](assets/external_screenshots/files-source-syncing-github-authentication.png)

Give CloudCannon access to your GitHub Account by clicking **Authorize CloudCannon**.

![GitHub connection screen](assets/external_screenshots/files-source-syncing-github-authorisation.png)

You’ll be redirected back to CloudCannon and asked to install the GitHub App.

![The Site Settings Syncing page with GitHub authenticated and a prompt to install the GitHub App to grant repository access.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Syncing-Select-GitHub-Repository-Dropdown.webp)

Install the CloudCannon GitHub App on your personal account or on your organization. Select to grant access to *all repositories* or *only select repositories*.

![Install GitHub App](assets/external_screenshots/files-source-syncing-github-installing.png)

You’ll be redirected back to CloudCannon  to pick a repository to connect.

![The Site Settings Syncing page with a GitHub repository selected from the repository dropdown, showing the Configure the GitHub App link.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Syncing-Select-GitHub-Complete.webp)

If you can't find your repository from the list, click **Configure the GitHub App **to change your repository access for an existing installation. Or click *Install new GitHub App* to install on a different account.

![The Installed GitHub App modal showing existing installations with a Configure access button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Syncing-Select-GitHub-Configure-App.webp)

> Any existing files on your website will be replaced with the contents of the selected repository. Click **Backup and Sync** to continue, or exit the page to cancel the process.

GitHub is now connected. Changes you push to the Git repository are pulled in by CloudCannon. Any changes made on CloudCannon are automatically committed and pushed.

## Migrating to GitHub App

By migrating to the GitHub App integration, you will be able to control the repositories to which you give CloudCannon access.

To migrate to GitHub App, follow these instructions:

1. Go to *Organization Settings > Files > GitHub*
2. Ensure you are logged into GitHub with the same GitHub account displayed above
3. Click **Migrate to GitHub app**
4. Follow the steps to **Authorize CloudCannon** and subsequently **Install** the GitHub App

Once migrated, a confirmation email will provide a link to revoke any old authentication in GitHub. Webhooks to CloudCannon on repositories can be deleted.

![A screenshot of the GitHub Organization Settings page shows a migration banner prompting the user to migrate to the GitHub App integration.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-GitHub-Migration-Pending.webp)


---

---
title: Connecting a GitLab repository as your source
description: Learn how to connect a GitLab repository to your site with CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/connecting-a-gitlab-respository-as-your-source/
content_type: developer article
last_modified: 2026-03-29
---

Connecting GitLab allows you to work on your websites locally and have the changes sync to CloudCannon. File changes made on CloudCannon also get synced back to GitLab.

> To connect to a *self-hosted GitLab* repository instead, follow the instructions listed for [Self-Hosted GitLab](/documentation/developer-articles/connecting-a-self-hosted-gitlab-repository-as-your-source/).

To connect a GitLab repository and start syncing files, follow these instructions:

1. Go to *Site Settings* / *Syncing*
2. Select **GitLab repository**
3. Click **Authenticate**

![The Site Settings Syncing page with GitLab repository selected from the provider dropdown and an Authenticate button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Syncing-Select-GitLab-No-Authorization.webp)

This will open a menu where you can connect to GitLab, via one of two methods.

## Connecting with your user account

You can connect to GitLab by authenticating with your user account. This will give your CloudCannon organization access to the same GitLab repositories you have access to.

This option will redirect you to GitLab. Log in and authorize CloudCannon access to your GitLab account, after which you will be redirected back to CloudCannon to pick a repository to connect.

![The GitLab Organization Settings page showing the OAuth authentication option with an Authenticate with GitLab button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-GitLab-Unauthenticated-OAuth.webp)

## Authenticating with a group access token

Alternatively, you can create a group access token in GitLab and save that token in CloudCannon. This will give your CloudCannon organization access to all the resources scoped to your token.

See GitLab's [Group access tokens](https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html) documentation for how to create and configure a token.

> For full functionality on CloudCannon, your group access token should have (at least) the Maintainer role, and the `api`, `read_api`, `read_repository`, and `write_repository` scopes.

Copy the token into the **Group Access Token** field. You will also need to provide the expiry date of the token. CloudCannon will send a warning email to all owners of your organization when the token is about to expire.

Click **Save and authenticate** to finish.

![The GitLab Organization Settings page showing the group access token form with fields for the token and expiry date.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-GitLab-Unauthenticated-Token.webp)

Once you've authenticated, you can choose a GitLab repository, and a branch to connect to the site. If you don't have an appropriate branch ready, create a new one in GitLab and refresh this page.

![The Site Settings Syncing page showing a GitLab repository and branch selected.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Syncing-Select-GitLab-Complete.webp)

> Any existing files on your website will be replaced with the contents of the selected repository. Click **Backup and Sync** to continue, or exit the page to cancel the process.

GitLab is now connected. Changes you push to the Git repository are pulled in by CloudCannon. Any changes made on CloudCannon are automatically committed and pushed.


---

---
title: Connecting a self-hosted GitLab repository as your source
description: Learn how to connect a self-hosted GitLab repository as your source with CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/connecting-a-self-hosted-gitlab-repository-as-your-source/
content_type: developer article
last_modified: 2026-03-29
---

> **This feature is available on our**[**Enterprise plan**](/pricing/)**.**
> 
> Want to chat about whether this feature is right for you? Our support team is always [happy to hear from you](mailto:success@cloudcannon.com?subject=A%20question%20about%20custom%20Permission%20Groups).

Connecting to your self-hosted GitLab allows you to work on your websites locally and have the changes sync to CloudCannon. File changes made on CloudCannon also get synced back to your self-hosted GitLab repository.

> To connect to a *GitLab.com* repository instead, follow the instructions listed for [GitLab](/documentation/developer-articles/connecting-a-gitlab-respository-as-your-source/).

## Connecting to an instance

Before syncing with a repository in your self-hosted GitLab, you need to connect CloudCannon to your self-hosted instance. You only need to do this once per account.

To connect to your self-hosted GitLab instance:

1. Go to *Settings* / *Self Hosted GitLab*
2. Enter the details for your self-hosted instance of GitLab
3. Click **Configure Self Hosted GitLab**

![The Organization Settings page for Self-hosted GitLab showing the initial configuration form with fields for Authorize URL, Token URL, API Endpoint, Key, and Secret.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Self-Hosted-GitLab-Config-Form.webp)

![A screenshot of the Organization Settings page for Self-hosted GitLab shows the configured and authenticated state with Authentication, Server, and Danger Zone tabs.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Self-Hosted-GitLab-Authenticated.webp)

The details for this page come from the GitLab server under *User Settings / Applications*.

![Settings page from Gitlab](assets/external_screenshots/files-source-syncing-gitlab-settings.png)

The Redirect URI is [https://app.cloudcannon.com/self_hosted_gitlab/authorize/](https://app.cloudcannon.com/self_hosted_gitlab/authorize/) The minimal scopes required are:

1. api
2. read_user
3. read_repository
4. write_repository
5. openid

Once completed, the key and secret will be available for use in CloudCannon. The URLs should match the form placeholders.

## Syncing with a repository

To connect a self-hosted GitLab repository and start syncing files, follow these instructions:

1. Go to *Site Settings* / *Syncing*
2. Select **Self Hosted GitLab repository**
3. Click **Authenticate**

![The Site Settings Syncing page with Self-hosted GitLab repository selected from the provider dropdown and an Authenticate button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Syncing-Select-Self-Hosted-GitLab-No-Authorization.webp)

This will open a menu where you can connect to GitLab, via one of two methods.

### Connecting with your user account

You can connect to GitLab by authenticating with your user account. This will give your CloudCannon organization access to the same GitLab repositories you have access to.

This redirects you to your self-hosted GitLab repository. Log in and authorize CloudCannon access to your self-hosted GitLab account, after which you will be redirected back to CloudCannon to pick a repository to connect.

![The GitLab Organization Settings page showing the OAuth authentication option with an Authenticate with GitLab button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-GitLab-Unauthenticated-OAuth.webp)

### Authenticating with a group access token

Alternatively, you can create a group access token in GitLab and save that token in CloudCannon. This will give your CloudCannon organization access to all the resources scoped to your token. See GitLab's [Group access tokens](https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html) documentation for how to create and configure a token.

> For full functionality on CloudCannon, your group access token should have (at least) the Maintainer role, and the `api`, `read_api`, `read_repository`, and `write_repository` scopes.

Copy the token into the **Group Access Token** field. You will also need to provide the expiry date of the token. CloudCannon will send a warning email to all owners of your organization when the token is about to expire.

Click **Save and authenticate** to finish.

![The GitLab Organization Settings page showing the group access token form with fields for the token and expiry date.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-GitLab-Unauthenticated-Token.webp)

Once you've authenticated, you can choose a GitLab repository, and a branch to connect to the site. If you don't have an appropriate branch ready, create a new one in GitLab and refresh this page.

![The Site Settings Syncing page showing a Self-hosted GitLab repository and branch selected.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Syncing-Select-Self-Hosted-GitLab-Complete.webp)

> Any existing files on your website will be replaced with the contents of the selected repository. Click **Backup and Sync** to continue, or exit the page to cancel the process.

Your self-hosted GitLab is now connected. Changes you push to the Git repository are pulled in by CloudCannon. Any changes made on CloudCannon are automatically committed and pushed.

## Configuring your GitLab connection

Once you've connected your GitLab server, you can configure CloudCannon to support your particular infrastructure. You can find these configuration options under the *Server* tab of your Self Hosted GitLab settings. The options you have for configuring CloudCannon are:

- Minimum Access Level,
- Custom Headers, and
- Custom CA Certificate.

![The Self-hosted GitLab Organization Settings Server tab showing options for Minimum Access Level, Custom Headers, and Custom CA Certificate.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Self-Hosted-GitLab-Server-Tab.webp)

The **Minimum Access Level** setting allows you to change the minimum access CloudCannon requires to a GitLab repo to connect to it. By default CloudCannon requires Maintainer access to a repo before syncing to it. Self Hosted GitLab allows custom access level permissions so a lower access level may be sufficient, depending on your setup.

The **Custom Headers** setting allows you to configure additional headers for CloudCannon to use when connecting to your GitLab server. Custom headers are passed using Git's `http.extraHeader` configuration option and in the form `key:value`.

The **Custom CA Certificate** allows you to upload a PEM encoded certificate or certificate chain for CloudCannon to trust during Git operations. The certificate is passed using Git's `http.sslCAInfo` configuration option.


---

---
title: Connecting your site to an Inbox
description: Connect forms on your site to an Inbox.
url: https://cloudcannon.com/documentation/developer-articles/connecting-your-site-to-an-inbox/
content_type: developer article
last_modified: 2026-04-11
---

To receive form submissions from your sites, you first need to connect your site to an Inbox in CloudCannon.

To connect your site to an Inbox:

1. Navigate to the forms menu in your site settings, under *Hosting > Forms.*
2. In the *Link Inbox* menu, select the Inbox you want to link.
3. At this point, you can also toggle the visibility of the Inbox on your site with the *Display Inbox* option. You can also require a CAPTCHA for submissions from this site with the *Require CAPTCHA* option. See here for more information about using CAPTCHA for your Inbox.
4. Click *Link Inbox* to finish linking the Inbox to your site.

Now create a form on your site and configure it to submit to one of your connected Inboxes.

To create a form:

1. Add an HTML form to a page.
2. Set the method attribute to **post.**
3. Set the action to the URL to redirect the visitor to after they submit the form.
4. Add an input element with the name `inbox_key` and set its value attribute to the key you gave your Inbox. If you don’t include this input, the submission will be sent to the default Inbox connected to your site.
5. Add form fields with name attributes to collect additional data from visitors.
6. If you are adding captcha to prevent spam, follow the documentation ([Google reCAPTCHA](https://developers.google.com/recaptcha/docs/display) or [hCaptcha](https://docs.hcaptcha.com/#add-the-hcaptcha-widget-to-your-webpage)) to add the required code to your form.

File: `contact.html`

```html
<form method="post" action="/success.html">
  <label>Email Address</label>
  <input type="text" name="email">

  <label>Name</label>
  <input type="text" name="name">

  <label>Message</label>
  <textarea name="message"></textarea>

  <label>Urgent</label>
  <input type="checkbox" name="urgent">

  <input type="hidden" name="inbox_key" value="your-inbox-key">
  <input type="text" name="_gotcha" style="display: none;">

  <input type="submit" value="Send Message">
</form>
```

### Special Fields

Any CloudCannon form can use the `_gotcha` field to help prevent untargeted spam. CloudCannon does **not** accept a submission if this field has a value. Hide it with CSS to prevent visitors from filling it out.

File: `contact.html`

```html
<input type="text" name="_gotcha" style="display: none;">
```

### Receiving files through your forms

You can also use CloudCannon Forms to receive file uploads from visitors to your site.

To set up file uploads on your form:

1. Set your form’s `enctype` attribute to `multipart/form-data`
2. Add an `input` element to your form with the `type` attribute set to `file`

File: `upload.html`

```html
<form action="/" enctype="multipart/form-data" method="post">
  <input accept="image/png, image/jpeg" id="avatar" name="avatar" type="file">
  <input type="submit" value="Send Message">
</form>
```

Now when visitors to your site submit a file through your form, CloudCannon will save that file and then replace it with a link that you can use to access the file. You will need to log in to CloudCannon in order to see the file.

If you want [Client Sharing](/documentation/user-articles/what-is-client-sharing/) users to access your form submissions, they must log in through the Client Login Page. When you add a new Inbox target and enable the *Use Client Sharing to view attached files* option, CloudCannon will ensure new form submission notifications link to the Client Login Page. You can toggle this option for existing Inbox targets using the *File attachment settings* option in the Inbox *Context Menu*.

### Limitations

File submissions through CloudCannon have the following limitations:

- Each file must be smaller than 5Mb in size.
- At most 5 files can be submitted at a time.
- Each non-file field must be smaller than 10kb in size.
- At most 100 non-file fields can be submitted at a time.

### Submitting with JavaScript

Submitting a form with JavaScript saves a page load after sending a message, providing a seamless experience. Viewers without JavaScript enabled will fall back to the normal flow.

To submit your form with JavaScript:

1. Build and test your form.
2. Override the submit event on your form.
3. Change the page to notify your viewers the message was sent.

Start with this JavaScript snippet and adapt it for your site:

File: `script.js`

```javascript
// Helper function to get form data in the supported format
function getFormDataString(formEl) {
    var formData = new FormData(formEl),
      data = [];

  for (var keyValue of formData) {
      data.push(encodeURIComponent(keyValue[0]) + "=" + encodeURIComponent(keyValue[1]));
  }

  return data.join("&");
}

// Fetch the form element
var formEl = document.getElementById("contact-form");

// Override the submit event
formEl.addEventListener("submit", function (e) {
    e.preventDefault();

  if (grecaptcha) {
      var recaptchaResponse = grecaptcha.getResponse();
    if (!recaptchaResponse) { // reCAPTCHA not clicked yet
      return false;
    }
  }

  var request = new XMLHttpRequest();

  request.addEventListener("load", function () {
    if (request.status === 303) { // CloudCannon redirects on success
      // It worked
    }
  });

  request.open(formEl.method, formEl.action);
  request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
  request.send(getFormDataString(formEl));
});
```


---

---
title: Create a Client Organization
description: Learn how to create a new Client Organization managed by your Partner Program Organization.
url: https://cloudcannon.com/documentation/developer-articles/create-a-client-organization/
content_type: developer article
last_modified: 2026-04-11
---

Client Organizations are a separate Organization that your Partner Organization manages but that your Client uses and pays for. Client Organizations are commonly used by web development and design studios in our [CloudCannon Partner Program](/partner-program/).

To create a Client Organization, you only need a name and to select the correct [pricing plan](/pricing/) for your Client's budget and needs.

If your Partner Organization uses website templates that you have not yet migrated to the Unified Configuration file format, we recommend you do not select Unified Configuration for your Client Organization. Otherwise, we highly recommend using the Unified Configuration file format. For more information, please read our guide on [migrating to Unified Configuration](/documentation/developer-guides/unified-configuration-migration-guide/).

> Client Organizations and Client Sharing are two different features. If you want to share a single Site with someone who doesn't have a CloudCannon account, please read our documentation on [Client Sharing](/documentation/user-articles/what-is-client-sharing/).

To create a Client Organization:

1. Navigate to your *Partner Dashboard*.
2. Click the *+ New client* button on the right.
3. On the *Create a new Client Organization* page, enter the name for your Client Organization, select whether Sites should use the Unified Configuration format, and choose a pricing plan.
4. Click the *Create Client Organziation* button.

CloudCannon will create your Client Organization and open a page for you to create your first Site.

![A screenshot of the Partner Dashboard shows one Partner Program Organization and a button labelled + New client.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Partner-Dashboard.webp)

![A screenshot of the Create a new Client Organization page shows a filed for Org name, Unified Configuration, and pricing plan.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Create-Client-Organization-Page.webp)


---

---
title: Create a Custom Permission Group
description: Learn how to create Custom Permission Groups for your Organization.
url: https://cloudcannon.com/documentation/developer-articles/create-a-custom-permission-group/
content_type: developer article
last_modified: 2026-03-29
---

> **This feature is available on our [Team and Enterprise plans](/pricing/).**
> 
> Want to chat about whether this feature is right for you? Our support team is always [happy to hear from you](mailto:success@cloudcannon.com?subject=A%20question%20about%20custom%20Permission%20Groups).

To create a custom [Permission Group](/documentation/user-articles/what-are-permission-groups/) in your [Organization](/documentation/user-articles/what-is-an-organization/):

1. Navigate to the *Team* page under *Org settings*.
2. Click on the *Groups* tab.
3. Under the *Groups* tab, click on the *+ Add new Group* button in the top right to open the *Create a new Group* page.
4. Enter the name of the Custom Permission Group.
5. Click the *Add permission* button to open the *Add permission* modal.
6. Select the scope for this permission using the *Scope* dropdown. If you select Base Domain, Group, Project, or Site, you must also choose the Target to that scope with the *Target* dropdown. Selecting a scope will automatically filter the resource tree.
7. Using the resource tree, select the resources you want to add and what actions you want to allow for each resource (i.e., Read, Write, or Create).
8. Click the *Add* button.
9. Repeat steps five to eight until you have added all the permissions you require.
10. If you want to include any [exceptions](/documentation/developer-articles/what-are-custom-permission-groups/#exceptions) in your Permission Group, click the *Add exception* button to open the *Add exception* modal.
11. Select the scope, target (if applicable), and resources for your exception.
12. Click the *Add* button.
13. Repeat steps ten to twelve until you have added all the exceptions you require.
14. Click the *Create group* button.

![A screenshot of the Create A New Group page shows the options to add a name, permissions, and exceptions to a Custom Permission Group.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Team-Create-Group.webp)

CloudCannon will add the new Permission Group to the *Groups* tab on the *Team* page. You are now able to [add team members to your custom permission group](/documentation/user-articles/add-a-team-member-to-a-permission-group/).

For more information, including a list of all available permissions, read our [permissions](/documentation/developer-reference/permissions/) reference documentation.


---

---
title: Create a Project
description: Learn how to create a Project in CloudCannon to group multiple Sites from the same repository.
url: https://cloudcannon.com/documentation/developer-articles/create-a-project/
content_type: developer article
last_modified: 2026-03-11
---

A [Project](/documentation/user-articles/what-is-a-project/) allows you to group multiple **Sites** from the same repository. You can create one *Project* per *Git Repository*.

To create a *Project*:

1. Click the *Projects* button in the *App Sidebar*.
2. If you already have a *Project*, CloudCannon will open the *Projects Browser* and you should click the *+ Create Project* button in the top right. Otherwise, CloudCannon will open the *Create a Project* page directly.
3. On the *Create a Project* page, select your *Git Provider*. If you have not authorized your *Git Provider*, please read our documentation on [authorizing your Git Provider](/documentation/developer-articles/authenticate-your-git-provider/).
4. Select the **Git Repository** for your *Project*. This can be a *Repository* that is already connected to a *Site* on CloudCannon.
5. Use the *Allow all branching* switch to define whether team members can create new branches from any branch in this *Project*. By default, this is off.
6. (Optional.) Enter the name of your **Main Branch**. This needs to match the name of a branch in your *Git Repository*.
7. Click the *Create Project* button.

CloudCannon will open the *Project Sites Browser*. If you do not have any branches from this *Repository* connected to a CloudCannon *Site*, this page will be empty. Otherwise, all your connected CloudCannon *Sites* will appear in the *Project Sites Browser*.

![A screenshot of the Create a Project form with all fields completed, including Git Provider, Repository, and Main Branch.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Create-a-Project-Page-Complete.webp)

![A screenshot of an empty Project page showing the Sites tab with no Sites to display.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Project-Sites-Browser-Empty.webp)

Once you have created your *Project*, you can [add Sites to it](/documentation/developer-articles/add-a-site-to-your-project/). This includes connecting existing branches as *Sites* or creating new branch *Sites* for your team members.


---

---
title: Create a schema
description: Learn how to create collection schemas for managing content across files in a collection.
url: https://cloudcannon.com/documentation/developer-articles/create-a-schema/
content_type: developer article
last_modified: 2026-03-29
---

> **Permissions required**
> 
> Members of the Technical Editors, Developers, and Owners [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `site:file:write` and `site:source-editor` permissions, can create a schema. You can limit permission to specific locations in the configuration using [file globs](/documentation/developer-articles/what-are-custom-permission-groups/#specify-a-file-glob).

There are two steps to creating a schema: creating a schema file and referencing your schema in your collection configuration.

To create a schema file:

1. Navigate to the folder where you would like to store your schema using the File Browser. We recommend creating a “Schemas” folder in your `.cloudcannon` folder.
2. Create a schema file with the same file extension as your collection files.
3. Add front matter and Markdown content to create a template.
4. [Save your file](/documentation/user-articles/save-your-changes/).

Here is an example of a schema file for an article:

File: `.cloudcannon/schemas/customer-story.md`

```Markdown

---
title:
date:
company:
thumbnail:
---
Tell us about this customer...

```

To reference a schema in your collection configuration:

1. Navigate to your global configuration file and open it in the Source Editor.
2. Within the `collections_config` key, find the key for the collection where you want to reference this schema.
3. Identify the `schemas` key, or create one.
4. Add the path to your schema file under `default`, then `path`.
5. [Save your changes](/documentation/user-articles/save-your-changes/) to the global configuration file.

Here is an example schema configuration:

File: `cloudcannon.config.yml`

```YAML

collections_config:
  blog:
    schemas:
      customer_story:
        name: Customer Story
        path: .cloudcannon/schemas/customer-story.md

```

The above code references the schema `customer-story.md` from the collection `blog`. This schema will populate new collection files with the `title`, `date`, `company`, and `thumbnail` inputs. It will also start the Markdown content with the sentence: "Tell us about this customer..."

Once you save the global configuration file, clicking the *+ Add* button in the top right of your collection browser will show that schema as an option in the dropdown menu.

![A closeup of the Collection Browser Add menu shows a schema for creating new articles.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Add-Options.webp)

Here is how the new article looks in the Content Editor.

![The Content Editor shows a Customer Story file with front matter inputs and Markdown content populated by a schema.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Schema-File.webp)

When you create a file using a schema, a hidden `_schema` input is added to the front matter of that file. This input is visible in the [Source Editor](/documentation/user-articles/what-is-the-source-editor/) but hidden in the sidebar of the Visual or Content Editor. It contains the name of the schema a file uses.

File: `acme-corp-grows-email-list.md`

```Markdown

---
_schema: customer_story
title:
date:
company:
thumbnail:
---
Tell us about this customer...

```

If you add a file to a collection with no schema referenced in the front matter, editing that file in an editing interface will add `_schema: default` to the front matter.

> Configuring a default schema is optional. If you do not want files with no defined schemas to update, do not configure a default schema.

## Reference multiple schemas in a collection

You can create and reference multiple schemas in a single collection. Multiple schemas will appear as more options in the *+ Add* button dropdown menu. By referencing multiple schemas in the same collection, you can create a list of file templates for you and your team.

You can also reference a schema in multiple collections. This will help you to keep content that uses the same template consistent across collections.

Here is an example:

File: `cloudcannon.config.yml`

```YAML

collections_config:
  posts:
    schemas:
      default:
        path: .cloudcannon/schemas/news.md
        name: Newsletter Entry
      events:
        path: .cloudcannon/schemas/events.md
        name: Upcoming Event
      announcements:
        path: .cloudcannon/schemas/announcement.md
        name: Important Announcement
  staff:
    schemas:
      default:
        path: .cloudcannon/schemas/announcement.md
        name: New Staff Announcement

```

In this example, we have the schemas for `news.md`, `events.md`, and `announcements.md` available for the collection called `posts`. The `announcements.md` schema is also available for the collection `staff`, where it is the default schema.

We have also used the `name` key to modify the name of the schema in the *+ Add* button dropdown menu. You can use the `name` key to provide context if you use the same schema in different collections.

> Schemas create new files with the same file extension as the schema file. If you need to, you can reference schemas with different file extensions from the same collection to create different file types.

## Update an existing schema

Schemas help you keep your collection files consistent. When you edit a file in a collection, CloudCannon checks that the inputs in the front matter match its defined schema. Updating a schema file by adding, removing, or reordering inputs will also update your collection files the next time you open them in an editing interface.

> CloudCannon does not update all existing collection files automatically when a schema changes. Each collection file will be updated when you next open it in an editing interface (excluding the Source Editor).

Let's go over an example.

We run a local news website. Our news collection has a default schema with inputs for each post's category, author, and title. Here is our default schema and an existing news post:

File: `post.md`

```Markdown

---
category: news
author:
title: My post
---
Add news story here...

```

File: `holding_breath_record.md`

```Markdown

---
_schema: default
category: news
author: John Simms
title: Local woman breaks the world record
---
Today, Irma Fisher broke the world record for holding her breath.

Ms Fisher, who has lived in the local area since birth, credits her achievement to swimming practice in the nearby lake.

```

We want to improve our posts by adding an image input and reordering the inputs for title and author. We have also noticed that our old schema has an input we no longer use.

In this example we want to add the input for `image` to our default schema, reorder our inputs so that `title` appears before `author`, and remove the input for `category`.

File: `post.md`

```Markdown

---
title: My updated post
author:
image: /images/posts/header.png
---
Add news story here...

```

File: `holding_breath_record.md`

```Markdown

---
_schema: default
title: Local woman breaks the world record
author: John Simms
image: /images/posts/header.png
---
Today, Irma Fisher broke the world record for holding her breath.

Ms Fisher, who has lived in the local area since birth, credits her achievement to swimming practice in the nearby lake.

```

When we save our updates to the default schema and open our news story in an editing interface, we see that CloudCannon has updated the front matter to match our schema.

The inputs for `title`, `author`, and `image` now appear in the updated order, and `category` has been removed. Reordering the `author` key has not affected its value in the collection file.

> You can customize this behavior using the `remove_extra_inputs`, `hide_extra_inputs`, `reorder_inputs` keys. For more information, please read our reference documentation for [schemas](/documentation/developer-reference/configuration-file/collections_config/*/schemas/).

> If you change the type of data stored in an input (e.g., switch from an object to a string or a string to a number), placeholder values in your schema will overwrite the values in your collection file.


---

---
title: Create a structure
description: Learn how to configure Structures to create custom templates for populating Array and Object Inputs.
url: https://cloudcannon.com/documentation/developer-articles/create-a-structure/
content_type: developer article
last_modified: 2026-03-29
---

In CloudCannon, you can configure structures under the key called `_structures`.

You can configure `_structures` at any level of the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/). Global structures, which you can reference from any array or object input on your site, are configured in your [CloudCannon configuration file](/documentation/developer-articles/create-your-cloudcannon-configuration-file/). For more information about how to define structures at other levels of the configuration cascade, read our documentation on [structures in the configuration cascade](/documentation/developer-articles/structures-in-the-configuration-cascade/).

Let’s create a structure in the global configuration file.

> Currently, you cannot configure the values for your structures in the Configuration GUI.

To create a structure:

1. Navigate to your global configuration file and open it in the Source Editor.
2. Identify the `_structures` key, or create one.
3. Add your structure within the `_structures` key.
4. [Save your changes](/documentation/user-articles/save-your-changes/) to the global configuration file.

Here is an example of a basic structure:

File: `cloudcannon.config.yml`

```YAML
```

_structures___1___:
  example___2___:
    values___3___:
      - value___4___:
          name:
          description:
          image:

```

**[1]** The `_structures` key contains all the structures defined at a given level of the configuration cascade.

**[2]** The key name of your structure. In this code, we have called our structure `example`. You can name your structure anything you want.

**[3]** The `example.values` key can contain an array of structures. We will cover [multiple structures](/documentation/developer-articles/create-a-structure/#add-multiple-structures-to-the-same-key) stored under a single key later in this article.

**[4]** This is the first structure in the group named `example`. Each structure must contain a `value` key defining what fields should populate new items of this type. This structure contains fields for `name`, `description`, and `image`. For more information on keys available for structure configuration, please read our [Configuration File](/documentation/developer-reference/configuration-file/) reference documentation.
```

In the above code, we have created a simple structure under the key `example`. This structure contains the fields for `name`, `description`, and `image`. This structure can be referenced in any array or object input.

> In this example, the inputs called “name”, “description”, and “image” should also be configured somewhere in the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/). For more information, read our documentation on [inputs](/documentation/user-articles/what-are-inputs/).

## Reference a structure in an array or object input

We can reference a structure in any number of array or object inputs. The benefits of referencing the same structure in many inputs are:

- It allows you to maintain consistency and reduce repetition across your site.
- There is no need to rename your existing inputs or structures.
- When you want to update a structure, you only need to do so in one place.

To reference a structure in an input:

1. Navigate to your global configuration file and open it in the Source Editor.
2. Identify the `_inputs` key and the input you want to reference the structure from, or create them.
3. Reference your structure using the `options.structures` key within your array or object input.
4. Save your changes to the global configuration file.

Here is an example of an array input referencing a structure:

File: `cloudcannon.config.yml`

```YAML
```

_inputs___1___:
  array_one___2___:
    type: array
    options___3___:
      structures___4___: _structures.example

```

**[1]** The `_inputs` key contains all the inputs defined at a given level of the configuration cascade.

**[2]** The key name of your array or object input. In this code, we have called our input `array_one`.

**[3]** The `options` key contains configuration options for this input. For more information on configuring your inputs, read our documentation on [Array inputs](/documentation/developer-articles/configure-an-array-input/).

**[4]** The `options.structures` key is set to `_structures.example`, referencing the structure named “example”.
```

Once you save the global configuration file, clicking the *+ Add* button below the array will add an item with the same fields as your structure.

![An empty array input in the Data Editor with an Add button for adding new items using a structure.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Array-Input-Structure-Empty.webp)

Let’s go over an example.

We want to create a single structure for storing links. The “links” structure will contain fields for `url`, `logo`, and `text`. Every time a team member adds a new item to an array that references the structure `links`, the structure will populate the new item with the fields for `url`, `logo`, and `text`.

In this example, there are two arrays which we want to add links to. The first array input is called `header_social_media`, and lists all the social media platforms we want to link to from our website header. The second array input is called `footer_affliate_links`, and lists our affiliate links in the website footer.

Here is an example of how we might create the structure for `links` and reference it in the input configuration for `header_social_media` and `footer_affliate_links`:

File: `cloudcannon.config.yml`

```YAML
```

_inputs___1___:
  header_social_media___2___:
    type: array
    options:
      structures___3___: _structures.links
  footer_affliate_links___4___:
    type: array
    options:
      structures___5___: _structures.links

_structures___6___:
  links___7___:
    values:
       - value___8___:
          url:
          logo:
          text:

```

**[1]** The `_inputs` key containing our two arrays.

**[2]** The key for the array `header_social_media`.

**[3]** The `options.structures` key is set to `_structures.links`.

**[4]** The key for the array `footer_affliate_links`.

**[5]** As with #3, the `options.structures` key is set to `_structures.links`.

**[6]** The `_structures` key contains all the structures defined at a given level of the configuration cascade.

**[7]** The key name for our structure group is `links`.

**[8]** The structure within `links`. This structure contains fields for `url`, `logo`, and `text`.
```

Let’s populate both arrays to see the `links` structure in action.

We’ve added the link for “cloudcannon.com” to the `header_social_media` array and “example.com” to the `footer_affliate_links` array.

Here is how the arrays look in the Data Editor.

![A screenshot of the Data Editor shows two Array inputs using the same Structure.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Array-Inputs-with-Shared-Structure.webp)

The arrays for `header_social_media` and `footer_affliate_links` are in the same file in this example. However, this does not have to be the case. You can add an array or object input to one file, define those inputs in a second file, and define the structure in a third, provided that all definitions have access to one another in the configuration cascade.

For more information on this topic, read our documentation on [structures in the configuration cascade](/documentation/developer-articles/structures-in-the-configuration-cascade/).

> If your structure and input key names happen to match, CloudCannon will automatically reference the structure for you, provided that the structure and input are defined in the correct levels of the configurations cascade. This behavior is convenient if you do not want to configure your inputs to reference a structure. However, we recommend choosing different names due to the benefits outlined at the beginning of this section.

## Add multiple structures to the same key

CloudCannon can store multiple structures under a single key. By creating an array of structures under a single key, you can provide your team with a selection of object templates for any array or object input.

When referencing a key that contains multiple structures, all the structures within that key are available. Therefore, the key becomes the name of a group of structures rather than a single structure.

Here is an example of multiple structures under one key:

File: `cloudcannon.config.yml`

```YAML
```

_structures:
  example___1___:
    values___2___:
      - label___3___: First
        value:
          name:
          description:
          image:
      - label___4___: Second
        value:
          heading:
          subtext:

```

**[1]** The key name of your group of structures. In this code, we have called our structure `example`.

**[2]** The `example.values` key contains an array of structures. Each structure in this array is named using the `label` key. You can also name a structure by [configuring your structure previews](/documentation/developer-articles/configure-your-structure-previews/).

**[3]** The first structure in the group named `example`. This structure contains fields for `name`, `description`, and `image`.

**[4]** The second structure in the group named `example`. This structure is different from the first, containing fields for `heading` and `subtext`.
```

You can have as many structures under one key as you want. As you create multiple structures, it is important to name each one. In this example, we will use the `label` key. Define your `label` on the same level as the `value` key using the `label`. You can also name your structures by [configuring your structure previews](/documentation/developer-articles/configure-your-structure-previews/).

Multiple structures appear as a dropdown menu when you click the *+ Add* button below an array or object.

![A dropdown menu shows two structure options, Employee and Manager, when clicking the Add button on an array input.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Array-Input-Structure-Dropdown.webp)

However, as you create more structures, a dropdown may not be the best way to view them. You can create a searchable pop-up modal to view your structures using the `style` key.

File: `cloudcannon.config.yml`

```YAML
```

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

```

**[1]** The `style` key is set to `modal`. Define the style key on the same level as the `values` key under the name of your structures group.
```

The `style` key has two values: “select” and “modal”. When the `style` key is not configured, CloudCannon sets the style to `select` by default.

When set to `select`, clicking the *+ Add* button for an array or object creates a dropdown menu. When set to `modal`, the *+ Add* button will create a pop-up modal. To switch to a modal, set the `style` key to `modal`.

You can [configure your structure previews](/documentation/developer-articles/configure-your-structure-previews/) to alter how each structure appears in the dropdown menu or pop-up modal. For more information, including how to use images, icons, and descriptions to customize your structures, read our documentation on [configuring your structure previews](/documentation/developer-articles/configure-your-structure-previews/).


---

---
title: Create your CloudCannon Configuration File
description: Learn how to create and configure your CloudCannon configuration file to customize your app experience.
url: https://cloudcannon.com/documentation/developer-articles/create-your-cloudcannon-configuration-file/
content_type: developer article
last_modified: 2026-03-29
---

> 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](https://non-unified.cloudcannon.com/documentation/developer-articles/create-a-global-configuration-file/).

> **Permissions required**
> 
> Members of the Owners, Developers, or Technical Editors [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `site:source-editor` permission, can see the *Getting Started* task list and create a CloudCannon Configuration File.

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](/documentation/developer-articles/create-your-cloudcannon-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.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Dashboard-Create-Config-File-Task.webp)

> The *Create your CloudCannon Configuration File* task or the *Getting Started with Editing* task list may not appear if you have the *Disable setup prompts* flag enabled. For more information, please read our documentation on [Flags](/documentation/developer-articles/what-are-flags/).

At minimum, your *CloudCannon Configuration File* should define your *Static Site Generator (SSG)* and *Source Folder*.

To create your CloudCannon configuration file:

1. Click the *Create my Configuration File* button under the relevant task in your *Getting Started with Editing* in-app guide.CloudCannon will open the *Create my Configuration File* modal.
2. Select your Static Site Generator (SSG) using the *Static Site Generator* dropdown, or click on the suggested SSG to populate the dropdown.
3. Optional. If your source folder is nested in your repository (such as if you have a mono-repo), check the *Use custom source* box and enter the file path in the *Source Folder* text field.
4. Once you are happy with your configuration, click the *Create my Configuration File* button at the bottom of the modal.

CloudCannon will add `cloudcannon.config.yml` to the root of your repository with your initial configuration. If required, you can move your *Configuration File* out of the root of your Git repository and [define a custom Configuration File path](/documentation/developer-articles/define-a-custom-configuration-file-path/).

![A screenshot of the Create my Configuration File modal shows text fields for selecting your SSG and source folder.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Dashboard-Create-Config-File-Modal.webp)

> Don't forget to [save your changes](/documentation/user-articles/save-your-changes/) to commit your *CloudCannon Configuration File* back to your Git repository!

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](/documentation/developer-articles/what-is-configuration-mode/) in general or the [Source Editor](/documentation/user-articles/what-is-the-data-editor/).

For more information about configuration options in your *CloudCannon Configuration File*, please read our reference documentation for your [Configuration File](/documentation/developer-reference/configuration-file/).


---

---
title: Creating a Cloudflare R2 DAM
description: Set up a DAM with Cloudflare R2 and link it to your CloudCannon Organization
url: https://cloudcannon.com/documentation/developer-articles/creating-a-cloudflare-r2-dam/
content_type: developer article
last_modified: 2026-03-29
---

Cloudflare R2 is an inexpensive cloud storage service built to be compatible with Amazon's S3 interface.

If you don't already have a Cloudflare account, you can [sign up here](https://dash.cloudflare.com/sign-up) and follow the steps below to create an R2 bucket and connect it to CloudCannon.

### Create your R2 bucket

Sign in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and open the R2 settings from the sidebar.

Use the "Create Bucket" button to create a new bucket, or select an existing bucket to configure it.

![Screenshot of R2 section of the Cloudflare dashboard](assets/external_screenshots/create-r2-bucket.png)

Choose a name for your bucket. This can be anything and will be displayed as the name of the DAM in CloudCannon.

Optionally, you can select a region for your bucket, if you don't want it to be autoselected.

Click "Create bucket" to finish and create the bucket.

![Screenshot of the bucket creation menu in Cloudflare](assets/external_screenshots/r2-initial-bucket-settings.png)

### Provide access through a custom domain

Navigate to your bucket in the R2 console, and switch to the "Settings" tab.

In the "Public access" section, you can add a custom domain where your assets will be served.

You can read more about making the contents of your bucket publically accessible here [in the Cloudflare documentation](https://developers.cloudflare.com/r2/buckets/public-buckets/).

![Screenshot of the Public Access menu in Cloudflare](assets/external_screenshots/r2-bucket-public-access.png)

### Configure CORS policies

You will need to configure your CORS policies to allow CloudCannon to interact with your bucket. In the "Settings" tab for your bucket in Cloudflare, click the "Edit CORS policy" button.

Minimally, you need to allow the GET and PUT methods, and the Content-Type header for https://app.cloudcannon.com.

![Screenshot of the CORS policy editor in Cloudflare](assets/external_screenshots/r2-bucket-cors-policy.png)

### Create an API token

You will also need to provide an API token to allow CloudCannon to access your bucket. Navigate back to the Overview page for R2 on your account, by clicking "R2 > Overview" in the sidebar.

Note down your account ID, which you'll need to copy into your CloudCannon settings later on.

Click "Manage R2 API tokens" in the top-right, and create a new API token. Copy the secret to somewhere safe.

![Screenshot of the Cloudflare R2 dashboard overview](assets/external_screenshots/r2-manage-api-token.png)

### Connect your DAM to CloudCannon

You should now have everything you need to connect CloudCannon with your R2 DAM.

Navigate to the Assets section of your Organization settings, and use the menu to authenticate a new Cloudflare R2 DAM.

![Screenshot of the CloudCannon form for authenticating an R2 DAM](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-DAM-CloudflareR2-Settings.webp)

Fill out the form as follows, then click "Authenticate" to finish.

- **DAM Provider**: Cloudflare R2.
- **Name**: This is the name you will see for your DAM in CloudCannon.
- **Base URL**: the domain name of the custom domain you configured earlier, where all your DAM assets are accessible.
- **Region**: This can be set to `auto`.
- **Endpoint**: you can copy the endpoint from your bucket settings, directly below the name of the bucket. It will look something like `https://[your-account-id].r2.cloudflarestorage.com`, and should not include anything after the ".com".
- **Access Key**: this is your Cloudflare account ID.
- **Access Secret**: this is the API token you saved earlier.

### Extra options

In your site settings, you can click the context menu on your linked DAM and select **Settings** to configure some extra site-level options.

The **Extra Prefix** option prepends a specified string to all asset paths when browsing and uploading assets. This is useful if you want to ensure that your site can only ever touch a specific folder in your DAM.


---

---
title: Creating a Cloudinary DAM
description: Set up a DAM with Cloudinary and link it to your CloudCannon Organization
url: https://cloudcannon.com/documentation/developer-articles/creating-a-cloudinary-dam/
content_type: developer article
last_modified: 2026-04-11
---

Cloudinary is a Digital Asset Manager (DAM) provider with an easy-to-use interface and a lot of powerful features. They have a generous free plan, making it a great tool if you're looking to experiment with asset management.

If you haven't already, [sign up for a free Cloudinary account](https://cloudinary.com/users/register/free). Once you have an account, [log in to your Cloudinary management console](https://cloudinary.com/users/login).

At the top of your Cloudinary console, navigate to **Dashboard** at the top of page. You should see a dashboard which lists your Cloud Name, API Key, and API Secret.

![Screenshot of Cloudinary user dashboard](assets/external_screenshots/assets-cloudinary_dashboard.png)

This page contains the necessary details to connect your Cloudinary DAM to your CloudCannon sites.

### Authenticating Cloudinary

In a new browser tab or window, open your site settings in CloudCannon. Navigate to *Files* */* *Assets*. Under *Link DAM*, select **New DAM**.

Choose **Cloudinary** as your DAM type and enter a name - this will be used to identify your DAM in CloudCannon.

In the **Username** field, enter your Cloudinary username. This is the email address that you used to sign up to Cloudinary.

Copy the **Cloud Name**, **API Key**, and **API Secret** from your Cloudinary dashboard into the respective fields in CloudCannon.

Under **Advanced options**, the **Asset browser** option determines how your Cloudinary assets are displayed and navigated in CloudCannon.

- If you *Use Cloudinary widget*, the Cloudinary widget will open. This gives you access to the advanced filtering options that Cloudinary provides.
- If you *Use CloudCannon asset browser*, the normal CloudCannon browser will open, populated with your Cloudinary assets. This is useful is you need to restrict the available assets to just the path specified by the **Folder** option described above.

If your Cloudinary account uses a custom delivery hostname, paste the full hostname into the **Custom Delivery Hostname** field to ensure the correct URLs are generated. If you are using a private CDN, check the Private CDN checkbox.

Once you have filled out all the fields, click **Authenticate** to save and close the modal.

If all went well, you should now be authenticated with your Cloudinary DAM. Next, you'll want to connect it to one or more of your sites.

### Link Cloudinary to your site

In your site settings, you can click the context menu on your linked DAM and select **Settings** to configure some extra site-level options.

The **Uploads locked** checkbox can be used to prevent uploads to your DAM from within CloudCannon.

**Upload presets** are configured in Cloudinary, and define how new assets are saved. Copy the name of an uploads preset from Cloudinary into the corresponding form field in CloudCannon to use that preset when a new asset is uploaded.  Read more about [upload presets for Cloudinary here](https://cloudinary.com/documentation/upload_presets).

The **Use upload preset to determine upload location** option ensures that **only** the upload preset determines the filename and path of a newly uploaded file. This means that CloudCannon configuration options like `dam_uploads` and `dam_uploads_filename` have no effect for this DAM, and editors cannot choose which folder a new file is uploaded to. It is best to disable this option unless you want all uploaded files to go to the location determined by your upload preset.

The **Omit Cloudinary params** checkbox can be used to omit the optional URL parameters provided by Cloudinary when saving URLs. Normally Cloudinary URLs include parameters in the middle of the URL corresponding to the asset type, delivery type, transformations, and versioning of the delivered asset. If this option is checked, URLs will be saved simply as `https://res.cloudinary.com/<cloud_name>/<public_id>.<extension>`. This may be useful if you want to add these parameters in your SSG's templating.

The **Folder** field determines which Cloudinary folder will be opened by default when a user browses existing assets from the DAM. Note that this should not begin with a leading slash.

Finally, click **Link DAM** to connect the DAM to your site.


---

---
title: Creating a DigitalOcean Spaces DAM
description: Set up a DAM with DigitalOcean Spaces and link it to your CloudCannon Organization
url: https://cloudcannon.com/documentation/developer-articles/creating-a-digitalocean-spaces-dam/
content_type: developer article
last_modified: 2026-03-29
---

[DigitalOcean Spaces](https://www.digitalocean.com/products/spaces) is a scalable, performant data storage service, built to be compatible with Amazon's S3 interface.

Below is a step-by-step guide for getting set up with DigitalOcean Spaces and connecting it to CloudCannon. Note that one step in this guide requires the use of a command-line interface.

### Create your Spaces bucket

[Sign in to your DigitalOcean account](https://cloud.digitalocean.com/), and navigate to "Spaces" using the sidebar.

Click the "Create Spaces Bucket" button. Choose a datacenter region close to your users and enter a unique name for your bucket. Finally, click "Create a Spaces Bucket" to finish.

![Screenshot of the bucket creation menu in DigitalOcean](assets/external_screenshots/digitalocean-spaces-create-bucket.png)

### Configure CORS policies

You will need to configure your CORS policies to allow CloudCannon to interact with your bucket. In the Settings tab for your bucket in DigitalOcean, click the Add button next to "CORS Configurations" to add a new policy.

Minimally, you need to allow the GET and PUT methods, and the Content-Type header for https://app.cloudcannon.com.

![Screenshot of the CORS policy editor in DigitalOcean](assets/external_screenshots/digitalocean-spaces-cors-config.png)

### Create an API token

You will also need to create an API token to allow CloudCannon to access your bucket. Click on "API" in the sidebar in DigitalOcean, and open the "Spaces Keys" tab.

Click "Generate New Key" and type any name to create the key. Save the secret token somewhere safe, and note down the Key for later.

![Screenshot of the menu in DigitalOcean for creating API keys](assets/external_screenshots/digitalocean-spaces-access-key.png)

### Make your bucket items public

By default, all the objects in your DigitalOcean Spaces bucket are private, and cannot be viewed without authentication. You will need to make them public, so that they can be viewed on your site and within CloudCannon. You can configure the permissions on each object separately within DigitalOcean, but ideally we want to make all objects in the bucket public by default.

DigitalOcean Spaces is compatible with Amazon's S3 API, so you can use the AWS CLI to make changes to your bucket policy. [See the AWS guide for installing the CLI here](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).

First, make a file called `policy.json` with the following contents, substituting `<YOUR-BUCKET-NAME>` with the name of your bucket. This policy will allow public read access for all objects within your bucket.

File: `policy.json`

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "PublicReadGetObject",
            "Effect": "Allow",
            "Principal": "*",
            "Action": [
                "s3:GetObject"
            ],
            "Resource": [
                "arn:aws:s3:::<YOUR-BUCKET-NAME>/*"
            ]
        }
    ]
}
```

Now run this command in your terminal, using the `aws` command line tool. Again, you will need to substitute the angle-bracketed placeholders with data from DigitalOcean.

```bash
AWS_ACCESS_KEY_ID=<YOUR-API-TOKEN-KEY> \
AWS_SECRET_ACCESS_KEY=<YOUR-API-TOKEN-SECRET> \
aws s3api put-bucket-policy \
    --bucket=<YOUR-BUCKET-NAME> \
    --policy=file://./policy.json \
    --endpoint-url=<YOUR-BUCKET-ENDPOINT>
```

### Connect your DAM to CloudCannon

You should now have everything you need to connect CloudCannon with DigitalOcean Spaces.

Navigate to the Assets section of your Organization settings, and use the menu to authenticate a new DigitalOcean Spaces DAM.

![Screenshot of the CloudCannon form for authenticating a DigitalOcean DAM](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-DAM-DigitalOcean-Settings.webp)

Fill out the form as follows, then click "Authenticate" to finish.

- **DAM Provider**: DigitalOcean Spaces
- **Name**: This is the name you will see for your DAM in CloudCannon.
- **Base URL**: copy the "origin endpoint" in the bucket's settings in DigitalOcean. This should look something like `https://bucket-name.reg1.digitaloceanspaces.com`
- **Region**: a 4-character code representing the your bucket's region. You can find this in the middle of the bucket's origin endpoint.
- **Endpoint**: this is the same as Base URL, but with the bucket name removed from the front (e.g. `https://reg1.digitaloceanspaces.com`)
- **Access Key**: the key name for the secret you generated earlier.
- **Access Secret**: the secret token you generated earlier.

### Extra options

In your site settings, you can click the context menu on your linked DAM and select **Settings** to configure some extra site-level options.

The **Extra Prefix** option prepends a specified string to all asset paths when browsing and uploading assets. This is useful if you want to ensure that your site can only ever touch a specific folder in your DAM.


---

---
title: Creating a form for your site on CloudCannon
description: Create forms on your site and send the submissions to an email address or integrate with your own workflows.
url: https://cloudcannon.com/documentation/developer-articles/creating-a-form-for-your-site-on-cloudcannon/
content_type: developer article
last_modified: 2026-04-11
---

> From July 2024, CloudCannon cannot guarantee support for this feature. This is a deprecated feature that only applies to Legacy CloudCannon forms. Please consider migrating to our new form configuration with the [Legacy Form Migration Guide](/documentation/developer-articles/legacy-forms-migration-guide/).

Create forms on your site and send the submissions to an email address or integrate with your own workflows.

To create a form:

1. If you haven't already, create an inbox and connect it to your site.
2. Add an HTML form to a page
3. Set the `method` attribute to **post**
4. Set the `action` to where the visitor is redirected after the form submission
5. Add an `input` element with the name `inbox_key` and set its `value` attribute to the key you gave your inbox. If you don't include this input the form will be sent to the default inbox connected to your site.
6. Add form fields with `name` attributes to collect data from visitors

File: `contact.html`

```html
<form method="post" action="/success.html">
  <label>Email Address</label>
  <input type="text" name="email">

  <label>Name</label>
  <input type="text" name="name">

  <label>Message</label>
  <textarea name="message"></textarea>

  <label>Urgent</label>
  <input type="checkbox" name="urgent">

  <label>Type of Enquiry</label>
  <input type="radio" name="_subject" value="Sales Enquiry"> Sales
  <input type="radio" name="_subject" value="General Enquiry"> General

  <input type="hidden" name="inbox_key" value="contact_inbox">
  <input type="hidden" name="_to" value="sales@example.com,support@example.com">
  <input type="hidden" name="_cc" value="sales.tracker@example.com">
  <input type="text" name="_gotcha" style="display: none;">

  <input type="submit" value="Send Message">
</form>
```

CloudCannon sends named form data to email addresses of your choosing. Alternatively, [use a hook](/documentation/developer-articles/extending-your-build-process-with-hooks/#webhooks) to integrate with services like Zapier or IFTTT.

## Special Fields

Use these fields to customize the email CloudCannon sends through the form. The fields can be hidden or visible, depending on your requirements.

`_replyto` - the value used for the Reply-To header in the email. Use this to ensure clients reply to the visitor rather than a default CloudCannon address.

File: `contact.html`

```html
<label>
  Your Email Address
  <input type="text" name="_replyto">
</label>
```

`_subject` - the subject of the email.

File: `contact.html`

```html
<select name="_subject">
  <option>General Enquiry</option>
  <option>Quote Request</option>
  <option>Support</option>
</select>
```

`_gotcha` - honeypot field for preventing untargeted spam. CloudCannon does **not** send the email if this field has a value. Hide it with CSS to prevent visitors filling it out.

File: `contact.html`

```html
<input type="text" name="_gotcha" style="display: none;">
```

> For better spam prevention try using [Google reCAPTCHA](/documentation/developer-articles/reducing-spam-by-adding-google-recaptcha/) or [hCaptcha](/documentation/developer-articles/reducing-spam-by-adding-hcaptcha/).

## Submitting with AJAX

Submitting a form with JavaScript saves a page load after sending a message, providing a seamless experience. Viewers without JavaScript enabled will fall back to the normal flow.

To submit your form with JavaScript:

1. Build and test your form
2. Override the submit event on your form
3. Change the page to notify your viewers the message was sent

Start with this JavaScript snippet and adapt it for your site:

File: `script.js`

```javascript
// Helper function to get form data in the supported format
function getFormDataString(formEl) {
    var formData = new FormData(formEl),
      data = [];

  for (var keyValue of formData) {
      data.push(encodeURIComponent(keyValue[0]) + "=" + encodeURIComponent(keyValue[1]));
  }

  return data.join("&");
}

// Fetch the form element
var formEl = document.getElementById("contact-form");

// Override the submit event
formEl.addEventListener("submit", function (e) {
    e.preventDefault();

  if (grecaptcha) {
      var recaptchaResponse = grecaptcha.getResponse();
    if (!recaptchaResponse) { // reCAPTCHA not clicked yet
      return false;
    }
  }

  var request = new XMLHttpRequest();

  request.addEventListener("load", function () {
    if (request.status === 303) { // CloudCannon redirects on success
      // It worked
    }
  });

  request.open(formEl.method, formEl.action);
  request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
  request.send(getFormDataString(formEl));
});
```


---

---
title: Creating a Google Cloud Storage DAM
description: Set up a DAM with Google Cloud Storage and link it to your CloudCannon Organization
url: https://cloudcannon.com/documentation/developer-articles/creating-a-google-cloud-storage-dam/
content_type: developer article
last_modified: 2026-04-11
---

Adding a Digital Asset Manager (DAM) to your site enables you to store your images and other assets in an external service, separate from your content. DAMs improve site build times and allow you to reuse the same assets across different sites. With Google Cloud Storage you can host your own DAM while still managing your files directly from CloudCannon.

### Create a project for your DAM

Open the navigation menu (in the top left), and navigate to *IAM and admin > Manage resources.*

In the resources console, click the **Create Project** button in the top left.

Give your project a name and then click the **Create.**

### Create your Google Cloud Storage bucket

Open the navigation menu (in the top left), and navigate to *Cloud Storage > Buckets.*

Make sure your DAM project is selected in the projects drop-down (in the top left).

In the Cloud Storage console, click the **Create** button in the top menu bar.

Give your bucket a name and choose where you want it to be located, then click the **Create** button again, leaving the other settings unchanged. Note that your choice of location may affect response times from your bucket, so you should pick a location close to your users.

Open the *Permission *tab of your newly created bucket and click the **Add** button next to the **Permissions** heading.

Enter `allUsers` as the new principal** **and select `Storage Object Viewer` from the roles drop-down.

Click the **Save **button, and then click the** Allow Public Access** button on the popup.

### Configure CORS for your bucket

Download and install the gsutil command line tool by following the instructions in the [Google Cloud Storage documentation](https://cloud.google.com/storage/docs/gsutil_install).

Create a JSON file with the following contents:

File: `cors.json`

```json
[
  {
    "origin": ["https://www.example.com"],
    "responseHeader": ["Content-Type"],
    "method": ["GET"],
    "maxAgeSeconds": 3600
  },
  {
    "origin": ["https://app.cloudcannon.com"],
    "responseHeader": ["Content-Type"],
    "method": ["*"],
    "maxAgeSeconds": 3600
  }
]
```

The CloudCannon app needs to have access to your bucket so that you can upload images to it.

Replace `https://www.example.com` in the JSON file with a list of domains that you want to be able to access your DAM, then run the following command:

```shell

gsutil cors set [path-to-your-json-file] gs://[your-bucket-name]
```

### Create an IAM role

Open the navigation menu (in the top left), and navigate to *IAM and admin > Roles*.

In the roles console, click the **Create Role** button in the top menu bar.

Give your role a title, description, and ID. Then set the role launch stage to `General Availablity.`

Click the **Add Permissions** button, and give your role the following permissions:

- storage.buckets.get
- storage.objects.create
- storage.objects.delete
- storage.objects.get
- storage.objects.list

Click the **Create** button to finish creating your role.

### Create a service account

Open the navigation menu (in the top left), and navigate to *IAM and admin > Service accounts.*

In the service accounts console, click the **Create service account **button in the top menu bar.

Give your service account a name, and select your newly created role under the **Grant this service account access to the project** section.

Click the **Done** button to finish creating your service account.

Click on the service account and open the *Keys* tab. Then click on the **Add Key** button and select the **Create new key** option.

Select `JSON` as your key type, then click the **Create** button. Save the downloaded JSON file, you’ll need this to connect your DAM to CloudCannon.

### Connecting your DAM to CloudCannon

Open your site settings in CloudCannon. Navigate to *Files* */* *Assets*. Under *Link DAM*, select **New DAM**.

Choose **Google Cloud Storage** as your DAM type and enter a name - this will be used to identify your DAM in CloudCannon.

Set *Base URL* to `https://storage.googleapis.com/<your-bucket-name>/`

Set *Storage Bucket Name* to the name of your bucket in Google Cloud Storage.

Set *Credentials* to the contents of your service account's JSON key.

Click **Authenticate**, to save and close the modal, then click **Link DAM**.

### Extra options

In your site settings, you can click the context menu on your linked DAM and select **Settings** to configure some extra site-level options.

The **Extra Prefix** option prepends a specified string to all asset paths when browsing and uploading assets. This is useful if you want to ensure that your site can only ever touch a specific folder in your DAM.


---

---
title: Creating a new Organization
description: Learn how to create a new Organization in CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/creating-a-new-organization/
content_type: developer article
last_modified: 2026-02-10
---

> **Permissions required**
> 
> Anyone can create a new Organization on CloudCannon. When you create a new Organization, CloudCannon will automatically add you to the Owners [Default Permission Group](/documentation/user-articles/what-are-default-permission-groups/) for that Org.

An Organization is the highest level of content management on CloudCannon, containing all your websites, team members, and resources in CloudCannon. When you sign up, CloudCannon will automatically create an *Organization* for you.

You can [join multiple Organizations](/documentation/user-articles/join-or-leave-an-organization/) by invitation, or create as many Organizations as you require.

To create a new Organization:

1. Click on your *Name* or *Avatar* at the bottom of the *App Sidebar* to open the *Account Menu* and select the *Organizations* option. CloudCannon will open the *Organizations Browser*.
2. Click the *+ Create organization* button on the right of your *Organization Browser Controls*. CloudCannon will open the *Create your Organization* page.
3. Enter a name for your Organization in the *Organization name* text field.
4. Click the *Create Organization* button.

CloudCannon will forward you to the *Organization Home* page for your new Organization.

![A screenshot of the Organization Browser shows the Create organization button on the right of the Organization Browser Controls.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Organization-Browser.webp)

![A screenshot of the Create your Organization page shows the Organization name text field.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Create-Organization-Page.webp)

Your new Organization will now appear in the *Organizations Browser*, which you can use to switch between Organizations at any time.


---

---
title: Creating a Tenovos DAM
description: Connect Tenovos to CloudCannon and allow editors to choose files from your DAM
url: https://cloudcannon.com/documentation/developer-articles/creating-a-tenovos-dam/
content_type: developer article
last_modified: 2026-03-29
---

Tenovos is an enterprise focused DAM (Digital Asset Manager).  Your enterprise account manager will work directly with Tenovos to make this connection. If you want to add this on your own, this document will show the process.

Connecting Tenovos will allow your editors to choose from your existing assets. This file picker will be available in all editing interfaces that accept assets. A Tenovos DAM is created on an Organisation and connected to each site. This allows you to choose which sites can interface with Tenovos and reduce configuration across branches.

To connect Tenovos to a site, first authenticate Tenovos as a DAM in your *Organization Settings / Assets* page. You can then link the authenticated DAM to any site from *Site Settings / Assets*.

![The Site Settings Assets page, showing options to link a DAM to your site.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Assets-Page.webp)

To authenticate a new Tenovos DAM, navigate to *Organization Settings / Assets* and click *Authenticate a new DAM*.

Select Tenovos from the list of DAM Providers and fill out all the details provided by Tenovos including your username and password.

![The New DAM modal with Tenovos selected as the DAM provider, showing fields for Name, Base URL, API Endpoint, Content Endpoint, API Key, Client ID, Username, and Password.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Assets-New-DAM-Modal-Tenovos.webp)

Once completed you can complete the connection to the site. Your new Tenovos DAM will be selected in the DAM drop down. Click Link DAM to finish connecting the new DAM to your site.

This new Tenovos DAM can be connected to as many sites as you like. This is useful for different branches/environments of the same site that need to interface with the same assets.


---

---
title: Creating an Azure DAM
description: Link your Azure DAM to your CloudCannon Organization
url: https://cloudcannon.com/documentation/developer-articles/creating-an-azure-dam/
content_type: developer article
last_modified: 2026-04-11
---

Adding a Digital Asset Manager (DAM) to your site enables you to store your images and other assets in an external service, separate from your content. DAMs improve site build times and allow you to reuse the same assets across different sites. With Azure Blob Storage and Azure CDN, you can host your own DAM while still managing your files directly from CloudCannon.

You will need an Azure account to use Blob Storage.

### Settings in Azure

You will need to configure the *Resource sharing (CORS)* settings in Azure Blob Storage to allow access from CloudCannon. Ensure that your CORS policies include a single rule with all of the following details:

- *AllowedOrigins* must include `https://app.cloudcannon.com`
- *AllowedMethods* must include `GET` and `PUT`.
- *AllowedHeaders* must include at least `content-type`, `x-ms-blob-type`, `x-ms-client-request-id`, `x-ms-version`. You will also need `x-ms-blob-content-type` unless this has been disabled in Advanced Options. See the section below about metadata for more details.

### Connecting your DAM to CloudCannon

Open your site settings in CloudCannon. Navigate to *Files* */* *Assets*. Under *Link DAM*, select **New DAM**.

Choose **Azure Blob Storage** as your DAM type and enter a name - this will be used to identify your DAM in CloudCannon.

Set *Base URL* to the domain name of your Azure CDN distribution or, if you chose to configure them, one of its alternate domain names.

Set *Container name* to the name of your container on Azure storage.

Enter your *Storage account name* and *Access key*.

Click **Authenticate**, to save and close the modal, then click **Link DAM**.

### Attach metadata to uploaded files

In the organization-level settings for the DAM, there are some *Advanced Options* for attach metadata to your files as they are uploaded.

The *Email of user* option will attach a piece of metadata `uploadedBy` to files uploaded to Azure from CloudCannon, with the email of the user who uploaded them. To enable this setting, you may need to update your "Resource sharing (CORS)" settings in Azure. Please ensure that the *AllowedHeaders* include `x-ms-meta-uploadedBy`.

The *X-Ms-Blob-Content-Type* option will set the content type on a file after it has been uploaded to Azure from CloudCannon. If this setting is enabled, you need to update your "Resource sharing (CORS)" settings in Azure, to ensure that the *AllowedHeaders* include `x-ms-blob-content-type`.

To edit these settings, navigate to the *Advanced Options* section under *Org Settings* > *Assets* > *Azure DAM*. Enabling the metadata option will only affect files uploaded after the setting is applied.


---

---
title: Creating an Inbox to receive your forms
description: Create an Inbox to receive your form submissions.
url: https://cloudcannon.com/documentation/developer-articles/creating-an-inbox-to-receive-your-forms/
content_type: developer article
last_modified: 2026-04-11
---

> If you're using legacy CloudCannon forms, see [here](/documentation/developer-articles/legacy-forms-migration-guide/) for a guide on migrating to the new CloudCannon forms

To get started with CloudCannon forms, you first need to create an Inbox attached to your Organization. Inboxes are responsible for receiving submissions from your sites and processing the data.

To create an Inbox:

1. Navigate to the forms menu in your Organization settings, under *Hosting > Forms.*
2. Click the *Add Inbox* button.
3. Give your Inbox a name and key. Take note of the Inbox key, as you will need this to connect sites to this Inbox. You can refer back to and change these values later from the Inbox settings.
4. At this point, you can also customize how long submissions are stored in your Inbox and add a CAPTCHA provider. See here for more information on configuring CAPTCHA providers.
5. Click the *Add Inbox* to finish creating your Inbox.

### Rate Limiting

Each Inbox on CloudCannon is limited to 2250 submissions per month. [Contact us](https://cloudcannon.com/contact) if you need this limit increased.


---

---
title: Creating an S3 DAM
description: Set up a DAM with S3 and link it to your CloudCannon Organization
url: https://cloudcannon.com/documentation/developer-articles/creating-an-s3-dam/
content_type: developer article
last_modified: 2026-04-11
---

Adding a Digital Asset Manager (DAM) to your site enables you to store your images and other assets in an external service, separate from your content. DAMs improve site build times and allow you to reuse the same assets across different sites. With AWS S3 and CloudFront, you can cheaply and easily host your own DAM while still managing your files directly from CloudCannon.

You will need an AWS account to use S3. If you haven't already, [create an AWS account](https://portal.aws.amazon.com/billing/signup), then sign in to the AWS console.

### Create your S3 bucket

Open the AWS Services menu (in the top left corner), and navigate to *Storage* / *S3*.

![Screenshot of AWS services menu with S3 highlighted](assets/external_screenshots/assets-s3-aws_console_menu.png)

In the S3 console, click **Create bucket** in the top right. Enter a name for your bucket then click **Create bucket** again, leaving the other settings unchanged. Note that S3 bucket names must be globally unique, so it's often a good idea to include your organization name in your bucket name, for example, `my-organization-dam`.

Once created, select your new bucket and open the *Permissions* tab. Scroll down to the *Cross-origin resource sharing (CORS)* section and click **Edit**. Copy the following JSON into the box:

File: `CORS`

```json

[
  {
    "AllowedHeaders": [
      "*"
    ],
    "AllowedMethods": [
      "GET",
      "PUT",
      "POST",
      "DELETE",
      "HEAD"
    ],
    "AllowedOrigins": [
      "*"
    ],
    "ExposeHeaders": []
  }
]
```

**(Optional)** Edit the *AllowedOrigins* key to include only your sites. Origins can either match single URLs `https://my-site.com` or multiple URLs using wildcards `https://*.my-site.com`. Make sure to also include `https://app.cloudcannon.com`, to ensure that CloudCannon can pull previews of your assets within the editor.

Once you are done, click **Save changes**.

### Create your CloudFront distribution

Open the AWS Services menu and navigate to *Networking & Content Delivery* / *CloudFront*.

![Screenshot of AWS Services menu with CloudFront highlighted](assets/external_screenshots/assets-s3-aws_menu_cloudfront.png)

In the top right of the screen, click **Create distribution**.

Under the *Origin* settings, set the **Origin domain** to your S3 bucket and set **Name** to what you want to name this distribution.

Under *Origin* / *S3 Bucket Access*, select **Yes use OAI**. Then create a new OAI by clicking the **Create new OAI** button and then clicking **Create** when prompted. Make sure the **Origin Access Identity** is set to your newly created OAI. Set *Bucket Policy* to **Yes update the bucket policy**.

Scroll to the *Default cache behavior* panel. Under **Viewer**, set the *Allowed HTTP methods* to **GET, HEAD, OPTIONS**.

Also in the *Default cache behavior* panel, under *Cache key and origin requests*, set *Origin request policy* to **CORS-S3Origin**, and the *Response headers policy* to **SimpleCORS**. As an optional step, if you're using wildcard origins in your S3 CORS settings create a new cache policy under *Cache policy.* Under *Cache key settings,* in the *Headers* section include the **Origin** *header*. Save that policy and set it as your distribution cache policy.

**(Optional)** Add any custom domain names you want to use for your DAM under *Settings* / *Alternate domain name (CNAME)*. If you're using HTTPS also configure your SSL certificate under *Settings > Custom SSL Certificate.*

When you are done configuring, Click **Create distribution**. On the distribution dashboard, under *General* / *Details*, take note of the **Distribution domain name**, or one of its alternate domain names if applicable. You’ll need this later to connect your DAM to CloudCannon.

![Screenshot of AWS CloudFront distribution after being created](assets/external_screenshots/assets-s3-cloudfront_distribution_screen.png)

### Create an IAM policy

In the sidebar of the IAM console, navigate to *Access management* / *Policies*, then click **Create Policy**.

![Screenshot of IAM Policies dashboard](assets/external_screenshots/assets-s3-iam_policies.png)

In the *JSON* tab, and paste the following policy - replacing the placeholder bucket name with your own.

```json

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObjectAcl",
        "s3:GetObject",
        "s3:ListBucketMultipartUploads",
        "s3:AbortMultipartUpload",
        "s3:ListBucket",
        "s3:PutObjectAcl",
        "s3:ListMultipartUploadParts"
      ],
      "Resource": [
        "arn:aws:s3:::<PlaceholderBucketName>",
        "arn:aws:s3:::<PlaceholderBucketName>/*"
      ]
    }
  ]
}
```

Click **Next** to Tags, then click **Next** again. Give your policy a name, then click **Create policy**.

### Create a CloudCannon IAM user

Open the AWS Services menu and navigate to *Security, Identity, & Compliance* / *IAM*.

![Screenshot of the AWS Services menu with IAM highlighted](assets/external_screenshots/assets-s3-aws_menu_iam.png)

In the Sidebar, navigate to *Access management* / *Users*, and click **Add users** in the top right of the page.

![Screenshot of the AWS IAM Users dashboard](assets/external_screenshots/assets-s3-iam_users_console.png)

Give the user a name (such as `CloudCannon`). Set the *AWS credential type* as **Access key - Programmatic access**, then click **Next: Permissions**.

On the next page, click **Attach existing policies directly**. locate the policy you created earlier, select it by ticking the check-box, then click **Next: Tags**, then **Next: Review**. Finally, click **Create user**.

Take note of your **Access key ID** and **Secret access key**. Once you leave this page, you will **not** be able to view the secret key again. You can recreate your access key + secret if you lose it.

#### Creating a new access key and secret

For security reasons, you may want to periodically change your access key. To create a new key, open your IAM user in the IAM console, and go to the *Security credentials* tab.

Under *Access keys*, click **Create access key**. A modal will open with your new access key and secret. Once you close this modal, you will **not** be able to view the secret again.

To remove an access key, first click **Make inactive**, then click **Deactivate** in the modal. Then, click the **x** attached to the respective key. In the modal, enter the key ID in the input field, then click **Delete**.

### Connecting your DAM to CloudCannon

Open your site settings in CloudCannon. Navigate to *Files* */* *Assets*. Under *Link DAM*, select **New DAM**.

Choose **Amazon S3** as your DAM type and enter a name - this will be used to identify your DAM in CloudCannon.

Set *Base URL* to the domain name of your CloudFront distribution or, if you chose to configure them, one of its alternate domain names.

Set *S3 Bucket Name* to the name of your bucket in S3.

Enter your *Access key ID* and *Secret access key* as your *IAM Access Key* and *IAM Access Secret,* respectively.

Click **Authenticate**, to save and close the modal, then click **Link DAM**.

### Extra options

In your site settings, you can click the context menu on your linked DAM and select **Settings** to configure some extra site-level options.

The **Extra Prefix** option prepends a specified string to all asset paths when browsing and uploading assets. This is useful if you want to ensure that your site can only ever touch a specific folder in your DAM.


---

---
title: Creating backups of your source files
description: Learn how to create an archive of your source files to protect against unintentional deletions.
url: https://cloudcannon.com/documentation/developer-articles/creating-backups-of-your-source-files/
content_type: developer article
last_modified: 2026-03-29
---

If you would like to create a new backup of your source files, navigate to *Site Settings* / *Backups* and click **Start Backup**.

When a backup is ready to download, it will show up on this page. You can have multiple backups from different points in time.

Click the **Download** button on your desired backup to download a zip of your source files, as they were at the specified date and time.

![Starting a new backup from your source files and downloading backups from specified date time](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Backups.webp)


---

---
title: Customize the Client Sharing Permission Group
description: Learn how to customize the Client Permission Group for each Site using Client Sharing.
url: https://cloudcannon.com/documentation/developer-articles/customize-the-client-sharing-permission-group/
content_type: developer article
last_modified: 2026-03-29
---

> **This feature is available on our [Team and Enterprise plans](/pricing/).**
> 
> Want to chat about whether this feature is right for you? Our support team is always [happy to hear from you](mailto:success@cloudcannon.com?subject=A%20question%20about%20custom%20Permission%20Groups).

Each Site has one [Permission Group](/documentation/user-articles/what-are-permission-groups/) for Clients with a Site scope. Anyone who logs into your Site using the Client Sharing password is considered a member of this Permission Group. [Team and Enterprise customers](/pricing/) can customize the permissions available to Clients for each Site using [Client Sharing](/documentation/user-articles/what-is-client-sharing/).

To customize the permissions in the Client Sharing Permission Group:

1. Navigate to the *Client Sharing* page under *Site settings*.
2. Click on the *Permissions* tab.
3. Select the resources you want to add and what actions you want to allow for each resource (i.e., Read, Write, or Create).
4. Click the *Update permissions* button.

![A screenshot of the Permissions tab on the Client Sharing page shows the resources and actions Clients are permitted to take for this Site.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Client-Sharing-Permissions-Tab.webp)

Unlike other [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/), you cannot configure the scope or exceptions for the Client Sharing Permission Groups.

For a complete list of resources and their associated actions, please read our [permissions](/documentation/developer-reference/permissions/) reference documentation.


---

---
title: Define a custom Configuration File path
description: Learn how to define a custom filepath for your CloudCannon Configuration File.
url: https://cloudcannon.com/documentation/developer-articles/define-a-custom-configuration-file-path/
content_type: developer article
last_modified: 2026-04-11
---

> **Permissions required**
> 
> Members of the Owners or Developers [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `x` permission, can...

By default, CloudCannon looks for your *CloudCannon Configuration File* in the root directory of your Git repository. If your *Configuration File* is in a nested folder, you must define a custom file path.

To define a custom configuration file path:

1. Navigate to the *Details* page under your *Site Settings*.
2. Under *CloudCannon Configuration Path*, enter the file path for your CloudCannon configuration file in the text field. Note: this file must have the `.json`, `.yaml`, or `.yml` file extension.
3. Click the *Update Details* button.

CloudCannon will now preferentially use the configuration file at this file path.

![A screenshot of the Details page under Site Settings shows the CloudCannon Configuration File path text field.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Details.webp)


---

---
title: Define editable regions in your HTML
description: Editable Regions let you edit parts of your HTML visually and with live updates.
url: https://cloudcannon.com/documentation/developer-articles/define-editable-regions-in-your-html/
content_type: developer article
last_modified: 2026-04-11
---

> Since October 2025, this method of visual editing has been deprecated. CloudCannon cannot guarantee support for this feature. Please consider using [Editable Regions](/documentation/developer-articles/what-are-editable-regions/) or Bookshop.

> The `class="editable"` attribute for Editable Regions function in the following file types: `.htm`, `.html`, `.ejs`, `.pug`, `.haml`, `.mustache`, `.hbs`, `.njk`, and `.liquid`.
> 
> For an alternative visual editing option, please read our guide on [Bookshop for Eleventy](/documentation/developer-guides/bookshop-eleventy-guide/) and [Bookshop for Astro](/documentation/developer-guides/bookshop-astro-guide/).

Editable Regions enable you to visually edit content in your source HTML in place on your output HTML.

Editable Regions are HTML elements that you define as editable. Define broad sections to provide flexibility, or define separate regions to retain fine control over images and text elements. Editable Regions display yellow borders in the [Visual Editor](/documentation/edit/interfaces/visual-editor/) to indicate areas that can be updated.

Depending on the element an editable is applied to, editors see different options in the editor. There are four types available for editing content in place:

- Inline regions for editing plain text
- Image regions for editing image elements
- Block regions for editing rich text
- Content for editing rich text populated from file content sections

To define an Editable Region:

1. Identify the HTML element you want to be editable
2. Add `class="editable"` to the HTML element, or append `editable` to `class` if the attribute is already defined

![Screenshot of the Visual Editor with multiple Editable Regions defined](/assets/deprecated/editing-editable-regions-block-editable.png)

> JavaScript is supported in the [Visual Editor](/documentation/edit/interfaces/visual-editor/). However, HTML rendered with JavaScript on page load is not editable.

For more information, read our documentation on how to [configure your rich text toolbars](/documentation/developer-articles/configure-your-rich-text-editors/).

## Best practices for Editable Regions

Not all HTML elements can be edited safely in the Visual Editor. It’s important to think carefully about what you want to be edited, and add the "editable" class only to those elements.

Improperly applied Editable Regions allow team members to break the layout of your site, in ways that can only be fixed in the Source Editor. To prevent this, CloudCannon automatically detects problem cases and disables editing.

Here are some examples of common misuses of Editable Regions, why they don’t conform to best practices, and how to refactor them.

### Unsupported elements

```HTML

<input type="checkbox" class="editable">

```

Some elements are simply not editable in the Visual Editor. It’s unclear what it would mean to edit an `<input>`, and this probably was not the developer’s intention. Only the following HTML elements should be given the editable class:

- Blocks: `div`, `section`, `article`, `aside`, `main`, `footer`, `header`, `nav`
- Block text: `p`, `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `blockquote`, `li`, `dd`, `dt`
- Inline text: `span`, `small`, `strong`, `em`, `i`, `b`, `sub`, `sup`, `td`, `th`, `cite`
- Image: `img`
- Link: `a`

#### How to fix this

Remove the "editable" class.

If you need this element to be editable, you can configure a Snippet. Depending on your SSG, there are libraries of Snippets available, or you can create custom Snippets.

### Editable regions containing unsupported elements

```HTML

<div class="editable">
  <input type="email" name="email" id="email" />
  <p>Enter your email</p>
</div>

```

This would create an editable region containing an uneditable element (`input`). If someone on your team backspaces too many times in this Editable Region, they could delete the `<input>` with no way to restore it.

#### How to fix this

Move the "editable" class directly onto the text you want to edit.

```HTML

<form>
  <input type="email" name="email" id="email" />
  <p class="editable">Enter your email</p>
</form>

```

### Editable regions containing custom classes

```HTML

<div class="editable">
  <p class="big">This text is big</p>
  <p class="small">This text is small<p>
</div>

```

If you have used the `styles` configuration option to include the "big" and "small" classes for <p> elements in this Rich Text input, this code will work perfectly!

Otherwise, this poses a problem. If an editor removes all the text in `p.small`, they will have no way to restore it, since there is no way to add arbitrary class names in the editor.

#### How to fix this

One way to fix this would be to add the `styles` configuration to include these class names. [Read more about this option here](/documentation/user-articles/what-is-a-rich-text-input/#styles-and-alignment).

File: `cloudcannon.config.yml`

```YAML

_editables:
  block:
    options:
      styles:  paragraph-styles.css

```

File: `paragraph-styles.css`

```CSS

p.big {
  font-size: 2em;
}

p.small {
  font-size: 0.5em;
}

```

Another way would be to move the "editable" class down a level, assuming you always want 1 line of each kind of text:

```HTML

<div>
  <p class="big editable">This text is big</p>
  <p class="small editable">This text is small<p>
</div>

```

### Editable regions containing templating code

```HTML

<div class="editable">
  <h3>Blog posts</h3>
  <ul>
  {% for post in collections.posts %}
    <li>{{ post.title }}</li>
  {% endfor %}
  </ul>
</div>

```

This editable region contains templating code that will be run by an SSG when the site is built. The Visual Editor shows the built output of a page, so this editable region might look like a normal list of blog post titles. However, it would be very destructive to edit this `<div>` since the templating code (invisible on the page) could easily be destroyed.

Using templating code inside an editable region is an anti-pattern and should be avoided in all cases.

#### How to fix

Move the editable region so that it doesn’t contain any templating code. In this example, we can still allow the user to edit the titles of blog posts, by providing in-editor links to the posts themselves. This is much safer, and removes repetition of content from the site.

To learn more about showing links only in the Visual Editor, [read this article](/documentation/developer-articles/detecting-your-site-is-loaded-in-the-visual-editor).

To learn more about linking to different views in CloudCannon, [read this article](/documentation/developer-articles/extending-in-app-navigation-with-editor-links).

```HTML

<div>
  <h3 class="editable">Blog posts</h3>
  <ul>
  {% for post in collections.posts %}
		<li>{{ post.title }}</li>
		<a href="cloudcannon:collections/posts/{{ post.path }}" class="show-in-cms-only">
			Edit this post
		</a>
	{% endfor %}
	</ul>
</div>

```

### Editable regions modified with JavaScript

```HTML

<div class="editable">
  <p>Welcome. The time is</p>
</div>

<script>
  const timeMessage = document.querySelector('p');
  timeMessage.innerHTML = timeMessage.innerHTML + ' ' + new Date().toString();
</script>

```

The script on this page will add the current time to the `<p>` within the editable region. The Visual Editor will recognize this as a change to the content of the editable region and will save it back to the source code, breaking the intended behaviour.

#### How to fix

It's important to make sure no dynamic content is being added to an editable region. In this case, we could simply move the "editable" class onto the static text.

```HTML

<div>
  <p><span class="editable">Welcome. The time is<span></p>
</div>

<script>
  const timeMessage = document.querySelector('p');
  timeMessage.innerHTML = timeMessage.innerHTML + ' ' + new Date().toString();
</script>

```

Another solution would be to prevent the script running inside the Visual Editor. See [this article for more information](/documentation/developer-articles/detecting-your-site-is-loaded-in-the-visual-editor/) about checking whether a page is being loaded inside CloudCannon.

```HTML

<div class="editable">
  <p>Welcome. The time is</p>
</div>

<script>
  if (!window.inEditorMode) {
    const timeMessage = document.querySelector('p');
    timeMessage.innerHTML = timeMessage.innerHTML + ' ' + new Date().toString();
  }
</script>

```


---

---
title: Define your data
description: Learn how to define data files or folders to populate your Select and Multiselect inputs.
url: https://cloudcannon.com/documentation/developer-articles/define-your-data/
content_type: developer article
last_modified: 2026-04-11
---

> 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](https://non-unified.cloudcannon.com/documentation/developer-articles/define-your-data/).

You can use data files and folders to populate your [Select and Multiselect](/documentation/user-articles/what-is-a-select-input/) inputs. Using a data file or folder to populate your value options is useful when you want your [team members](/documentation/user-articles/what-is-a-team-member/) to be able to edit the available options.

> Data files/folders (i.e., `data_config`) are different to fixed data sets (i.e., `_select_data`).
> 
> For more information about fixed data sets, please read our documentation on [Select and Multiselect inputs](/documentation/user-articles/what-is-a-select-input/).

You can define your data files and folder in the [CloudCannon configuration file](/documentation/developer-articles/what-is-the-cloudcannon-configuration-file/) under the `data_config` key.

To define a data file or folder:

1. Navigate to your CloudCannon configuration file.
2. Identify the `data_config` key at the root level of your configuration file, or add it if the key is not present.
3. Enter a key name for your data nested within the `data_config` key.
4. Add the `path` key within your data key and define the filepath to your data file or folder.
5. Save your changes.

Your data file or folder is now available for [Select and Multiselect](/documentation/user-articles/what-is-a-select-input/) inputs configured with this data key.

File: `cloudcannon.config.yml`

```YAML
```

data_config___1___:
  authors:
    path___2___: data/authors.csv
  offices:
    path___3___: data/offices

```

**[1]** Configure all data files or folders under the `data_config` key in your [CloudCannon configuration file](/documentation/developer-articles/what-is-the-cloudcannon-configuration-file/).

**[2]** Select and Multiselect inputs which use the `authors` key are populated by the contents of the `authors.csv` file.

**[3]** Select and Multiselect inputs which use the `offices` key are populated by the contents of each file in the `offices` folder.
```

## Options

Your data configuration has the following options available:

**`data_config`** Object

This key defines which file or folder data in your Site is available to populate [Select and Multiselect inputs](/documentation/user-articles/what-is-a-select-input/).

This key has no default.

**`data_config.[*].path`** String

This key defines the file or folder path for the data key in which it is nested.

The value for this key is relative to your Site source. Each Collection must have a unique path.

This key has no default.

File: `cloudcannon.config.yml`

```YAML
data_config:
  products:
    path: data/products
```


---

---
title: Defining the same key in multiple Configuration Files
description: Learn how CloudCannon handles configuration for the same key across multiple Configuration Files.
url: https://cloudcannon.com/documentation/developer-articles/defining-the-same-key-in-multiple-configuration-files/
content_type: developer article
last_modified: 2026-02-10
---

When you define a configuration key at the same level of the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/) in multiple [CloudCannon Configuration Files](/documentation/developer-articles/what-is-the-cloudcannon-configuration-file/), CloudCannon will preferentially use configuration from the last file in the import order.

CloudCannon uses the [localeCompare()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/localeCompare) Javascript function when importing definitions for object keys in the main *Configuration File* and other *Configuration Files* referenced by a `*_from_glob` key. Any inline configuration in your *Configuration File* is used first, followed by the imported configuration from other files in alphabetical [Unicode](https://en.wikipedia.org/wiki/List_of_Unicode_characters) order.

Unicode order respects upper and lowercase letters, punctuation, locale-specific rules for special characters, and accented letters, ensuring proper ordering for international filenames.

## Multiple configurations for an array key

When you define multiple values for an array configuration key (e.g., `_structures.*.values`), CloudCannon will not overwrite any array item with another. Instead, array items referenced in another *Configuration File* using a `*_from_glob` key are appended to arrays defined in your main *Configuration File*. The order of array items in the array will follow the import order (i.e., inline configuration first, followed by configuration from other files in Unicode order).

File: `cloudcannon.config.yml`

```YAML
```

_structures:
  staff:
    style: modal
    values_from_glob___1___:
      - '/.cloudcannon/boardMember.cloudcannon.structure_value.yml'
    values___2___:
      - label: Employee
        value:
          name:
          title:
          profile_picture:
      - label: Manager
        value:
          name:
          title:
          profile_picture:
          url:

```

**[1]** The main *Configuration File* references another *Configuration File*, `board_member.cloudcannon.structure_value.yml`, using `_structures.staff.values_from_glob`.

**[2]** In the main *Configuration File*, there are two array items in `_structures.staff.values`, "Employee" and "Manager".
```

File: `/components/team/boardMember.cloudcannon.structure-value.yml`

```YAML
```

label___3___: Board
value:
  name:
  title:
  profile_picture:
  url:
  description:

```

**[2]** In `boardMember.cloudcannon.structure-value.yml`, there is one array item, "Board". CloudCannon will append this value after the inline values defined in the main *Configuration File* as the `boardMember.cloudcannon.structure-value.yml` file is last in the import order (inline values are always first).
```

## Multiple configurations for an object key

When you define multiple values for an object configuration key (e.g., `_inputs`, `collection_config`), CloudCannon will preferentially use the configuration of the from the last file in the import order (i.e., inline configuration first, followed by configuration from other files in Unicode order).

This means, when you define conflicting object keys inline in your main *Configuration File* and in another *Configuration File* referenced by a `*_from_glob` key, CloudCannon will preferentially use the configuration defined outside of the main *Configuration File*.

File: `cloudcannon.config.yml`

```YAML
```

_inputs_from_glob___1___:
  - '/.cloudcannon/contact_address.cloudcannon.inputs.yml'
_inputs___2___:
  contact_address:
    type: url
    options:
      hide_link_to_address___2___: true

```

**[1]** The main *Configuration File* references another *Configuration File*, `contact_address.cloudcannon.inputs.yml`, using `_inputs_from_glob`.

**[2]** The main *Configuration File* defines the `contact_address` Input inline. CloudCannon will not use this configuration as it is first in the import order.
```

File: `/.cloudcannon/contact_address.cloudcannon.inputs.yml'`

```YAML
```

_inputs:
  contact_address:
    type: url
    options:
      hide_link_to_address___3___: false

```

**[3]** The `contact_address.cloudcannon.inputs.yml` file also defines the `contact_address` Input inline. CloudCannon will use this configuration as it is last in the import order.
```

Additionally, if you define a conflicting object key in multiple *Configuration Files* referenced by a `*_from_glob` key, CloudCannon will preferentially use the configuration defined in files later in the import order. The order of files in your `*_from_glob` array does not affect import order.

File: `cloudcannon.config.yml`

```YAML
```

collections_config_from_glob___1___:
  - '/.cloudcannon/posts.cloudcannon.collections.yml'
  - '/.cloudcannon/blog.cloudcannon.collections.yml'

```

**[1]** The main *Configuration File* references two *Configuration Files* using `collections_config_from_glob`, `posts.cloudcannon.structures.yml` and `blog.cloudcannon.structures.yml`. However, both these *Configuration Files* define the same *Collection*, `content`.
```

File: `/.cloudcannon/posts.cloudcannon.collections.yml`

```YAML
```

content___2___:
  path: content
  icon: wysiwyg

```

**[2]** The `posts.cloudcannon.structures.yml` defines the `content` *Collection*. CloudCannon will use this configuration as it is last in the import order (`posts` is after `blog` in Unicode order).
```

File: `/.cloudcannon/blog.cloudcannon.collections.yml`

```YAML
```

content___3___:
  path: content
  icon: post_add

```

**[3]** The `blog.cloudcannon.structures.yml` also defines the `content` *Collection*. CloudCannon will not use this configuration as it is first in the import order (`posts` is after `blog` in Unicode order).
```


---

---
title: Delete a Custom Permission Group
description: Learn how to delete Custom Permission Groups from your Organization.
url: https://cloudcannon.com/documentation/developer-articles/delete-a-custom-permission-group/
content_type: developer article
last_modified: 2026-03-29
---

> **This feature is available on our [Team and Enterprise plans](/pricing/).**
> 
> Want to chat about whether this feature is right for you? Our support team is always [happy to hear from you](mailto:success@cloudcannon.com?subject=A%20question%20about%20custom%20Permission%20Groups).

To delete a custom [Permission Group](/documentation/user-articles/what-are-permission-groups/) from your [Organization](/documentation/user-articles/what-is-an-organization/):

1. Navigate to the *Team* page under *Org settings*.
2. Click on the *Groups* tab.
3. Under the *Groups* tab, click on the Permission Group you want to delete. This will open the *Permission Group* page.
4. Click the *Delete Group* button at the top right of the page.
5. Confirm that you want to delete this Permission Group by double clicking the *Delete Group* button in the confirmation modal.

![A screenshot of the Marketing Team Custom Permission Group page shows the Delete Group button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Team-Custom-Group-Members-Tab.webp)

Alternatively, you can delete a Group from the *Team* page by clicking on the *Context Menu* in the top right of a Group card and selecting *Delete Group*.

CloudCannon will delete this Permission Group, and all members will lose any permissions associated with the Group.

> Each team member in your Organization must be a member of at least one Permission Group. If you delete a team member's last Permission Group, this action will also remove them from your Organization.


---

---
title: Deprecated 301.txt Redirects
description: 301.txt redirects are deprecated, use routing.json to configure this with more options.
url: https://cloudcannon.com/documentation/developer-articles/deprecated-301-redirects/
content_type: developer article
last_modified: 2026-04-11
---

> This feature has been deprecated. It is highly recommended you update to use a [Routing file](/documentation/developer-articles/what-is-routing/).

301 redirects are inside the 301.txt file at the root of your built files. Redirects are specified using the following syntax:

`old-url new-url`

Redirect to external domains and wildcard matching with `*`. Here’s an example file:

File: `301.txt`

```
/about.html /about/
/category/* /new-category
/should-have-been-elsewhere/ https://example.com
```

Redirects will only occur if the redirect-from page/location no longer exists within the site. If the page/location still exists within your site, this will be served instead of performing a redirect.

> You can redirect to, but not from a URL fragment (e.g. #example-heading). The fragment is not passed to the server so, it cannot be processed by the redirect.

## Migrating to a Routing file

301.txt redirects still work to ensure backwards compatibility for older sites. Once a `.cloudcannon/routing.json` file has been added 301.txt will be ignored. 301.txt offers a subset of the options available in the Routing file. This feature will not be receiving any further improvements.

Upgrading will give access to the following improvements:

1. Regex redirects and regex parameters in the location
2. Redirects run before all other behaviour allowing easier configuration
3. More redirect status codes
4. Customise headers on existing routes
5. And more coming soon

For the above example, here is the equivalent:

File: `.cloudcannon/routing.json`

```json
{
  "routes": [
      {
        "from": "/about.html",
        "to": "/about/",
        "status": 301,
        "substitutions": false,
        "forced": false
      },
      {
        "from": "/category/*",
        "to": "/new-category",
        "status": 301,
        "substitutions": false,
        "forced": false
      },
      {
        "from": "/should-have-been-elsewhere/",
        "to": "https://example.com",
        "status": 301,
        "substitutions": false,
        "forced": false
      }
  ]
}
```


---

---
title: Detecting when your site is loaded in the Visual Editor
description: Learn how to show content to team members in the Visual Editor that is hidden on the live site.
url: https://cloudcannon.com/documentation/developer-articles/detecting-your-site-is-loaded-in-the-visual-editor/
content_type: developer article
last_modified: 2026-04-11
---

There may be situations where you want to show content to editors when they’re in the Visual Editor but not show it on the live site.

The Visual Editor adds the `.cms-editor-active` class to the `body` of the page. Use this to show elements that are hidden on the live site:

File: `styles.css`

```css
.editor-content {
  display: none;
}

.cms-editor-active .editor-content {
  display: block;
}
```

Alternatively, check `window.inEditorMode` with JavaScript to find out if a page is being viewed inside the Visual Editor:

File: `script.js`

```javascript
if (window.inEditorMode) {
  alert('Inside CloudCannon!');
} else {
  alert('Not in CloudCannon.');
}
```


---

---
title: Disable branch publishing
description: Learn how to disable branch publishing with CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/disable-branch-publishing/
content_type: developer article
last_modified: 2026-02-23
---

You can prevent a branched site from publishing content to another site. To disable publishing, disconnect the branched site from your publish site.

Navigate to the *Publishing* tab under *Site Settings* and click *Remove Publish Branch*. Click again to confirm.

![A screenshot of the Publishing page shows a connected Publish Branch with the Remove Publish Branch button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Publishing-Connected.webp)

Once your sites are disconnected, CloudCannon will remove the *Publish* button from the sidebar.


---

---
title: Disable CloudCannon window global in the Visual Editor
description: Learn how to disable the CloudCannon object injected onto the window in the Visual Editor.
url: https://cloudcannon.com/documentation/developer-articles/preventing-the-global-cloudcannon-live-editing-object/
content_type: developer article
last_modified: 2026-04-11
---

CloudCannon injects an object onto the window object when viewed in the Visual Editor. This article will show how to turn off this behaviour. This is helpful if you are using another global variable called `CloudCannon`.

To turn this off, we need to capture the `cloudcannon:load` event and call the `disableGlobalInstall` function.

```javascript
document.addEventListener('cloudcannon:load', function (e) {
  const { CloudCannon } = e.details;
  CloudCannon.disableGlobalInstall();
});
```


---

---
title: Disable output URL matching for a Collection
description: Learn how to disable output URL matching and turn off the Visual Editor or webpage screenshots for a Collection.
url: https://cloudcannon.com/documentation/developer-articles/disable-output-url-matching-for-a-collection/
content_type: developer article
last_modified: 2026-02-12
---

> **Permissions required**
> 
> Members of the Owners, Developers, and Technical Editors [Default Permission Groups](/documentation/articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/articles/what-are-custom-permission-groups/) with the `site:source-editor:write` and `site:file:write` permissions, can edit your *CloudCannon Configuration File*. You can limit permission to specific files using [file globs](https://cloudcannon.com/documentation/articles/what-are-custom-permission-groups/#specify-a-file-glob).

An output URL is the URL your SSG outputs your files to during a [Site build](/documentation/articles/what-is-a-site-build/). After each successful build, CloudCannon automatically determines the likely output URL to match an [output file](/documentation/articles/what-is-an-output-file/) to a source file, enabling the [Visual Editor](/documentation/articles/what-is-the-visual-editor/) and screenshots in the *Collection Browser*.

You can disable this behavior for any *Collection* if you do not want CloudCannon to attempt to match output files to source files. If you disable the output URL for a *Collection*, files from that *Collection* will not be visible in the [Visual Editor](/documentation/articles/what-is-the-visual-editor/), or have screenshots in the *Collection Browser*, even if you have a template string configured for the *Collection*.

These instructions assume you want to build your *Site*, and have already grouped your files into *Collections*.

To disable output URL matching for a *Collection*:

1. Navigate to the *Collection* for which you want to disable output URL matching.
2. Turn on *Configuration Mode* using the switch on the right of the *Site Header*. Purple *Edit Configuration* buttons will appear in the *Collection Browser*.
3. Click the *Edit Advanced* in the top right of the *Collection Browser*. CloudCannon will open the *Edit Advanced* data panel.
4. Identify the *Disable URL* checkbox and ensure it is ticked.
5. Save the change to your *Site*.

CloudCannon will stop matching output files to source files, and disable the *Visual Editor* and webpage screenshots for that *Collection*.

![A screenshot of the Collection Browser shows the Edit Advanced data panel open with a text field for URL configuration.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-Configuration-Mode-Edit-Advanced-URL.webp)

> The `disable_url` key does not determine whether your SSG will output a *Collection*.


---

---
title: Disconnect a Custom Domain from your Organization
description: Learn how to disconnect a Custom Domain from your Organization on CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/disconnect-a-custom-domain-from-your-organization/
content_type: developer article
last_modified: 2026-02-10
---

> **Permissions required**
> 
> Members of the Owners [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `base-domain:delete:write` permission, can disconnect Custom Domains from an Organization.

A Custom Domain is a unique address used to identify a website (e.g., [cloudcannon.com](https://cloudcannon.com/)). If you have [connected a Custom Domain to your Organization](/documentation/developer-articles/connect-a-custom-domain-to-your-organization/) and [added the Custom Domain to your Site](/documentation/developer-articles/add-a-custom-domain-to-your-site/), CloudCannon will host your website content at that web address.

Disconnecting a Custom Domain from your Organization will allow you to add the domain to a different CloudCannon Organization.

> Disconnecting a Custom Domain from your CloudCannon Organization does not delete your domain, or affect any of the settings managed by your Domain Registrar.

To protect you from accidentally taking your website down by disconnecting your Custom Domain, CloudCannon prevents you from disconnecting the domain from your Organization until you have removed it from all CloudCannon Sites.

These instructions assume you have already [removed the Custom Domain from all CloudCannon Sites](/documentation/developer-articles/remove-a-custom-domain-from-your-site/).

To disconnect a Custom Domain from your Organization:

1. Log in to CloudCannon and select the Organization from which you want to disconnect the Custom Domain.
2. Click the *Domains* button in the *App Sidebar*. CloudCannon will open the *Domains browser*.
3. Identify the domain you want to disconnect and click on the *Domain* card. CloudCannon will open the *Domain* page for this Custom Domain.
4. Navigate to the *Danger* section under the *Domain Settings* tab.
5. Click the *Disconnect Domain* button, and click again to confirm.

CloudCannon will disconnect the Custom Domain from your Organization.

![A screenshot of the Domain Settings tab on the Domain page shows the Disconnect Domain button and a warning notification.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Domain-Domain-Settings-Tab-Danger.webp)


---

---
title: Edit a Custom Permission Group
description: Learn how to edit Custom Permission Groups for your Organization, including how to add, delete, and edit permissions.
url: https://cloudcannon.com/documentation/developer-articles/edit-a-custom-permission-group/
content_type: developer article
last_modified: 2026-03-29
---

> **This feature is available on our [Team and Enterprise plans](/pricing/).**
> 
> Want to chat about whether this feature is right for you? Our support team is always [happy to hear from you](mailto:success@cloudcannon.com?subject=A%20question%20about%20custom%20Permission%20Groups).

## Add a permission or exception to a Custom Permission Group

To add a permission to an existing [Custom Permission Group](/documentation/developer-articles/what-are-custom-permission-groups/):

1. Navigate to the *Team* page under *Org settings*.
2. Click on the *Groups* tab.
3. Under the *Groups* tab, click on the Permission Group you want to delete. This will open the *Permission Group* page.
4. Click on the *Settings* tab.
5. Click on the *Add permission* or *Add exception* button to open the appropriate modal.
6. Select the scope using the *Scope* dropdown. If you select Base Domain, Group, Project, or Site, you must also choose the Target to that scope with the *Target* dropdown. Selecting a scope will automatically filter the resource tree.
7. Using the resource tree, select the resources you want to add and what actions you want to allow for each resource (i.e., Read, Write, or Create).
8. Click the *Add* button.
9. Once you are happy with the changes to your Permission Group, click the *Update group* button.

![A screenshot of the Marketing Team Permission Group page shows permissions and the Add Permission button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Team-Custom-Group-Settings-Tab.webp)

CloudCannon will add the new permission to your Custom Permission Group. All members of that group will automatically gain the new permission.

> Alternatively, you can add a new permission or exception by cloning an existing one. This method is more efficient when you need to create many similar permissions (e.g., several permissions with a Site scope targeting different Sites).
> 
> To clone a permission or exception, click on the *Context Menu* and select *Clone*. You can now edit the cloned item.

## Delete a permission or exception from a Custom Permission Group

To delete a permission from an existing [Custom Permission Group](/documentation/developer-articles/what-are-custom-permission-groups/):

1. Navigate to the *Team* page under *Org settings*.
2. Click on the *Groups* tab.
3. Under the *Groups* tab, click on the Permission Group you want to delete. This will open the *Permission Group* page.
4. Click on the *Settings* tab.
5. Identify the permission or exception you want to delete and click on the *Context Menu*.
6. Select *Delete* from the dropdown menu.
7. Once you are happy with the changes to your Permission Group, click the *Update group* button.

![A screenshot of the Marketing Team Permission Group page shows the context menu open on a permission card with Delete and Clone options.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Team-Custom-Group-Permission-Context-Menu.webp)

CloudCannon will delete the permission from your Custom Permission Group. All members of that group will automatically lose the permission.

## Edit a permission or exception in a Custom Permission Group

To edit a permission in an existing [Custom Permission Group](/documentation/developer-articles/what-are-custom-permission-groups/):

1. Navigate to the *Team* page under *Org settings*.
2. Click on the *Groups* tab.
3. Under the *Groups* tab, click on the Permission Group you want to delete. This will open the *Permission Group* page.
4. Click on the *Settings* tab.
5. Identify the permission or exception you want to edit and click on the card. This will open the *Edit permission/exception* modal.
6. Make your desired edits. If you alter the scope, CloudCannon will automatically filter the resource tree.
7. Click the *Update* button.
8. Once you are happy with the changes to your Permission Group, click the *Update group* button.

![A screenshot of the Edit permission modal shows the scope and resource tree for a Global permission with site:write.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Team-Edit-Permission-Modal.webp)

CloudCannon will update the permission in your Custom Permission Group. All members of that group will automatically gain the updated permission.


---

---
title: Edit a team member's Site Sharing Permission Group
description: Learn how to switch a team member's Permission Group for Site Sharing.
url: https://cloudcannon.com/documentation/developer-articles/edit-a-team-members-site-sharing-permission-group/
content_type: developer article
last_modified: 2026-03-29
---

There are two [Permission Groups](/documentation/user-articles/what-are-permission-groups/) available per Site for [Site Sharing](/documentation/user-articles/share-a-site-with-site-sharing/). These have identical permissions to the [Technical Editors](/documentation/user-articles/what-are-default-permission-groups/#technical-editors) and [Editors](/documentation/user-articles/what-are-default-permission-groups/#editors) Groups except with a Site scope. Site Sharing Permission Groups are named after the Site they provide access to.

> Members of the Owners or Developers [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/) can update a team member’s Site Sharing Permission Group. If you are using [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/), any member with permission to access the `group:member:write` or `site:settings:site-sharing:write` resources can update a member's Site Sharing Permission Groups.

To switch which Permission Group your team member belongs to:

1. Navigate to the *Site Sharing* page under *Site settings*.
2. Click on the member whose permissions you want to update. This will open the *Update team member Permission Group* modal.
3. Select the Permission Group to which you want to add the team member.
4. Click the *Update Group* button.

![A screenshot of the Edit Permission Group modal shows one field to select which Site Sharing Permission Group a team member belongs to.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Site-Sharing-Edit-Permission-Group-Modal.webp)


---

---
title: Edit SSO/SAML authentication
description: Learn how to edit the Single Sign-On authentication settings for your CloudCannon Organization.
url: https://cloudcannon.com/documentation/developer-articles/edit-sso-saml-authentication/
content_type: developer article
last_modified: 2026-04-11
---

> **This feature is available on our [Enterprise plan](/pricing/).**
> 
> Want to chat about whether this feature is right for you? Our support team is always [happy to hear from you](mailto:success@cloudcannon.com?subject=A%20question%20about%20SSO%2FSAML).

You can update the initial [Permission Group](/documentation/user-articles/what-are-permission-groups/) for SSO users and your X.509 Certificate at any time.

To edit your [SSO/SAML](/documentation/developer-articles/what-is-sso-saml/) settings:

1. Navigate to the *Single Sign-On* page under *Org settings*.
2. Click on the *Settings* tab.
3. Edit your settings.
4. Click the *Update SAML Configuration* button.


---

---
title: Editing markdown in the Visual Editor
description: Learn how to edit your markdown files as they would appear on your live site, with CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/editing-markdown-files-in-the-visual-editor/
content_type: developer article
last_modified: 2026-04-11
---

> Since October 2025, this method of visual editing has been deprecated. CloudCannon cannot guarantee support for this feature. Please consider using [Editable Regions](/documentation/developer-articles/what-are-editable-regions/) or Bookshop.

You can edit markdown files in the Visual Editor using an in-place Rich Text editor embedded on your page.

To do so, add the `data-cms-edit="content"` attribute to the relevant element on your site. For example:

File: `page.html`

```html
<div data-cms-edit="content">
  {{ content }}
</div>
```

When encountering this attribute, CloudCannon will replace the children of the tagged element with the Content Editor, connected to the Markdown content of the opened file.


---

---
title: Enable Git LFS
description: Learn how to enable Git LFS to store large files outside your repository for faster syncs and builds in CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/enable-git-lfs/
content_type: developer article
last_modified: 2026-04-11
---

[Git Large File Storage](https://git-lfs.github.com/) (Git LFS) enables you to store large files outside of your Git repository, but continue to access them as if they were within the repository. Enabling Git LFS is a great way to maintain a smaller repository size for faster syncing and building.

> A great way to use Git LFS is to track your uploads path, so new asset files in the editor are stored there. Running `git lfs track "uploads/**"` tracks all files inside of the `/uploads` folder.

Setting up Git LFS is a two part process:

1. Install Git LFS
2. Enable Git LFS in your CloudCannon Site Settings

To install Git LFS, follow the installation guide on the [Git Large File Storage website](https://git-lfs.github.com/). Alternatively, you can use the instructions provided by [Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/use-git-lfs-with-bitbucket/), [GitHub](https://docs.github.com/en/repositories/working-with-files/managing-large-files/installing-git-large-file-storage), or [GitLab](https://docs.gitlab.com/ee/topics/git/lfs/).

To enable Git LFS for your Site:

1. Navigate to the *Syncing* page under *Site Settings*.
2. Check the *Enable Git LFS* checkbox under *Additional Settings*.
3. Click the *Update Settings* button.

You have enabled Git LFS on CloudCannon.

> CloudCannon will prompt you to check the *Enable Git LFS* option in your Site Settings if it detects you have a `.gitattributes` file in your repository. This warning will appear in the *Needs Attention* section on your *Status* page.


---

---
title: Enable Headless Mode
description: Learn how to enable Headless Mode on your CloudCannon Site to disable hosting and builds.
url: https://cloudcannon.com/documentation/developer-articles/enable-headless-mode/
content_type: developer article
last_modified: 2026-04-11
---

> Headless Mode is only available for Sites using Unified Configuration. For more information, please read our [Unified Configuration migration guide](/documentation/developer-guides/unified-configuration-migration-guide/).

Headless Mode disables hosting and building for your Site.

To enable Headless Mode on your Site:

1. Navigate to the *Details* page under *Site Settings*.
2. Select the *Headless* option under *Mode*.
3. Click the *Update Site* button.
4. Click the *Turn off hosting and builds* button on the confirmation modal.

CloudCannon will immediately take down your live Site and prevents any further builds.

![A screenshot of the Details page shows the Mode field with radio buttons for Hosted and Headless.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Details.webp)

When your Site is in Headless Mode, CloudCannon will display a reduced set of pages in your *Site Settings*.

You can turn off *Headless Mode* at any time by selecting *Hosted* on the *Details* page under your *Site Settings*.


---

---
title: Enable multi-factor authentication
description: Learn how to enable multi-factor authentication in CloudCannon using a third-party authentication app.
url: https://cloudcannon.com/documentation/developer-articles/enable-multi-factor-authentication/
content_type: developer article
last_modified: 2026-04-07
---

These instructions assume that you have a third-party authentication app. For more information, please read our documentation on [multi-factor authentication](/documentation/user-articles/what-is-multi-factor-authentication/).

> You cannot disable this feature once you enable MFA for your CloudCannon account. For more information about MFA, please contact our [support team](/support/).

![A screenshot of the multi-factor authentication page with the option to enable MFA.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Multifactor-Authentication-Settings.webp)

To enable multi-factor authentication:

1. Log in to CloudCannon.
2. Navigate to the *Multi-factor Authentication* page under *Account Settings.*
3. Click the *Enable multi-factor authentication* button.
4. Scan the QR code with your third-party authentication app and follow the setup instructions.
5. Enter the authentication app passcode into CloudCannon. (Note: this code is time-sensitive and will regenerate often.)
6. Click the *Verify* button.
7. CloudCannon will generate sixteen recovery codes for your account. Copy these recovery codes and store them in a secure location.
8. Click the *I have saved my recovery codes* button. If you cancel or click away from this modal before clicking this button, CloudCannon will not enable MFA for your account. You must explicitly agree that you have saved your recovery codes.

You have enabled multi-factor authentication for your CloudCannon account.

![A screenshot of the multi-factor authentication screen, showing the MFA setup modal with a QR code for your third-party authentication app.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-MFA-Setup-QR-Code.webp)

![A screenshot of the multi-factor authentication screen, showing the MFA setup modal with a list of recovery codes.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-MFA-Setup-Recovery-Codes.webp)

![A screenshot of the multi-factor authentication screen, showing the 'Edit multi-factor authentication' and 'Generate new recovery codes' buttons.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Multifactor-Authentication-Page.webp)

With multi-factor authentication enabled, CloudCannon will prompt you to enter a one-time passcode from your third-party authentication app each time you log in. These passcodes are unique and time-sensitive, regenerating often (normally every thirty seconds).

![A screenshot of the CloudCannon login screen, showing a prompt to enter your six digit MFA passcode for an authentication app.](assets/onboarding_screenshots/CloudCannon-Documentation-Login-MFA-Passcode.png)

If you cannot access your device or authentication app, you can use one of your recovery codes to log in.

![A screenshot of the CloudCannon login screen, showing a prompt to enter your recovery code.](assets/onboarding_screenshots/CloudCannon-Documentation-Login-MFA-Recovery-Code.png)


---

---
title: Enable or disable a flag
description: Learn about flags in CloudCannon and how you can use them to opt into app behavior.
url: https://cloudcannon.com/documentation/developer-articles/enable-or-disable-a-flag/
content_type: developer article
last_modified: 2026-02-10
---

> Flags can be tricky. If you need assistance, please don't hesitate to contact our friendly [support team](/support/).

To enable or disable a flag:

1. Navigate to the *Flags* page under *Site Settings*.
2. Identify the flag and use the checkbox to enable or disable the flag.
3. Click the *Update* button.

![A screenshot of the Flags page in your Site Settings shows three checkboxes for enabling opt-in behavior in CloudCannon.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Flags-Page.webp)

For more information about specific flags in CloudCannon, please read their dedicated documentation:

- [General Flags](/documentation/developer-articles/general-flags/)
- [Unified Configuration Flags](/documentation/developer-articles/unified-configuration-flags/)
- [Input Naming Convention Flags](/documentation/developer-articles/input-naming-convention-flags/)
- [Legacy Option Flags](/documentation/developer-articles/legacy-option-flags/)


---

---
title: Enable password authentication
description: Learn how to enable password authentication and require a password to visit your Site.
url: https://cloudcannon.com/documentation/developer-articles/enable-password-authentication/
content_type: developer article
last_modified: 2026-04-03
---

> This feature is only available for Sites [hosted through CloudCannon](/documentation/user-articles/what-is-web-hosting/#hosting-on-cloud-cannon). If you host your Site externally, or use CloudCannon in [Headless Mode](/documentation/developer-articles/what-is-headless-mode/), this feature will not work.

Password authentication requires visitors to your Site to enter a password before they can view any content.

By default, CloudCannon serves a simple Login page when a visitor requests your URL.

![A screenshot of the default Login page for a Site with Password Authentication enabled.](assets/onboarding_screenshots/CloudCannon-Documentation-Password-Authentication-Login-Page.png)

To enable password authentication for your Site:

1. Navigate to the *Authentication* page under *Site Settings*.
2. Click on the *Authentication method* dropdown and select the *Password* option.
3. Click the *Switch to Password authentication* button to confirm your choice.
4. Add the password of your choice in the *Site Password* text field.
5. Click the *Update Site Password* button.

CloudCannon will now require visitors to your Site to enter this password to see its content.

![A screenshot of the Authentication page shows the Switch to Password authentication button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Authentication-Password-Switch-Prompt.webp)

![A screenshot of the Authentication page shows a this Site has a password set.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Authentication-Password-Success.webp)

> If you enable Password Authentication without setting a password, visitors will not be able to access your content. You can resolve this by setting a password or turning off Password Authentication.

CloudCannon will warn you if you have enabled Password Authentication but have not set a password. CloudCannon will also show an Invalid Authentication warning on your live Site.

![A screenshot of the Site Password Warning on the Authentication page.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Authentication-Password-Warning.webp)

![A screenshot of the Misconfigured Password Page shows a warning when you attempt to access a Site with no password set.](assets/onboarding_screenshots/CloudCannon-Documentation-Password-Authentication-No-Password.png)

You can change the password for your Site at any time by entering a new password in the *Site Password* text field and clicking the *Update Site Password* button.

To disable password authentication, click on the *Authentication method* dropdown,  select the *None* option, and then click the *Switch to no authentication* button to confirm your choice.

CloudCannon uses cookies to determine whether a visitor is logged in (i.e., authenticated). Visitors can log out using the log-out link. For more information, please read our documentation on [allowing authenticated users to log out](/documentation/developer-articles/allow-authenticated-users-to-log-out/).

## Configure a custom login page

You can customize the login page for your website by creating a `login.html` file. This file should be in the root directory of your output Site. Where this is in your Site repository will depend on your SSG (e.g., the root of the repository for Jekyll, the static folder for Hugo, etc.).

You can customize the `login.html` file to match your Site branding and provide helpful resources.

This page requires:

- A form input for `password`.
- A hidden from input for `username`.
- A `submit` input.

In the `login.html` file, CloudCannon requires a `<form>` element with the liquid variable `class="{{messageClasses}}"`. CloudCannon injects a class into the `{{messageClasses}}` liquid variable to change the content on the page as the user submits the form.

> On Jekyll-generated pages, please add `raw` tags so Jekyll outputs the liquid variable correctly: `{% raw %}{{messageClasses}}{% endraw %}`.

You can add custom message classes to communicate with your users when using your forms, such as error-handling messages and success notifications. CloudCannon highly recommends adding a `has-incorrect-login` message class.

- The `has-incorrect-login` message class warns visitors when they enter incorrect login details.

A form action is not required for this page.

Here is an example of a basic login page:

File: `login.html`

```html

<!DOCTYPE html>

<html>
  <head>
    <title>Log in</title>
    <style>
      .incorrect-login-message {
        display: none;
      }

      .has-incorrect-login .incorrect-login-message {
        display: block;
      }
    </style>
  </head>
  <body>
    <h1>Log in</h1>

    <form action="" method="post" class="{{messageClasses}}">
      <div class="incorrect-login-message">
        Incorrect password.
      </div>

      <label for="password">Password</label>
      <input id="password" type="password" name="password" autofocus>

      <input type="hidden" name="username" value="user">

      <input type="submit" value="Log in">
    </form>
  </body>
</html>

```

> You may already have a `login.html` file if you are switching from [user account authentication](/documentation/developer-articles/enable-user-account-authentication/) to password authentication. Make sure to update the contents of this file.


---

---
title: Enable SAML authentication
description: Learn how to enable SAML authentication for your Site and require visitors to log in using a third-party login service.
url: https://cloudcannon.com/documentation/developer-articles/enable-saml-authentication/
content_type: developer article
last_modified: 2026-03-29
---

> **This feature is available on our [Enterprise plan](/pricing/).**
> 
> Want to chat about whether this feature is right for you? Our support team is always [happy to hear from you](mailto:success@cloudcannon.com?subject=A%20question%20about%20SSO%2FSAML).
> 
> This feature is only available for Sites [hosted through CloudCannon](/documentation/user-articles/what-is-web-hosting/#hosting-on-cloud-cannon). If you host your Site externally, or use CloudCannon in [Headless Mode](/documentation/developer-articles/what-is-headless-mode/), this feature will not work.

Security Assertion Markup Language (SAML) authentication requires visitors to your Site to log in with a third-party Single Sign-On ([SSO](/documentation/developer-articles/what-is-sso-saml/)) account. SSO/SAML provides a way to authenticate a visitor's identity through an external application and communicate that authentication to your Site hosted on CloudCannon.

We recommend SAML authentication for websites primarily used by internal teams.

> To enable SAML authentication for your Site you must have a SAML certificate from an Identity Provider of your choice (e.g., Google sign in). Visitors to your Site must have an account with your Identity Provider to access your content.

To enable user account authentication for your Site:

1. Navigate to the *Authentication* page under *Site Settings*.
2. Click on the *Authentication method* dropdown and select the *SAML* option.
3. Click the *Switch to SAML authentication* button to confirm your choice.
4. Enter your SAML certificate details in the text fields for *SAML 2.0 Endpoint (HTTP)*, *Issuer Suffix*, and *X.509 Certificate*. Alternatively, you can add your certificate details automatically by clicking the *Fill cert using XML Metadata* button and uploading the XML file from your Identity Provider.
5. Click the *Update SAML Configuration* button.

CloudCannon will redirect visitors to your SSO login page.

![A screenshot of the Authentication page shows fields for SAML 2.0 Endpoint (HTTP), Issuer Suffix , and X.509 Certificate.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Authentication-SAML-Empty.webp)

To disable SAML authentication, click on the *Authentication method* dropdown, select the *None* option, and then click the *Switch to no authentication* button to confirm your choice.

CloudCannon uses cookies to determine whether a visitor is logged in (i.e., authenticated). Visitors can log out using the log-out link. For more information, please read our documentation on [allowing authenticated users to log out](/documentation/developer-articles/allow-authenticated-users-to-log-out/).


---

---
title: Enable user account authentication
description: Learn how to enable user account authentication for your Site and restrict access to a list of invited users.
url: https://cloudcannon.com/documentation/developer-articles/enable-user-account-authentication/
content_type: developer article
last_modified: 2026-04-03
---

> This feature is only available for Sites [hosted through CloudCannon](/documentation/user-articles/what-is-web-hosting/#hosting-on-cloud-cannon). If you host your Site externally, or use CloudCannon in [Headless Mode](/documentation/developer-articles/what-is-headless-mode/), this feature will not work.

User account authentication allows you to specify a list of email addresses that can log in to view your website content.

By default, CloudCannon serves a simple Login page when a visitor requests your URL.

![A screenshot of the Site Login Page shows fields for email address and password to log in to a user account authenticated Site.](assets/onboarding_screenshots/CloudCannon-Documentation-Account-Authentication-Login-Page.png)

To enable user account authentication for your Site:

1. Navigate to the *Authentication* page under *Site Settings*.
2. Click on the *Authentication method* dropdown and select the *Accounts* option.
3. Click the *Switch to Account authentication* button to confirm your choice.
4. For each user you want to access your Site, enter their email address in the *Email Address* text field and click the *Add User* button.

CloudCannon will email each user and prompt them to create a personal password for your Site. If a user forgets their password, they can reset it using their email address.

![A screenshot of the Authentication page shows a text field where you can enter the email address of the person you want to invite.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Authentication-Account-Enter-Email.webp)

![A screenshot of the Authentication page shows a card for each user you have invited to your Site.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Authentication-Account-Success.webp)

Once a user has set their personal password for your Site, CloudCannon will update the authenticated users list.

![A screenshot of the Authenticated User Card on the Authentication page shows that hello@cloudcannon is invited and has set a password.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Authentication-Account-User-Card.webp)

You can remove users at any time by clicking the *Remove* button next to their email address.

To disable user account authentication, click the *Authentication method* dropdown, select the *None* option, and then click the *Switch to no authentication* button to confirm your choice.

CloudCannon uses cookies to determine whether a visitor is logged in (i.e., authenticated). Visitors can log out using the log-out link. For more information, please read our documentation on [allowing authenticated users to log out](/documentation/developer-articles/allow-authenticated-users-to-log-out/).

## Configure custom login pages

You can customize the login pages for your website by creating the `login.html`, `set-password.html`, and `reset-password.html` files. These files should be in the root directory of your output Site. Where this is in your Site repository will depend on your SSG (e.g., the root of the repository for Jekyll, the static folder for Hugo, etc.).

You can customize these HTML files to match your Site branding and provide helpful resources.

In each file, CloudCannon requires a `<form>` element with the liquid variable `class="{{messageClasses}}"`. CloudCannon injects a class into the `{{messageClasses}}` liquid variable to change the content on the page as the user submits the form.

You can add custom message classes to communicate to your users when they use your forms, such as error-handling messages and success notifications. CloudCannon highly recommends specific message classes, which are detailed in the sections below.

> On Jekyll-generated pages, please add `raw` tags so Jekyll outputs the liquid variable correctly: `{% raw %}{{messageClasses}}{% endraw %}`.

### Login page

The login page allows visitors to your Site to enter an email and password to view your content. This page must be named `login.html`.

This page requires:

- Form inputs for `email` and `password`.
- A `submit` input.
- A link to the reset password page.

We also highly recommend using the message class `has-incorrect-login` to communicate to visitors when they have entered incorrect login details.  A form action is not required for this page.

Here is an example of a basic login page:

File: `login.html`

```html

<!DOCTYPE html>

<html>
  <head>
    <title>Log in</title>
    <style>
      .incorrect-login-message {
        display: none;
      }

      .has-incorrect-login .incorrect-login-message {
        display: block;
      }
    </style>
  </head>
  <body>
    <h1>Log in</h1>

    <form action="" method="post" class="{{messageClasses}}">
      <div class="incorrect-login-message">
        Incorrect email address or password.
      </div>

      <label for="email">Email Address</label>
      <input id="email" type="email" name="email" autofocus>

      <label for="password">Password</label>
      <input id="password" type="password" name="password">

      <input type="submit" value="Log in">
    </form>

    <a href="/reset-password">Forgot your password?</a>
  </body>
</html>

```

> You may already have a `login.html` file if you are switching from [password authentication](/documentation/developer-articles/enable-password-authentication/) to user account authentication. Make sure to update the contents of this file.

### Set Password page

The set password page allows visitors to set a personal password to log in to your Site. CloudCannon will email a link to this page to each user when you add them to your invited users list. Visitors can also access this page when they request a password reset. This page must be named `set-password.html`.

This page requires:

- Form inputs for `password` and `password-confirm`.
- A hidden form input for `token`.
- A `submit` input.
- The `/set-password` form action.

There are several message classes we recommend for this page: `has-password-mismatch`, `has-invalid-link`, `has-token-expired`, and `has-success`.

- The `has-password-mismatch` message class warns the user when the text in the password and password confirmation fields does not match.
- The `has-invalid-link` and `has-token-expired` message classes warn the user when their reset password link is invalid or expired.
- The `has-success` message class tells the user when they have successfully set a password.

Here is an example of a basic set password page:

File: `set-password.html`

```html

<!DOCTYPE html>

<html>
  <head>
    <title>Set Password</title>
    <style>
      .password-mismatch-message,
      .invalid-link-message,
      .token-expired-message,
      .success-message {
        display: none;
      }

      .has-password-mismatch .password-mismatch-message,
      .has-invalid-link .invalid-link-message,
      .has-token-expired .token-expired-message,
      .has-success .success-message {
        display: block;
      }

      .has-success label,
      .has-success input {
        display: none;
      }
    </style>
  </head>
  <body class="{{messageClasses}}">
    <h1>Set Password</h1>
    <form action="/set-password" method="post">
      <div class="password-mismatch-message">
        Password did not match confirmation.
      </div>
      <div class="invalid-link-message">
        Your reset link is no longer valid.
        <a href="/reset-password">Reset your password</a> to get another.
      </div>
      <div class="token-expired-message">
        Your reset link has expired.
        <a href="/reset-password">Reset your password</a> to get another.
      </div>
      <div class="success-message">
        Successfully set your password.
      </div>

      <label for="password">Password</label>
      <input id="password" type="password" name="password" autofocus>

      <label for="password-confirm">Confirm Password</label>
      <input id="password-confirm" type="password" name="password-confirm">

      <input type="hidden" name="token" value="{{token}}">

      <input type="submit" value="Set Password">
    </form>
  </body>
</html>

```

### Reset Password page

The reset password page allows visitors to reset their personal login password by entering an invited email address. CloudCannon will email a link to the set password page. This page must be named `reset-password.html`.

This page requires:

- A form input for `email`.
- A `submit` input.
- The `/reset-password` form action.

We highly recommend adding the `has-no-email` and `has-success` message classes.

- The `has-no-email` message class warns the user when they have
- The `has-success` message class tells the user when they have successfully entered their email to receive a reset link.

Here is an example of a basic reset password page:

File: `reset-password.html`

```html

<!DOCTYPE html>

<html>
  <head>
    <title>Reset Password</title>
    <style>
      .no-email-message,
      .success-message {
        display: none;
      }

      .has-success .success-message,
      .has-no-email .no-email-message {
        display: block;
      }
    </style>
  </head>
  <body>
    <h1>Reset Password</h1>

    <form action="/reset-password" method="post" class="{{messageClasses}}">
      <div class="no-email-message">
        You must provide an email address.
      </div>
      <div class="success-message">
        We've sent you an email with instructions to reset your password.
      </div>

      <label for="email">Email Address</label>
      <input id="email" type="email" name="email" autofocus>

      <input type="submit" value="Reset Password">
    </form>
  </body>
</html>

```


---

---
title: Enforce multi-factor authentication
description: Learn how to enforce multi-factor authentication for your CloudCannon Organization.
url: https://cloudcannon.com/documentation/developer-articles/enforce-multi-factor-authentication/
content_type: developer article
last_modified: 2026-03-31
---

> **This feature is available on our Enterprise plan.**
> 
> This feature is available to customers on our [Enterprise plan](/pricing/). Want to chat about whether this feature is right for you? Our support team is always [happy to hear from you](mailto:success@cloudcannon.com?subject=A%20question%20about%20enforced%20MFA).

Requiring your [team members](/documentation/user-articles/what-is-a-team-member/) to use [multi-factor authentication](/documentation/user-articles/what-is-multi-factor-authentication/) on CloudCannon can add an extra layer of security to your [Organization](/documentation/user-articles/what-is-an-organization/).

Only members of the Owners [Permission Group](/documentation/user-articles/what-are-permission-groups/) can enforce multi-factor authentication for an Organization.

![A screenshot of the Multi-factor Authentication page shows a checkbox and date field for enforcing MFA.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Multi-Factor-Authentication-Page.webp)

To enforce multi-factor authentication for your CloudCannon Organization:

1. Log in to CloudCannon.
2. Navigate to the *Multi-factor Authentication* page under *Org Settings.*
3. Check the *Require multi-factor authentication (MFA)* check box.
4. Enter the date after which CloudCannon will require multi-factor authentication to view your Organization.
5. Click the *Update* button.

After the specified date, CloudCannon will require team members in your Organization to have [multi-factor authentication enabled](/documentation/developer-articles/enable-multi-factor-authentication/) to view your Organization and Sites. You can update the date and disable enforced multi-factor authentication at any time.

As the date approaches, your team members will see a warning banner, informing them that your Organization will soon require multi-factor authentication.

![A screenshot of the MFA Required Warning Banner, warning users that they must enable MFA to retain access to this Organization.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-MFA-Warning-Banner.webp)

If a team member has not enabled multi-factor authentication before that date, they can log in to CloudCannon but cannot access your Organization.

![A screenshot of the Organizations page shows that access to an Organization is prevented because MFA is required.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Organizations-Page-MFA-Required.webp)

![A screenshot of the MFA Required page shows that you cannot access an Organization until you enable MFA for your account.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-MFA-Required-Screen.webp)

A team member can restore access to your Organization by [enabling multi-factor authentication](/documentation/developer-articles/enable-multi-factor-authentication/) on their CloudCannon account.

You can view which team members have multi-factor authentication enabled on the *Team* page under *Org Settings*.

![A screenshot of the Team page shows which team members have enabled MFA.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-MFA-Enabled-Team-Page.webp)


---

---
title: Extending your build process with hooks
description: Learn how to run Preinstall, Prebuild, and PostBuild scripts to extend your build process in CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/extending-your-build-process-with-hooks/
content_type: developer article
last_modified: 2026-04-11
---

Bash scripts that run at different stages in the build to extend the functionality of your sites. There are three hooks available: Preinstall, Prebuild, and PostBuild. All three are configured using extensionless script files.

To run a hook script:

1. Create one of the named files in the `.cloudcannon` folder at the root of your file structure
2. Enter the commands you want to run at the specified step

### Preinstall

A script at `/.cloudcannon/preinstall` which runs after the files are available and before any install scripts.

Preinstall scripts are useful for configuring your install commands before they run.

### Prebuild

A script at `/.cloudcannon/prebuild` which runs after the install scripts and before any build commands.

Prebuild commands allow you to incorporate your favourite tools for building and pre-processing into CloudCannon. Some ideas for using this feature include:

- Bundling JavaScript
- Fetching API data
- Running build commands outside of your SSG
- Sending messages to your Slack channel

Here’s an example file that bundles JavaScript files using webpack:

File: `/.cloudcannon/prebuild`

```shell
#!/bin/bash

npm install webpack
npm install webpack-cli

./node_modules/.bin/webpack path/to/entry.js -o js/output.js
```

### Postbuild

A script at `/.cloudcannon/postbuild` which runs after your build is completed successfully before the files are uploaded to CloudCannon servers.

Postbuild scripts are useful for augmenting your built output or running postbuild webhooks.

> If your `postbuild` script adds, removes or updates files used by the editor, your editing experience may be compromised.


---

---
title: General Flags
description: Learn about the general flags and how they might affect your Site.
url: https://cloudcannon.com/documentation/developer-articles/general-flags/
content_type: developer article
last_modified: 2026-04-11
---

## Disable setup prompts

During the onboarding and Site creation process, CloudCannon will guide you using setup prompts in your *Site Navigation*. By default, these prompts disappear from the *Site Navigation* once you have completed you Site setup, but they can return if CloudCannon detects your Site no longer has the minimum recommended configuration (e.g., you delete your [CloudCannon configuration file](/documentation/developer-articles/what-is-the-cloudcannon-configuration-file/)).

You can disable these prompts by checking the *Disable setup prompts* flag on the *Flags* page of your Site, under *Site Settings*.

If you disable this flag, CloudCannon will not be able to warn you about incomplete setup in your *Site Navigation*. Instead you can find these warnings under the *Needs attention* section on your *Status* page.


---

---
title: Generate a bearer token
description: Learn about bearer tokens and how to generate them for your Site.
url: https://cloudcannon.com/documentation/developer-articles/generate-a-bearer-token/
content_type: developer article
last_modified: 2026-03-29
---

> This feature is only available for Sites [hosted through CloudCannon](/documentation/user-articles/what-is-web-hosting/#hosting-on-cloud-cannon). If you host your Site externally, or use CloudCannon in [Headless Mode](/documentation/developer-articles/what-is-headless-mode/), this feature will not work.

A bearer token is an alphanumeric string that allows trusted third-party applications (i.e., APIs) to circumvent authentication and access protected content. An application must pass the correct token in an HTTP Authorization header for CloudCannon to allow it to access your Site.

Here is an example bearer token and the Authorization header for a third-party application:

`Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`

File: `shell`

```shell

curl -H "Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" https://example.com/products.json

```

To generate a bearer token for your Site:

1. Navigate to the *Bearer Token* page under *Site Settings*.
2. Enter the name of your bearer token in the *Name* text field under *Create Token*. We recommend choosing a name that indicates which application will use the token.
3. Click the *Generate Bearer Token* button to generate a token. CloudCannon will open the *New token* modal.
4. Copy your bearer token from the modal and store it somewhere safe.
5. Click the *OK, I've copied it* button.

![A screenshot of the Bearer Token page under Site Settings shows the Name text field and the Generate Bearer Token button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Bearer-Tokens-None.webp)

![A screenshot of the Bearer Token page under Site Settings shows the New Token modal with a bearer token in the text field.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Bearer-Tokens-Popup.webp)

![A screenshot of the Bearer Token page under Site Settings shows one bearer token has been generated for this Site.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Bearer-Tokens-Success.webp)

You can remove a bearer token at any time by clicking the *Remove* button and clicking again to confirm. Applications using that bearer token will no longer be able to access your Site.


---

---
title: Including git folder in your build
description: Include your site's .git folder in the build procecss
url: https://cloudcannon.com/documentation/developer-articles/including-git-folder-in-your-build/
content_type: developer article
last_modified: 2026-04-11
---

By default, CloudCannon will not include your `.git` directory in the build process.

If your site relies on information from your `.git` folder, you can use the **Include Git Folder** option.

1. Navigate to *Site Settings* / *Build*.
2. Open the *Advanced Options* menu.
3. Check *Include Git Folder* option.
4. Click the *Update Configuration* button at the bottom of the page.


---

---
title: Input Naming Convention Flags
description: Learn about the input naming convention flags and how they might affect your Select inputs and Structures.
url: https://cloudcannon.com/documentation/developer-articles/input-naming-convention-flags/
content_type: developer article
last_modified: 2026-04-11
---

> As of October 2024, CloudCannon's input naming convention behavior changed for all new Sites and Sites using Unified Configuration. For more information, please read out guide on [migrating to Unified Configuration](/documentation/developer-guides/unified-configuration-migration-guide/) or contact our friendly [support team](/support/).

In older versions of CloudCannon, you could define which [Collections](/documentation/user-articles/what-is-a-collection/) or [data sets](/documentation/developer-articles/define-your-data/) populated a [Select input](/documentation/user-articles/what-is-a-select-input/) or which [Structures](/documentation/developer-articles/what-is-a-structure/) populated an [Object input](/documentation/user-articles/what-is-an-object-input/) or [Array input](/documentation/user-articles/what-is-an-array-input/) using a naming convention.

Sites using Unified Configuration may require you to configure this behavior rather than rely on the naming convention for CloudCannon to detect what should populate an input.

## Infer Select values from input key

The *Infer Select values from input key* flag controls whether CloudCannon uses the input naming convention to determine which Collections or data sets should populate a Select or Multiselect input.

This convention involved naming the input the singular noun of a Collection or data set name. For example, an unconfigured input named `author` will automatically become a Select input referencing a Collection named `authors`.

CloudCannon no longer uses this behavior by default. New Sites created after October 2024 and sites using Unified Configuration do not have this flag enabled. You can enable this behavior by checking the *Infer Select values from input key* flag on the *Flags* page of your Site, under *Site Settings*.

## Infer Structure values from input key

The *Infer Structure from input key* flag controls whether CloudCannon uses the input naming convention to determine which Structures should populate an Object or Array input.

This convention involved naming the Structure the same as an input. For example, an unconfigured input named `content_blocks` will automatically become an array of the structure named `content_blocks`.

CloudCannon enables this behavior by default to support older Site configurations. You can disable this behavior by checking the *Infer Structure from input key* flag on the *Flags* page of your Site, under *Site Settings*.


---

---
title: Integrating your DAM with CloudCannon
description: Learn how to connect your DAM to your sites in CloudCannon
url: https://cloudcannon.com/documentation/developer-articles/integrating-your-dam-with-cloudcannon/
content_type: developer article
last_modified: 2026-04-11
---

Learn how to connect your DAM to your sites in CloudCannon.

For information on setting up a DAM with a specific provider, read one of our guides below:

- [Creating a Cloudinary DAM](/documentation/developer-articles/creating-a-cloudinary-dam/)
- [Creating an S3 DAM](/documentation/developer-articles/creating-an-s3-dam/)
- [Creating a Cloudflare R2 DAM](/documentation/developer-articles/creating-a-cloudflare-r2-dam/)
- [Creating a DigitalOcean Spaces DAM](/documentation/developer-articles/creating-a-digitalocean-spaces-dam/)
- [Creating a Tenovos DAM](/documentation/developer-articles/creating-a-tenovos-dam/)
- [Creating an Azure Blob Storage DAM](/documentation/developer-articles/creating-an-azure-dam/)
- [Creating a Google Cloud Storage DAM](/documentation/developer-articles/creating-a-google-cloud-storage-dam/)

### Authenticating your DAM

To connect your DAM to your sites, you must first authenticate the DAM with your organisation.

1. In your Organisation settings, navigate to *Files* / *Assets*
2. Click **Authenticate a new DAM**
3. Select your provider from the dropdown, then fill out the relevant fields. Check your provider's documentation to see where you can find the relevant values
4. Click **Authenticate**.

You will then be able to manage your DAM within the scope of your organisation. To check the authentication went correctly:

1. In your Organisation settings, navigate to *Files* / *Assets*
2. Locate the relevant DAM, and click the **Manage** button next to its name
3. In the **Configuration tab**, click the **Open preview** button.

If your DAM successfully authenticated, a modal will open that will let your browse the files in your DAM. If something goes wrong, you may have entered your details incorrectly. Read below to learn how to configure an existing DAM with CloudCannon.

### Linking your DAM to a site in CloudCannon

Once you have authenticated your DAM with your CloudCannon organisation, you can then link it to any number of your sites.

To link a site:

1. Open your site in the CloudCannon app
2. In your site's settings, navigate to *Files* / *Assets*
3. In the box labelled *Link DAM*, select your authenticated DAM from the dropdown
4. Click **Link DAM**

![Screenshot of DAMs linked to a site in CloudCannon](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Assets-No-Linked-DAMs.webp)

> You can prevent choosing existing files from and uploads to your site/repository files in the *Site Settings / Details* section.


---

---
title: Integrating your forms with email
description: Receive your form submissions by email.
url: https://cloudcannon.com/documentation/developer-articles/integrating-your-forms-with-email/
content_type: developer article
last_modified: 2026-04-11
---

You can choose to forward submissions from your CloudCannon forms to your email address by using the email Inbox target.

To create an email target:

1. Navigate to the forms menu in your Organization settings, under *Hosting > Forms.*
2. Open your Inbox settings by clicking the *Manage* button on the Inbox you want to receive email from.
3. Open the *Add new target* menu, and set the *Type* to *Email.*
4. Set the *Target* to the email address to send submissions to, then click *Add Inbox target*.

At this point, you should receive a validation link at that email address. Once you click that link, the target will be validated and begin receiving form submission emails.

### Special Fields

Use these fields to customize the email CloudCannon sends through the form. The fields can be hidden or visible, depending on your requirements.

`_replyto` — the value used for the Reply-To header in the email. Use this to ensure clients reply to the visitor rather than a default CloudCannon address.

File: `contact.html`

```html
<label>
  Your Email Address
  <input type="text" name="_replyto">
</label>
```

`_subject` — the subject of the email.

File: `contact.html`

```html
<select name="_subject">
  <option>General Enquiry</option>
  <option>Quote Request</option>
  <option>Support</option>
</select>
```


---

---
title: Integrating your forms with IFTTT
description: Process your form submissions with IFTTT applets
url: https://cloudcannon.com/documentation/developer-articles/integrating-your-forms-with-ifttt/
content_type: developer article
last_modified: 2026-04-11
---

You can integrate your CloudCannon forms with your IFTTT applets using webhooks and the IFTTT Inbox target.

To create an IFTTT webhook:

1. If you haven't already, create an IFTTT account [here](https://ifttt.com/join).
2. In the IFTTT console, create a new applet by clicking the *Create* button.
3. Select the *Webhooks* service and then select *Receive a web request with a JSON payload* as your trigger.
4. Enter an event name and then click *Create Trigger*.
5. Add any actions you want to your applet, then click *Continue*. Give your applet a name and click *Finish.*
6. Navigate to *My Services > Webhooks*, then click the *Settings* button.
7. Go to the URL listed under the *Details* heading. Here you'll find your webhook URL. Replace `{event}` in the URL with the event name you gave your trigger, the resulting URL is the one you'll use to create the IFTTT target.

![The IFTTT applet create screen](assets/external_screenshots/ifttt-com-create.png)

To create an IFTTT target:

1. Navigate to the forms menu in your Organization settings, under *Hosting > Forms.*
2. Open your Inbox settings by clicking the *Manage* button on the Inbox you want to connect to IFTTT.
3. Open the *Add new target* menu, and set the *Type* to *IFTTT.*
4. Set the *Target* to the webhook URL from your IFTTT webhook service, then click *Add Inbox target*.

Now if you submit to that Inbox, your applet will be triggered with the submission data.


---

---
title: Integrating your forms with Integromat
description: Process your form submissions using Integromat scenarios.
url: https://cloudcannon.com/documentation/developer-articles/integrating-your-forms-with-integromat/
content_type: developer article
last_modified: 2026-04-11
---

> If you're looking to migrate your Integromat organization to Make, see [here](/documentation/developer-articles/integrating-your-forms-with-make-formerly-integromat/) for a guide on integrating with Make

You can integrate your CloudCannon forms with your Integromat scenarios using webhooks and the Integromat Inbox target.

To create an Integromat webhook:

1. In the Integromat console, open the *Scenarios* menu from the sidebar and click the *Create a new scenario* button.
2. Add a *Webhooks* module and select *Custom webhook* as its type.
3. When prompted to select a webhook, click the *Add* button and create a new webhook.
4. After you've created your webhook, click the *Copy address to clipboard* button. You'll need this URL to create the Integromat target. If you need to refer back to this URL you can do so from the *Webhooks* menu in the sidebar.
5. Add any additional modules that you want, then save your scenario.

![The scenario creation screen in Integromat](assets/external_screenshots/www-integromat-com-scenario-add.png)

To create an Integromat target:

1. Navigate to the forms menu in your Organization settings, under *Hosting > Forms.*
2. Open your Inbox settings by clicking the *Manage* button on the Inbox you want to connect to Integromat.
3. Open the *Add new target* menu, and set the *Type* to *Integromat.*
4. Set the *Target* to the webhook URL from your Integromat scenario, then click *Add Inbox target*.


---

---
title: Integrating your forms with Make (formerly Integromat)
description: Process your form submissions using Make scenarios.
url: https://cloudcannon.com/documentation/developer-articles/integrating-your-forms-with-make-formerly-integromat/
content_type: developer article
last_modified: 2026-04-11
---

> If you're an existing Integromat user, see [here](/documentation/developer-articles/integrating-your-forms-with-integromat/) for a guide on integrating with Integromat

You can integrate your CloudCannon forms with your Make scenarios using webhooks and the Make Inbox target.

To create a Make webhook:

1. If you haven't already, create a Make account [here](https://www.make.com/en/register).
2. In the Make console, open the *Scenarios* menu from the sidebar and click the *Create a new scenario* button.
3. Add a *Webhooks* module and select *Custom webhook* as its type.
4. When prompted to select a webhook, click the *Add* button and create a new webhook.
5. After you've created your webhook, click the *Copy address to clipboard* button. You'll need this URL to create the Make target. If you need to refer back to this URL you can do so from the *Webhooks* menu in the sidebar.
6. Add any additional modules that you want, then save your scenario.

![The scenario creation screen from Make](assets/external_screenshots/make-scenarios-add.png)

To create a Make target:

1. Navigate to the forms menu in your Organization settings, under *Hosting > Forms.*
2. Open your Inbox settings by clicking the *Manage* button on the Inbox you want to connect to Make.
3. Open the *Add new target* menu, and set the *Type* to *Make.*
4. Set the *Target* to the webhook URL from your Make scenario, then click *Add Inbox target*.

Now if you submit to that Inbox, your scenario will run on the submission data.


---

---
title: Integrating your forms with Slack
description: Send your form submissions to a Slack channel.
url: https://cloudcannon.com/documentation/developer-articles/integrating-your-forms-with-slack/
content_type: developer article
last_modified: 2026-04-11
---

You can integrate your CloudCannon forms with your Slack apps using webhooks and the Slack Inbox target.

To create a Slack webhook:

1. In the Slack API console, click the *Create an app* button and select *From Scratch* configuration.
2. Name your app and select your Slack Workspace then click *Create App*.
3. Under the *Add features and functionality menu*, click *Incoming Webhooks*.
4. Toggle *Activate Incoming Webhooks* to *On, *then click *Add New Webhook to Workspace.*
5. Select the Slack channel you want to forward submissions to, then click *Allow* to create your webhook.
6. After you've created your webhook, copy its URL. You'll need this URL to create the Slack target. If you need to refer back to this URL you can do so from the *Incoming Webhooks* menu in the sidebar.

![The Slack Incoming Webhooks console](assets/external_screenshots/api-slack-com-apps-webhooks.png)

To create a Slack target:

1. Navigate to the forms menu in your Organization settings, under *Hosting > Forms.*
2. Open your Inbox settings by clicking the *Manage* button on the Inbox you want to connect to Slack.
3. Open the *Add new target* menu, and set the *Type* to *Slack.*
4. Set the *Target* to the webhook URL from your Slack app, then click *Add Inbox target*.

Now if you submit to that Inbox, the submission data will be forwarded to Slack. See [here](https://api.slack.com/reference/messaging/payload) for a reference on the kinds of data that Slack accepts.


---

---
title: Integrating your forms with Zapier
description: Process your form submissions with Zapier zaps.
url: https://cloudcannon.com/documentation/developer-articles/integrating-your-forms-with-zapier/
content_type: developer article
last_modified: 2026-04-11
---

You can integrate your CloudCannon forms with your Zapier zaps using webhooks and the Zapier Inbox target.

To create a Zapier webhook trigger:

1. If you haven't already, create a Zapier account [here](https://zapier.com/sign-up).
2. In the Zapier console, click the *Create Zap* button.
3. Select *Webhooks* as your trigger app and *Catch Hook* as your trigger event.
4. Click the *Continue* button, then copy the webhook URL and click *Continue* again.
5. Zapier is now waiting to receive a sample submission to that webhook URL.

![The Zapier create zap screen](assets/external_screenshots/zapier-com-create-zap.png)

To finish setting up the Zap, you must first create the Zapier target in CloudCannon and send a sample submission.

To create a Zapier target:

1. Navigate to the forms menu in your Organization settings, under *Hosting > Forms.*
2. Open your Inbox settings by clicking the *Manage* button on the Inbox you want to connect to Zapier.
3. Open the *Add new target* menu, and set the *Type* to *Zapier.*
4. Set the *Target* to the webhook URL from your Zapier Zap, then click *Add Inbox target*.

Now, submit to that Inbox and then click *Test Trigger* in Zapier. At this point, you can click the *Continue* button and finish setting up your Zap.


---

---
title: Introduction to Assets and DAMs
description: CloudCannon Assets feature allows you to configure a different platform (DAM) that stores images and documents (e.g. S3, Cloudinary)
url: https://cloudcannon.com/documentation/developer-articles/introduction-to-assets-and-dams/
content_type: developer article
last_modified: 2026-02-24
---

**Assets** are often the most visually important part of your **Site**, but they can also be the largest. Storing large assets in your **Git repository** can become an issue, as most *Git Repositories* have a maximum storage amount, and larger *Repositories* have slower **Build** times.

You can configure a **Digital Asset Manager** to store your assets externally and connect it to your CloudCannon *Site*. *DAMs* also allow you to attach extra metadata to your assets, add complex sorting, and perform image transformations.

![A diagram showing code changes going to the GIT repository and large files going to your DAM](assets/diagrams/dam-diagram.svg)

Articles in this section are useful for developers responsible for configuring asset storage and managing large files in CloudCannon.

In the Assets section of our Developer documentation, we cover:

- DAMs — Learn how to connect external storage like S3, Cloudinary, Azure, and more
- Configuring paths — Learn how to configure where assets are uploaded and how they are served

Let's briefly introduce a few of these topics.

## DAMs

CloudCannon integrates with several DAM providers to store your images and documents outside your Git repository. Your editors can upload and select assets from any editing interface, and the DAM serves them from a CDN.

For a more in-depth explanation of DAMs, including how to connect and configure them, please read our documentation:

- [Creating an Azure DAM](/documentation/developer-articles/creating-an-azure-dam/)
- [Creating a Cloudflare R2 DAM](/documentation/developer-articles/creating-a-cloudflare-r2-dam/)
- [Creating a Cloudinary DAM](/documentation/developer-articles/creating-a-cloudinary-dam/)
- [Creating a DigitalOcean Spaces DAM](/documentation/developer-articles/creating-a-digitalocean-spaces-dam/)
- [Creating a Google Cloud Storage DAM](/documentation/developer-articles/creating-a-google-cloud-storage-dam/)
- [Creating an S3 DAM](/documentation/developer-articles/creating-an-s3-dam/)
- [Creating a Tenovos DAM](/documentation/developer-articles/creating-a-tenovos-dam/)
- [Managing your connected DAMs](/documentation/developer-articles/managing-your-connected-dams/)
- [Integrating your DAM with CloudCannon](/documentation/developer-articles/integrating-your-dam-with-cloudcannon/)

## Configuring paths

For finer control of your assets, you can configure where CloudCannon will save new assets after a team member uploads one, and update the DAM asset URLs to use relative paths.

For a more in-depth explanation of upload paths and asset management, please read our documentation:

- [Adjusting the uploads path](/documentation/developer-articles/adjusting-the-uploads-path/)
- [DAM assets with relative paths](/documentation/developer-articles/dam-assets-with-relative-paths/)


---

---
title: Introduction to Building
description: Learn how building works in CloudCannon, including configuration, hooks, scheduling, and more.
url: https://cloudcannon.com/documentation/developer-articles/introduction-to-building/
content_type: developer article
last_modified: 2026-02-24
---

**Building** is when CloudCannon converts all your **Site** files into a single, functional website. *Building* through CloudCannon is optional; however, extra features are available if you enable *Building*. This includes preview screenshots of your pages in the *Collection Browser*, a [Testing Domain](/documentation/user-articles/what-is-a-testing-domain/) and [Custom Domain](/documentation/developer-articles/what-is-a-custom-domain/), and the [Visual Editor](/documentation/user-articles/what-is-the-visual-editor/).

Articles in this section are useful for developers responsible for configuring and managing Site builds in CloudCannon.

> Building is an optional step. If your Site is dynamic, or you only want to use CloudCannon as a CMS for your Git repository, you don’t need to build.

In the Building section of our Developer documentation, we cover:

- Configure your builds — Learn how to set up and manage your build settings
- Extend your builds — Learn how to add more functions to your build
- Schedule your builds — Learn how to schedule builds manually or automatically
- Output Files and URLs — Learn how CloudCannon matches output files to source files
- Headless Mode — Learn how to use CloudCannon as a CMS without building or hosting
- Site Mounting — Learn how to make files from one Site available to another at build time

Let’s briefly introduce a few of these topics.

## Configure your builds

CloudCannon needs to know a few details about your Site to build it, such as which **SSG** you are using and what commands to run. You can manage these settings on the *Site Details* and *Build Configuration* pages under *Site Settings*.

For a more in-depth explanation of build configuration, please read our documentation:

- [Configure your first build](/documentation/developer-articles/configure-your-first-build/)
- [Select your SSG](/documentation/developer-articles/select-your-ssg/)
- [Configure your command line options](/documentation/developer-articles/configure-your-command-line-options/)
- [Configure your environment variables](/documentation/developer-articles/configure-your-environment-variables/)
- [Pin your dependency version](/documentation/developer-articles/pin-your-dependency-version/)
- [Lock builds for your Site](/documentation/developer-articles/lock-builds-for-your-site/)

## Extend your builds

You can add more functions to your build to collect information from your Site, improve your build time, and more.

For a more in-depth explanation of the various ways you can extend your build, please read our documentation:

- [Build hooks](/documentation/developer-articles/extending-your-build-process-with-hooks/)
- [Including the .git folder](/documentation/developer-articles/including-git-folder-in-your-build/)
- [Initial Site settings](/documentation/developer-articles/configure-your-initial-site-settings/)
- [Committing build files](/documentation/developer-articles/saving-files-from-your-build-back-to-your-source/)
- [Configure caching between builds](/documentation/developer-articles/configure-caching-between-builds/)
- [Optimize your Site](/documentation/developer-articles/optimize-your-site/)

## Schedule your builds

Scheduling a build lets you edit your Site when you have time and release your changes later.

For a more in-depth explanation of build scheduling, please read our documentation:

- [Schedule your builds manually](/documentation/developer-articles/scheduling-your-builds-manually/)
- [Schedule your builds automatically](/documentation/developer-articles/scheduling-your-next-build-automatically/)

## Output Files and URLs

When you build your *Site*, your **SSG** creates the output files your visitors see on the Internet. CloudCannon uses these output files for the *Visual Editor* preview and *Collection Browser* screenshots. You can configure how CloudCannon matches output files to source files and controls output URLs for collections.

For a more in-depth explanation of output files and URLs, please read our documentation:

- [What is an output file?](/documentation/developer-articles/what-is-an-output-file/)
- [Update the output URL for a collection](/documentation/developer-articles/update-the-output-url-for-a-collection/)
- [Disable output URL matching for a collection](/documentation/developer-articles/disable-output-url-matching-for-a-collection/)

## Headless Mode

If you don't want to build your *Site* in CloudCannon, you can enable *Headless Mode*. This disables building and hosting on CloudCannon while still allowing CloudCannon to manage your content.

For a more in-depth explanation of Headless Mode, please read our documentation:

- [What is Headless Mode?](/documentation/developer-articles/what-is-headless-mode/)
- [Enable Headless Mode](/documentation/developer-articles/enable-headless-mode/)

## Site Mounting

**Site Mounting** makes files from one or more CloudCannon *Sites* available to another *Site* at build time, allowing you to share resources and trigger builds when the resources are updated.

For a more in-depth explanation of *Site Mounting*, please read our documentation:

- [What is Site Mounting?](/documentation/developer-articles/what-is-site-mounting/)
- [Mount a Site](/documentation/developer-articles/mount-a-site/)
- [Remove a mounted Site](/documentation/developer-articles/remove-a-mounted-site/)


---

---
title: Introduction to Editing
description: Learn how to configure the editing experience in CloudCannon, including Schemas, Inputs, Structures, and Visual Editing.
url: https://cloudcannon.com/documentation/developer-articles/introduction-to-editing/
content_type: developer article
last_modified: 2026-02-23
---

Editing in CloudCannon is how your team contributes to your website content. You can configure the editing experience to make it intuitive for your content team. This includes defining data structures, choosing **input** types, and enabling visual editing on your pages.

Articles in this section are useful for developers responsible for configuring the editing experience in CloudCannon.

In the Editing section of our Developer documentation, we cover:

- Markdown Engine — Learn how to configure how CloudCannon parses and saves your Markdown content
- Schemas — Learn how to define the structure of your content and which inputs appear
- Inputs — Learn how to configure how each field is edited in the Data Editor and sidebar
- Structures — Learn how to create reusable object templates for arrays and complex content
- Snippets — Learn how to add custom blocks to **rich text** in the Content Editor
- Rich Text Editors — Learn how to customize the WYSIWYG toolbar and options
- Visual Editing — Learn how to define which elements are editable in the Visual Editor
- Data — Learn how to configure global data files and their structure

Let's briefly introduce a few of these topics.

## Markdown Engine

CloudCannon parses Markdown content into HTML for previewing and editing, and saves it in a format your **SSG** recognizes. You can configure the Markdown engine (CommonMark or Kramdown) and its options to control how CloudCannon processes your content.

For a more in-depth explanation of the Markdown engine, please read our documentation:

- [Configure your Markdown engine](/documentation/developer-articles/configure-your-markdown-engine/)

## Schemas

Schemas define the structure of your content. They specify which keys appear in your **front matter** or data files and what type of input each key uses. Schemas can be applied to **collections**, individual files, or globally.

For a more in-depth explanation of Schemas, including how to create and configure them, please read our documentation:

- [What is a Schema?](/documentation/developer-articles/what-is-a-schema/)
- [Create a Schema](/documentation/developer-articles/create-a-schema/)
- [Set the path for new files](/documentation/developer-articles/set-the-path-for-new-files/)
- [Configure the add button in collections](/documentation/developer-articles/configure-the-add-button-in-collections/)
- [Configure your collections](/documentation/developer-articles/configure-your-collections/)

## Inputs

Inputs determine how each field in your content is edited. CloudCannon supports many input types: text, number, date, file, select, rich text, and more. You can configure labels, placeholders, and validation for each input.

For a more in-depth explanation of Inputs, please read our documentation:

- [What are Inputs?](/documentation/user-articles/what-are-inputs/)
- [Configure an Array Input](/documentation/developer-articles/configure-an-array-input/)
- [Configure a Boolean Input](/documentation/developer-articles/configure-a-boolean-input/)
- [Configure a Code Input](/documentation/developer-articles/configure-a-code-input/)
- [Configure a Color Input](/documentation/developer-articles/configure-a-color-input/)
- [Configure a Date or Time Input](/documentation/developer-articles/configure-a-date-or-time-input/)
- [Configure a File Input](/documentation/developer-articles/configure-a-file-input/)
- [Configure a Number Input](/documentation/developer-articles/configure-a-number-input/)
- [Configure an Object Input](/documentation/developer-articles/configure-an-object-input/)
- [Configure a Rich Text Input](/documentation/developer-articles/configure-a-rich-text-input/)
- [Configure a Select Input](/documentation/developer-articles/configure-a-select-input/)
- [Configure a Text Input](/documentation/developer-articles/configure-a-text-input/)
- [Configure a URL Input](/documentation/developer-articles/configure-a-url-input/)
- [Populate an Array Input](/documentation/developer-articles/populate-an-array-input/)
- [Populate a Select Input](/documentation/developer-articles/populate-a-select-input/)

## Structures

Structures are predefined object templates that your team can add to arrays. For example, you might have a structure for a testimonial block or a team member card. Structures make it easy to maintain consistent content structure.

For a more in-depth explanation of Structures, please read our documentation:

- [What is a structure?](/documentation/developer-articles/what-is-a-structure/)
- [Create a structure](/documentation/developer-articles/create-a-structure/)
- [Configure your structure previews](/documentation/developer-articles/configure-your-structure-previews/)
- [Structures in the configuration cascade](/documentation/developer-articles/structures-in-the-configuration-cascade/)

## Snippets

Snippets are custom blocks that can be inserted into rich text content. They appear in the Content Editor toolbar and allow your team to add structured components like image galleries or call-to-action blocks without editing code.

For a more in-depth explanation of Snippets, please read our documentation:

- [What is a Snippet?](/documentation/developer-articles/what-is-a-snippet/)
- [Snippets using Docusaurus components](/documentation/developer-articles/snippets-using-docusaurus-components/)
- [Snippets using Eleventy shortcodes](/documentation/developer-articles/snippets-using-eleventy-shortcodes/)
- [Snippets using Hugo shortcodes](/documentation/developer-articles/snippets-using-hugo-shortcodes/)
- [Snippets using MDX components](/documentation/developer-articles/snippets-using-mdx-components/)
- [Snippets using Python Markdown](/documentation/developer-articles/snippets-using-python-markdown/)

## Rich Text Editors

Rich Text Editors provide WYSIWYG editing for markup content. You can configure which formatting options appear in the toolbar, add custom Snippets, and control how content is saved.

For a more in-depth explanation of Rich Text Editors, please read our documentation:

- [What are Rich Text Editors?](/documentation/developer-articles/what-are-rich-text-editors/)
- [Configure your rich text editors](/documentation/developer-articles/configure-your-rich-text-editors/)

## Visual Editing

**Visual Editing** allows your team to click directly on content in a live preview to edit it. You define Editable Regions in your HTML to specify which elements are editable. This creates an intuitive, WYSIWYG experience.

For a more in-depth explanation of Visual Editing, please read our documentation:

- [What is Visual Editing?](/documentation/developer-articles/what-is-visual-editing/)
- [What are Editable Regions?](/documentation/developer-articles/what-are-editable-regions/)
- [Configure array editable regions](/documentation/developer-articles/configure-array-editable-regions/)
- [Configure component editable regions](/documentation/developer-articles/configure-component-editable-regions/)
- [Configure image editable regions](/documentation/developer-articles/configure-image-editable-regions/)
- [Configure source editable regions](/documentation/developer-articles/configure-source-editable-regions/)
- [Configure text editable regions](/documentation/developer-articles/configure-text-editable-regions/)

## Data

CloudCannon can manage standalone data files in addition to content with front matter. You can configure how global data files are structured and which inputs appear when editing them.

For a more in-depth explanation of Data configuration, please read our documentation:

- [Define your data](/documentation/developer-articles/define-your-data/)


---

---
title: Introduction to Hosting
description: Learn how hosting works in CloudCannon, including Testing and Custom Domains, DNS, and SSL certificates.
url: https://cloudcannon.com/documentation/developer-articles/introduction-to-hosting/
content_type: developer article
last_modified: 2026-02-24
---

**Hosting** through CloudCannon can make your website content available on the Internet. *Hosting* through CloudCannon is optional, however, it can be convenient to manage your website hosting and content editing through the same software.

Articles in this section are useful for developers responsible for configuring hosting, domains, and security for CloudCannon Sites.

> Hosting your Site through CloudCannon is optional. You can always edit your Site using CloudCannon as your CMS and host your content through an external hosting service.

In the Hosting section of our Developer documentation, we cover:

- Web Hosting — Learn the basics of getting your website live on the Internet for visitors
- Custom Domains — Learn how to add a Custom Domain, subdomain, or host on a subpath
- DNS — Learn how to configure CloudCannon DNS or external DNS
- SSL Certificates — Learn how to add an auto-generated or custom SSL certificate to your domain
- Routing — Learn how to configure custom routing, a 404 page, extensionless URLs, geolocation, and HTTP redirects
- Authentication — Learn how to enable password, user account, or SAML authentication for your hosted Site
- External Hosting — Learn how to host your Site outside CloudCannon while using CloudCannon for editing
- Forms — Learn how to receive form submissions and integrate with external providers

Let's briefly introduce a few of these topics.

## What is web hosting?

Web hosting is where, after a successful [build](/documentation/developer-articles/what-is-a-site-build/), all your files are stored on a web server and made available to the public on the Internet. You can host your Site through CloudCannon, or through an external service.

For a more in-depth explanation of web hosting, please read our documentation:

- [What is web hosting?](/documentation/user-articles/what-is-web-hosting/)

## Custom Domains

A **Custom Domain** is a unique address used to identify a website (e.g., [cloudcannon.com](https://cloudcannon.com/)). To host your website through CloudCannon, you will need to connect your *Custom Domain* purchased from a *Domain Registrar*.

For a more in-depth explanation of Custom Domains, please read our documentation:

- [What are Custom Domains?](/documentation/developer-articles/what-is-a-custom-domain/)
- [Connect a Custom Domain to your Organization](/documentation/developer-articles/connect-a-custom-domain-to-your-organization/)
- [Disconnect a Custom Domain from your Organization](/documentation/developer-articles/disconnect-a-custom-domain-from-your-organization/)
- [Add a Custom Domain to your Site](/documentation/developer-articles/add-a-custom-domain-to-your-site/)
- [Remove a Custom Domain from your Site](/documentation/developer-articles/remove-a-custom-domain-from-your-site/)
- [Update the Fallback Redirect for your Custom Domain](/documentation/developer-articles/update-the-fallback-redirect-for-your-custom-domain/)

## DNS

The **Domain Name System** allows your computer to translate a human-readable domain name into a machine-readable IP address. *DNS providers*, like CloudCannon or other external providers, allow you to manage your domain's DNS records.

For a more in-depth explanation of DNS, including how to configure CloudCannon or external DNS, please read our documentation:

- [What is DNS?](/documentation/developer-articles/what-is-dns/)
- [Configure CloudCannon DNS](/documentation/developer-articles/configure-cloudcannon-dns/)
- [Configure external DNS](/documentation/developer-articles/configure-external-dns/)

## SSL

An SSL certificate (or a TLS certificate) is a periodically regenerated digital certificate that supports your website's authenticity and enables encryption for greater security between your web server and the visitor's browser. On CloudCannon, any Site with a [Custom Domain](/documentation/developer-articles/what-is-a-custom-domain/) can use an auto-generated or custom SSL certificate.

For a more in-depth explanation of SSL certificates, please read our documentation:

- [What is an SSL certificate?](/documentation/developer-articles/what-is-an-ssl-certificate/)
- [Add an auto-generated SSL certificate](/documentation/developer-articles/add-an-auto-generated-ssl-certificate/)
- [Add a custom SSL certificate](/documentation/developer-articles/add-a-custom-ssl-certificate/)

## Routing

Routing is the process that determines what content a visitor to your Site should see when they enter a URL in their Internet browser. On CloudCannon, you can configure custom routing to extend default routing behavior.

For a more in-depth explanation of routing, please read our documentation:

- [What is routing?](/documentation/developer-articles/what-is-routing/)
- [Configure custom routing](/documentation/developer-articles/configure-custom-routing/)
- [Configure a 404 page](/documentation/developer-articles/configure-a-404-page/)
- [Configure extensionless URLs](/documentation/developer-articles/configure-extensionless-urls/)
- [Configure geolocation](/documentation/developer-articles/configure-geolocation/)
- [Configure HTTP redirects](/documentation/developer-articles/configure-http-redirects/)

## Authentication

If you host your Site on CloudCannon, you can require visitors to your website to authenticate their identity before they can view the webpage content.

For a more in-depth explanation of authentication, please read our documentation:

- [What is authentication?](/documentation/developer-articles/what-is-authentication/)
- [Enable password authentication](/documentation/developer-articles/enable-password-authentication/)
- [Enable user account authentication](/documentation/developer-articles/enable-user-account-authentication/)
- [Enable SAML authentication](/documentation/developer-articles/enable-saml-authentication/)
- [Allow authenticated users to log out](/documentation/developer-articles/allow-authenticated-users-to-log-out/)
- [Configure authenticated routes](/documentation/developer-articles/configure-authenticated-routes/)
- [Generate a bearer token](/documentation/developer-articles/generate-a-bearer-token/)

## External Hosting

You can use CloudCannon as your CMS and host your Site through an external provider such as Netlify or Vercel. This allows you to leverage CloudCannon's editing experience while using your preferred hosting infrastructure.

For a more in-depth explanation of external hosting, please read our documentation:

- [Output a built Site from CloudCannon to an external provider](/documentation/developer-articles/output-a-built-site-from-cloudcannon-to-an-external-provider/)
- [Netlify hosting with CloudCannon editing](/documentation/developer-articles/netlify-hosting-with-cloudcannon-editing/)

## Forms

CloudCannon forms allow you to receive form submissions from visitors to your website. You can view submissions in your CloudCannon inbox, forward them to email, or integrate with external providers such as IFTTT, Make, Zapier, or Slack.

For a more in-depth explanation of forms, please read our documentation:

- [What is a form?](/documentation/developer-articles/what-is-a-form/)
- [Creating an Inbox to receive your forms](/documentation/developer-articles/creating-an-inbox-to-receive-your-forms/)
- [Connecting your Site to an Inbox](/documentation/developer-articles/connecting-your-site-to-an-inbox/)


---

---
title: Introduction to Organizations
description: Learn how to manage Organizations in CloudCannon, including creating Organizations, transferring Sites, and using the Partner Program.
url: https://cloudcannon.com/documentation/developer-articles/introduction-to-organizations/
content_type: developer article
last_modified: 2026-02-24
---

**Organizations** are the billing unit in CloudCannon, containing all your *Sites*, *Team Members*, and *Custom Domains*.

Articles in this section are useful for developers responsible for setting up *Organizations* and managing client accounts.

In the Accounts section of our Developer documentation, we cover:

- Organizations — Learn how to create and manage *Organizations*, and transfer Sites between them
- Partner Program — Learn how to manage web agency clients in CloudCannon

Let's briefly introduce a few of these topics.

## Organizations

When you create a CloudCannon account, CloudCannon will automatically make you an *Organization* on a free trial; however, you can create and be a member of as many *Organizations* as you want.

For a more in-depth explanation of *Organizations*, please read our documentation:

- [Creating a new Organization](/documentation/developer-articles/creating-a-new-organization/)
- [Transferring Sites between Organizations](/documentation/developer-articles/transferring-sites-between-organizations/)

## Partner Program

CloudCannon's [Partner Program](/partner-program/) is designed for agencies to manage client websites while providing independent editing and billing. As a member of the *Partner Program* you will have access to exclusive features to make managing several *Organizations* easier.

For a more in-depth explanation of the Partner Program in app, please read our documentation:

- [Create a Client Organization](/documentation/developer-articles/create-a-client-organization/)


---

---
title: Introduction to Publishing
description: Learn how publishing works in CloudCannon, including commit messages, projects, and branching workflows.
url: https://cloudcannon.com/documentation/developer-articles/introduction-to-publishing/
content_type: developer article
last_modified: 2026-03-11
---

CloudCannon is a **Git-backed** **CMS**, allowing you to store your website source files securely on a *Git Provider*. One benefit of *Git* is the capacity to work on content changes in parallel with separate *Branches* and control when changes are published to your live website. In CloudCannon, you can configure a **Project** for managing **Sites** connected to *Branches* in a single **Git Repository**, including designating a *Main Branch* and defining publishing workflows.

Articles in this section are useful for developers responsible for configuring publishing workflows, commit messages, and branching in CloudCannon.

In the Publishing section of our Developer documentation, we cover:

- Projects — Learn how to group multiple *Sites* connected to a single *Git Repository* and enable upstream publishing
- Publishing Methods — Learn how to configure the method of publishing changes from one branch to another

Here is a brief introduction to each of these topics.

## Projects

> **Some features are only available on our** [**Team and Enterprise plans**](/pricing/)**.**

In CloudCannon, a **Project** is a group of *Sites* connected to *Branches* from a single *Git Repository*. Creating a *Project* allows you to designate a *Main Branch* in your *Repository* and define branching rules.

For a more in-depth explanation of *Projects*, please read our documentation:

- [What is a Project?](/documentation/user-articles/what-is-a-project/)
- [Create a Project](/documentation/developer-articles/create-a-project/)
- [Add a Site to your Project](/documentation/developer-articles/add-a-site-to-your-project/)
- [Set the Main Branch for your Project](/documentation/developer-articles/set-the-main-branch-for-your-project/)
- [Add Related Links to your Project](/documentation/developer-articles/add-related-links-to-your-project/)

## Publishing Methods

> **This feature is available on our** [**Standard plans**](/pricing/)**.**

You can refine your publishing workflows in CloudCannon, choosing which **Publish Branch** each *Site* should publish to, selecting whether publishing is automatic or requires a **Pull Request**, and defining templates for *Pull Requests* for documenting your website changes.

For a more in-depth explanation of publishing methods, please read our documentation:

- [Connect a Publish Branch](/documentation/developer-articles/connect-a-publish-branch/)
- [Disable branch publishing](/documentation/developer-articles/disable-branch-publishing/)
- [Merging and pull requests](/documentation/developer-articles/merging-and-pull-requests/)
- [What is a pull request template?](/documentation/developer-articles/what-is-a-pull-request-template/)
- [Configure a pull request template](/documentation/developer-articles/configure-a-pull-request-template/)


---

---
title: Introduction to Sharing
description: Learn how sharing works in CloudCannon, including Permission Groups, Site Sharing, and Client Sharing.
url: https://cloudcannon.com/documentation/developer-articles/introduction-to-sharing/
content_type: developer article
last_modified: 2026-02-24
---

Sharing your CloudCannon *Sites* allows you to provide everyone on your team with access to your content. You can configure which resources they have access to, what actions they can perform, and how they log in to CloudCannon.

Articles in this section are helpful for developers responsible for configuring access to CloudCannon.

In the Sharing section of our Developer documentation, we cover:

- Custom Permission Groups — Learn how to create your own *Permission Groups* and specify which resources Group members can access
- Site Sharing — Learn how to give a team member permission to access a specific *Site* in your Organization
- Client Sharing — Learn how to create a site-specific password to share your content with people outside of CloudCannon
- SSO/SAML — Learn how to set up Single Sign-On for greater security
- Multi-factor Authentication — Learn how to add an extra layer of security to your account and require MFA for Organization members

Let’s briefly introduce a few of these topics.

## Custom Permission Groups

> **This feature is available on our** [**Team and Enterprise plans**](/pricing/)**.**

CloudCannon provides Default Permission Groups for every **Organization**, but for more fine-grained permission control, you can use *Custom Permission Groups*. **Custom Permission Groups** allow you to define exactly what resources its members can access and what actions they can perform.

For a more in-depth explanation of *Custom Permission Groups*, please read our documentation:

- [What are Custom Permission Groups?](/documentation/developer-articles/what-are-custom-permission-groups/)
- [Create a Custom Permission Group](/documentation/developer-articles/create-a-custom-permission-group/)
- [Delete a Custom Permission Group](/documentation/developer-articles/delete-a-custom-permission-group/)
- [Edit a Custom Permission Group](/documentation/developer-articles/edit-a-custom-permission-group/)
- [Best practices for Custom Permission Groups](/documentation/developer-articles/best-practices-for-custom-permission-groups/)

## Site Sharing

You can share a specific *Site* with collaborators from outside your CloudCannon *Organization* without giving them access to all your *Sites*. There are two *Default Permission Groups* for *Site Sharing*, equivalent to the *Technical Editors* and *Editors* groups.

For a more in-depth explanation of *Site Sharing*, please read our documentation:

- [Add a team member to Site Sharing](/documentation/developer-articles/add-a-team-member-to-site-sharing/)
- [Remove a team member from Site Sharing](/documentation/developer-articles/remove-a-team-member-from-site-sharing/)
- [Edit a team member's Site Sharing Permission Group](/documentation/developer-articles/edit-a-team-members-site-sharing-permission-group/)

## Client Sharing

You can share a specific *Site* with collaborators who do not have CloudCannon accounts and configure a simplified *Site* interface for them. Clients can log in using a Site-specific password and make changes to your content.

For a more in-depth explanation of *Client Sharing*, please read our documentation:

- [Turn on Client Sharing for a Site](/documentation/developer-articles/turn-on-client-sharing-for-a-site/)
- [Configure the commit details for clients](/documentation/developer-articles/configure-the-commit-details-for-clients/)
- [Customize the Client Sharing Permission Group](/documentation/developer-articles/customize-the-client-sharing-permission-group/)
- [Configure the Client login page](/documentation/developer-articles/configure-the-client-login-page/)
- [Configure the Client Dashboard support links](/documentation/developer-articles/configure-the-client-dashboard-support-links/)

## SSO/SAML

> **This feature is available on our** [**Enterprise plans**](/pricing/)**.**

CloudCannon supports **Single Sign-On** using a Security Assertion Markup Language (SAML). By configuring SSO/SAML, you can authenticate your team members through an external application when they log in to CloudCannon.

For a more in-depth explanation of SSO/SAML, please read our documentation:

- [What is SSO/SAML?](/documentation/developer-articles/what-is-sso-saml/)
- [Add SSO/SAML authentication](/documentation/developer-articles/add-sso-saml-authentication/)
- [Edit SSO/SAML authentication](/documentation/developer-articles/edit-sso-saml-authentication/)
- [Remove SSO/SAML authentication](/documentation/developer-articles/remove-sso-saml-authentication/)

## Multi-factor Authentication

Multi-factor Authentication (MFA) adds a second factor to your login process, typically a code from an authenticator app. This helps protect your account even if your password is compromised. Organization Owners can optionally require MFA for all team members.

For a more in-depth explanation of Multi-factor Authentication, please read our documentation:

- [Enable Multi-factor Authentication](/documentation/developer-articles/enable-multi-factor-authentication/)
- [Enforce Multi-factor Authentication](/documentation/developer-articles/enforce-multi-factor-authentication/)


---

---
title: Introduction to Sites
description: Learn how Sites work in CloudCannon, including configuration files, collections, and site customization.
url: https://cloudcannon.com/documentation/developer-articles/introduction-to-sites/
content_type: developer article
last_modified: 2026-02-20
---

You can edit content on CloudCannon through **Sites**. Each *Site* is connected to a *Branch* in your **Git Repository** and you can connect multiple *Sites* to a single *Branch*. You can customize the appearance and function of each *Site* to create the editing experience best suited to your team.

Articles in this section provide information about the *CloudCannon Configuration File* and are useful for developers responsible for customizing CloudCannon.

In the Sites section of our Developer documentation, we cover:

- CloudCannon Configuration Files — Learn about the configuration file at the heart of your CloudCannon experience.
- Configuration Mode — Learn how to edit your *Site* configuration from any page and see it update in real time.
- Collections — Learn how to group related files and configure your Collection Browser
- Cards — Learn how to configure card previews in your Collection Browser
- Commit Messages — Learn how to configure how commit messages are generated when your team saves
- Backups — Learn how to create archives of your source files
- Flags — Learn how to fine-tune Site behavior with configuration options
- Template Strings — Learn how to use placeholders to create dynamic strings for paths, card previews, and commit messages

Let's briefly introduce a few of these topics.

## CloudCannon Configuration Files

The **CloudCannon Configuration File** allows you to define preferences and settings for your *Site* to customize its functionality and appearance. CloudCannon supports `.yml` (recommended), `.yaml`, and `.json` *Configuration Files,* and you can have one or several files depending on your desired workflow and permissions.

For a more in-depth explanation of the *CloudCannon Configuration File*, please read our documentation:

- [What is the CloudCannon Configuration File?](/documentation/developer-articles/what-is-the-cloudcannon-configuration-file/)
- [Create your CloudCannon configuration file](/documentation/developer-articles/create-your-cloudcannon-configuration-file/)
- [Define a custom Configuration File path](/documentation/developer-articles/define-a-custom-configuration-file-path/)
- [Why split your Configuration File?](/documentation/developer-articles/why-split-your-configuration-file/)
- [Defining the same key in multiple Configuration Files](/documentation/developer-articles/defining-the-same-key-in-multiple-configuration-files/)
- [Best practice for splitting your Configuration File](/documentation/developer-articles/best-practice-for-splitting-your-configuration-file/)
- [Split your Configuration File](/documentation/developer-articles/split-your-configuration-file/)

## Configuration Mode

The **Configuration Mode** switch in the top right of your *Site Header* or *Editing Interface Header* toggles the visibility of *Configuration Buttons* in the app. You can use these to modify the configuration of specific elements and see your changes update the **UI** in real time.

For a more in-depth explanation of *Configuration Mode*, please read our documentation:

- [What is Configuration Mode?](/documentation/developer-articles/what-is-configuration-mode/)
- [Using the configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/)

## Collections

Your **Collections** are groups of related files with a similar format, such as product pages, blog posts, staff profiles, and more. You can access your *Collections* via the *Site Navigation* and configure your *Collection Browser* to help your team members find their files easily.

For a more in-depth explanation of *Collections*, please read our documentation:

- [Configure your collections](/documentation/developer-articles/configure-your-collections/)
- [Set a default editing interface](/documentation/developer-articles/set-a-default-editing-interface/)

## Cards

In your *Collection Browser*, each file is represented by a customizable **File Card**. You can configure how these *Cards* display information, including gallery images, titles, subtitles, and metadata, to help your team members visually differentiate between files.

For a more in-depth explanation of *Cards*, please read our documentation:

- [Configure your card previews](/documentation/developer-articles/configure-your-card-previews/)

## Commit Messages

When you or a team member saves changes in CloudCannon, those changes are committed to your **Git Repository**. **Commit messages** allow you to describe each change and provide a record for you and your team. You can configure commit message templates to maintain a consistent format across your team's edits.

For a more in-depth explanation of *Commit Messages*, please read our documentation:

- [Configure your commit messages](/documentation/developer-articles/configure-your-commit-messages/)
- [Configure an upstream commit message template](/documentation/developer-articles/configure-an-upstream-commit-message-template/)

## Backups

CloudCannon can create archives of your **Site** source files at any point in time. Backups protect against unintentional deletions and give you a snapshot of your files as they were at a specific date and time.

For a more in-depth explanation of Backups, please read our documentation:

- [Creating backups of your source files](/documentation/developer-articles/creating-backups-of-your-source-files/)

## Flags

**Flags** are configuration options that control specific behaviors in CloudCannon. They allow you to fine-tune how your Site works, from **input** behavior to editing interface options.

For a more in-depth explanation of Flags, please read our documentation:

- [What are Flags?](/documentation/developer-articles/what-are-flags/)

## Template Strings

Template strings are a mixture of literal text and dynamic placeholders that are replaced with data. You can use template strings when configuring create paths for new files, upload paths for assets, card previews in the Collection Browser, and commit messages. Placeholders reference front matter or fixed CloudCannon data to populate the string.

For a more in-depth explanation of template strings, please read our documentation:

- [Configure your template strings](/documentation/developer-articles/configure-your-template-strings/)


---

---
title: Introduction to Syncing
description: Learn how CloudCannon syncs your files from your Git Repository, or upload a website from your local storage.
url: https://cloudcannon.com/documentation/developer-articles/introduction-to-syncing/
content_type: developer article
last_modified: 2026-02-20
---

CloudCannon is a **Git-backed** **Content Management Software**, allowing you to store your website source files securely on a *Git Provider*. CloudCannon will automatically **Sync** your files whenever you create a *Site*, trigger a *Sync*, or your website files are updated via CloudCannon or an **IDE**. This means that no matter what software your team uses, everyone always has access to the latest version of your files.

Articles in this section are helpful for team members responsible for setting up *Sites* in CloudCannon and managing website files.

> You can upload your website files directly from your local storage, but we highly recommend using a *Git Provider* like GitHub, GitLab, or Bitbucket.

In the Syncing section of our Developer documentation, we cover:

- Git — Learn how to get your website files from your *Git Repository* onto CloudCannon
- Direct Upload — Learn how to upload your website files from local storage to CloudCannon
- Syncing Errors — Learn how to resolve *Syncing Errors* when CloudCannon detects that incoming changes conflict with recently saved content

Let's briefly introduce a few of these topics.

## Git

CloudCannon supports several cloud and self-hosted *Git Providers*. You can authenticate your provider, control which repository a *Site* syncs from, and enable large file storage for faster syncing.

For a more in-depth explanation of *Git* in CloudCannon, please read our documentation:

- [Authenticate your Git Provider](/documentation/developer-articles/authenticate-your-git-provider/)
- [Connect a GitHub repository](/documentation/developer-articles/connecting-a-github-repository-as-your-source/)
- [Connect a GitHub Enterprise Server repository](/documentation/developer-articles/connecting-a-github-enterprise-server-repository-as-your-source/)
- [Connect a Bitbucket repository](/documentation/developer-articles/connecting-a-bitbucket-respository-as-your-source/)
- [Connect a GitLab repository](/documentation/developer-articles/connecting-a-gitlab-respository-as-your-source/)
- [Connect a self-hosted GitLab repository](/documentation/developer-articles/connecting-a-self-hosted-gitlab-repository-as-your-source/)
- [Enable Git LFS](/documentation/developer-articles/enable-git-lfs/)
- [Creating backups of your source files](/documentation/developer-articles/creating-backups-of-your-source-files/)

## Direct Upload

Although not technically syncing, you can upload your website files directly from your local storage when you create a Site. You can still use the majority of CloudCannon's features, except for *Syncing* and *Publishing*.

For a more in-depth explanation of connecting your repository, please read our documentation:

- [Add files with Direct Upload](/documentation/developer-articles/create-a-site-with-direct-upload/)

## Syncing Errors

CloudCannon will [pause automatic syncing](/documentation/user-articles/why-is-syncing-paused/) when incoming changes from your *Git Repository* conflict with unsaved changes on your CloudCannon *Site*. If saving those changes doesn't resolve this issue, there are several solutions for *Syncing Errors*.

For a more in-depth explanation of syncing errors, please read our documentation:

- [Resolve Syncing Errors](/documentation/developer-articles/resolve-syncing-errors/)


---

---
title: Legacy form documentation
description: Create forms on your site and send the submissions to an email address or integrate with your own workflows.
url: https://cloudcannon.com/documentation/developer-articles/legacy-form-documentation/
content_type: developer article
last_modified: 2026-04-11
---

> Legacy forms are deprecated. It is recommended that you migrate to the new  forms feature. This will speed up your build process and enable a new range of features. Legacy forms will not work with all SSGs.

Create forms on your site and send the submissions to an email address or integrate with your own workflows.

To create a form:

1. Add an HTML form to a page
2. Set the `method` attribute to **post**
3. Set the `action` to where the visitor is redirected after the form submission
4. Add form fields with `name` attributes to collect data from visitors

File: `contact.html`

```html
<form method="post" action="/success.html">
  <label>Email Address</label>
  <input type="text" name="email">

  <label>Name</label>
  <input type="text" name="name">

  <label>Message</label>
  <textarea name="message"></textarea>

  <label>Urgent</label>
  <input type="checkbox" name="urgent">

  <label>Type of Enquiry</label>
  <input type="radio" name="_subject" value="Sales Enquiry"> Sales
  <input type="radio" name="_subject" value="General Enquiry"> General

  <input type="hidden" name="_to" value="sales@example.com,support@example.com">
  <input type="hidden" name="_cc" value="sales.tracker@example.com">
  <input type="text" name="_gotcha" style="display: none;">

  <input type="submit" value="Send Message">
</form>
```

CloudCannon sends named form data to email addresses of your choosing. Alternatively, [use a hook](/documentation/developer-articles/extending-your-build-process-with-hooks/#webhooks) to integrate with services like Zapier or IFTTT.

## Special Fields

Use these fields to customize the email CloudCannon sends through the form. The fields can be hidden or visible, depending on your requirements.

`_to` *(required)* - the address (or addresses) that CloudCannon sends the email to. Send the email to multiple addresses by separating them with commas.

If a `_hook` is defined, this field will not be used.

File: `contact.html`

```html
<input type="hidden" name="_to" value="contact@example.com">
```

`_replyto` or `email` - the value used for the Reply-To header in the email. Use this to ensure clients reply to the visitor rather than a default CloudCannon address.

File: `contact.html`

```html
<label>
  Your Email Address
  <input type="text" name="_replyto">
</label>
```

`_subject` - the subject of the email.

File: `contact.html`

```html
<select name="_subject">
  <option>General Enquiry</option>
  <option>Quote Request</option>
  <option>Support</option>
</select>
```

`_cc` - the value used for the CC header in the email. Use this to send a copy in another address (or addresses) without sending it directly. Send a copy of the email to multiple addresses by separating them with commas.

File: `contact.html`

```html
<input type="hidden" name="_cc" value="contact@example.com">
```

`_hook` - instead of sending an email, a webhook can be supplied for the data to be sent to. See [Webhooks](#using-webhooks) for configuration details.

File: `contact.html`

```html
<input type="hidden" name="_hook" value="https://hooks.zapier.com/hooks/catch/1234567/abcdef/">
```

`_gotcha` - honeypot field for preventing untargeted spam. CloudCannon does **not** send the email if this field has a value. Hide it with CSS to prevent visitors filling it out.

File: `contact.html`

```html
<input type="text" name="_gotcha" style="display: none;">
```

> For better spam prevention try using [Google reCAPTCHA](/documentation/developer-articles/reducing-spam-by-adding-google-recaptcha/).

## Security

these fields are encrypted before being served to protect your information and prevent spam.

- `_to`
- `_cc`
- `_hook`

## Submitting with AJAX

Submitting a form with JavaScript saves a page load after sending a message, providing a seamless experience. Viewers without JavaScript enabled will fall back to the normal flow.

To submit your form with JavaScript:

1. Build and test your form
2. Override the submit event on your form
3. Change the page to notify your viewers the message was sent

Start with this JavaScript snippet and adapt it for your site:

File: `script.js`

```javascript
// Helper function to get form data in the supported format
function getFormDataString(formEl) {
    var formData = new FormData(formEl),
      data = [];

  for (var keyValue of formData) {
      data.push(encodeURIComponent(keyValue[0]) + "=" + encodeURIComponent(keyValue[1]));
  }

  return data.join("&");
}

// Fetch the form element
var formEl = document.getElementById("contact-form");

// Override the submit event
formEl.addEventListener("submit", function (e) {
    e.preventDefault();

  if (grecaptcha) {
      var recaptchaResponse = grecaptcha.getResponse();
    if (!recaptchaResponse) { // reCAPTCHA not clicked yet
      return false;
    }
  }

  var request = new XMLHttpRequest();

  request.addEventListener("load", function () {
    if (request.status === 302) { // CloudCannon redirects on success
      // It worked
    }
  });

  request.open(formEl.method, formEl.action);
  request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
  request.send(getFormDataString(formEl));
});
```

## Using Webhooks

Create your own workflow around form submissions.

The `_hook` field allows you to supply a webhook that you control to process the form submission. The data is sent as a **POST** request with the Content Type `application/json`.

We currently allow hooks from the following platforms to be used:

- [Zapier](https://zapier.com/) - *[Documentation](https://zapier.com/help/create/code-webhooks)*
- [IFTTT](https://ifttt.com/) - *[Help Page](https://help.ifttt.com/hc/en-us/articles/115010230347-The-Webhooks-Service)*

If you have use cases beyond these platforms, [send us a message](/support/).

#### IFTTT

Note that IFTTT does not support custom **JSON** keys. Webhook Applets have access to the three keys `value1`, `value2` and `value3`, the quantity and naming is fixed. This means that you will have to reflect this structure in your form. For example:

File: `contact.html`

```html
<label>Email Address</label>
<input type="email" name="value1">
```

Zapier does not have a limitation on the number of fields or custom keys.

## Rate Limiting

Forms hosted on CloudCannon are limited to 750 submissions per 10 days. [Contact us](https://cloudcannon.com/contact) if you need this limit expanded.


---

---
title: Legacy Forms migration guide
description: A guide to migrating from legacy CloudCannon forms to the new CloudCannon forms
url: https://cloudcannon.com/documentation/developer-articles/legacy-forms-migration-guide/
content_type: developer article
last_modified: 2026-04-11
---

The new CloudCannon forms offer improved compatibility with new SSGs, reduced build times, and increased security. This guide will provide you with all the resources you need to safely migrate your existing legacy forms to the new CloudCannon forms.

If you were using legacy forms on a site, CloudCannon will have automatically created and attached a new forms Inbox to that site. That Inbox will have a single *Legacy* target, so your forms will continue working normally until you're ready to migrate.

### Migrating email forms

To migrate a legacy email form, you can follow this guide for forwarding from an Inbox to email. Your target value will be the email address in your `_to` input. The new email target only supports a single address, so if you have multiple addresses in your `_to` input or you're using the `_cc` input you'll have to create a target for each of those addresses individually.

### Migrating hooks forms

To migrate a legacy webhook form, you can follow the guide for integrating CloudCannon forms with your specific service:

- [IFTTT](/documentation/developer-articles/integrating-your-forms-with-ifttt/)
- [Integromat](/documentation/developer-articles/integrating-your-forms-with-integromat/)
- [Zapier](/documentation/developer-articles/integrating-your-forms-with-zapier/)

Your target value will be the webhook URL in your `_hook` input.

### Removing your legacy target

Once you have set up your new targets, you're now ready to remove your *Legacy* target from your Inbox.

To remove your *Legacy* target:

1. Remove all `_to`, `_cc`, and `_hook` inputs from your legacy forms. It's important to do this first so that you don't leak any private information after you delete your *Legacy* target and the form is no longer encrypted.
2. Navigate to the forms menu in your Organization settings, under *Hosting > Forms.*
3. Click the *Manage* button on the Inbox connected to your site.
4. Open the context menu for the *Legacy* target with the three dots button, and click *Delete.*

With the *Legacy* target removed, CloudCannon will skip the encrypting forms on your site for all future builds. Your form's previously encrypted details will persist until your site next builds.


---

---
title: Legacy Option Flags
description: Learn about flags that enable CloudCannon legacy behavior to support older Site configuration.
url: https://cloudcannon.com/documentation/developer-articles/legacy-option-flags/
content_type: developer article
last_modified: 2026-04-11
---

## Image size attributes default behaviour

Older versions of CloudCannon would automatically add size attributes (width, height, sizes) to the HTML for images uploaded in the [Content Editor](/documentation/user-articles/what-is-the-content-editor/) and [Editable Regions](/documentation/developer-articles/define-editable-regions-in-your-html/). This flag sets this as the default behavior, and will be turned on for some *Sites* where these attributes must be added to rich text images by default.

In most cases, this flag will be turned off, meaning that the attributes will not be injected for any editing interface that does not have `image_size_attributes: true`.

> We do not recommend turning this flag on. Please consider using the `image_size_attributes` key instead.

As an alternative to turning this flag on, you can use the `image_size_attributes: true` configuration option anywhere in the [Configuration Cascade](/documentation/developer-articles/using-the-configuration-cascade/) for the Content Editor, [Rich Text inputs](/documentation/user-articles/what-is-a-rich-text-input/#block-content), and Editable Regions. When `image_size_attributes` is `true`, CloudCannon will inject width and height attributes onto images added to rich text through the editor.

A benefit of enabling `image_size_attributes` is that Internet browsers can size `<img>` elements before loading CSS and images. This prevents "pop-in" where the webpage shifts around in front of the viewer as images are loaded and elements are resized. Additionally, these attributes are required for `srcset` to work correctly. Browsers assume that the width of an image is 100vw by default. If the image has a `srcset` but no explicit size attributes, it will appear full-width regardless of the `srcset`.

One notable disadvantage of `image_size_attributes` is that, depending on the Markdown engine used by your *Site*, Markdown-formatted images may need to be converted to HTML.

If adding size attributes to your images is not right for you, some simple CSS can ensure that your images are sized correctly on the page. Define a width for your images, then set `height` to `auto`. This will allow the browser to calculate the appropriate height for your image based on the width.

File: `styles.css`

```css

img {
  max-width: 100%;
  height: auto;
}

```

## Legacy Collections Value Key

When you use a select input to reference a collection item, the value saved in your front matter is determined by [options.value_key](/documentation/user-articles/what-is-a-select-input/#value_key) configured for your input. If this option has not been configured, the value will fallback to look for one of several sensible keys to pull from, like "id" and "title".

This flag exists to provide legacy behaviour to sites created before 25 November 2021. If turned on, select inputs that reference collection items, and which do not have `options.value_key` configured, will save a combination of the collection item's path, slug and id.

**It is not recommended to turn this flag on.** Instead, configure `options.value_key` for any select inputs that reference collections on your site.

## Hide link to telephone on URL inputs

`hide_link_to_telephone` is a configuration option that can be set on [URL inputs](/documentation/developer-articles/configure-a-url-input) to hide the option to link to a telephone number.

This flag sets the default behaviour, when `hide_link_to_telephone` is not explicitly configured. If this flag is turned on, the telephone option will be hidden for any URL input that does not explicitly have `hide_link_to_telephone` configured.


---

---
title: Linking to CloudCannon views
description: Learn how to link to CloudCannon pages from the Visual Editor to create edit buttons and speed up navigation.
url: https://cloudcannon.com/documentation/developer-articles/extending-in-app-navigation-with-editor-links/
content_type: developer article
last_modified: 2026-04-11
---

> Since October 2025, this method of visual editing has been deprecated. CloudCannon cannot guarantee support for this feature. Please consider using [Editable Regions](/documentation/developer-articles/what-are-editable-regions/) or Bookshop.

Editor Links allow you to link to other sections of the CloudCannon interface from within the [Visual Editor](/documentation/user-articles/what-is-the-visual-editor/). Use them to create edit buttons for your collection items and blog posts to quickly navigate the app. You can also add front matter Editor Links to open the front matter Editor at specified fields.

Editor Links are using the [CloudCannon link protocol](/documentation/developer-articles/cloudcannon-protocol/).

## Linking to front matter

Create a link to open a data editor at a specific input:

File: `index.html`

```html
<!-- Inputs -->
<a href="cloudcannon:#title">
  Edit the title
</a>

<!-- Arrays -->
<a href="cloudcannon:#array[1]">
  Edit the first array item
</a>

<a href="cloudcannon:#array[+]">
  Create a new item in an array
</a>

<!-- Inputs within an Object -->
<a href="cloudcannon:#object.title">
  Edit a variable within an object
</a>

<a href="cloudcannon:#object.array">
  Edit an array within an object
</a>

<!-- Inputs within an Array inside an Object -->
<a href="cloudcannon:#object.array[0].title">
  Edit the title of the first array item within an object
</a>
```

> You can edit hidden inputs by using popout-style editor links.

### Open the sidebar instead

Front matter can be highlighted within the data editor in the sidebar, or displayed standalone in a panel (default). To change open an editor link in the sidebar:

1. Add the `data-cms-bind-style` attribute
2. Set the attribute’s value to **sidebar** (optional)

File: `index.html`

```html
<a href="cloudcannon:#title" data-cms-bind-style="sidebar">
  Edit the title
</a>
```

## Linking to other views

To have edit links for posts in a list, add an Editor Link in the blog post loop:

File: `index.html`

```html
<a href="cloudcannon:collections/staff">
  Edit all staff
</a>

<a href="cloudcannon:collections/staff/jane-doe.md">
  Edit Jane Doe
</a>

<a href="cloudcannon:collections/posts/welcome-post.md">
  Edit Welcome Post
</a>

<a href="cloudcannon:status">
  Link to Site Status and Recent Activity
</a>
```

Front matter Editor Links are prefixed with `cloudcannon:#` and use a common syntax to reference them, for example:

File: `index.html`

```html
<!-- Inputs -->
<a href="cloudcannon:#title">
  Edit the title
</a>

<!-- Arrays -->
<a href="cloudcannon:#array[1]">
  Edit the first array item
</a>

<a href="cloudcannon:#array[+]">
  Create a new item in an array
</a>

<!-- Inputs within an Object -->
<a href="cloudcannon:#object.title">
  Edit a variable within an object
</a>

<a href="cloudcannon:#object.array">
  Edit an array within an object
</a>

<!-- Inputs within an Array inside an Object -->
<a href="cloudcannon:#object.array[0].title">
  Edit the title of the first array item within an object
</a>
```

### Posts Example

To insert edit links for posts in a list, add an Editor Link in the blog post loop

For example, a Hugo site would implement this as:

File: `posts.html`

```html
<ul class="blog-posts">
  {{ range .Pages }}
    <li class="blog-post">
      <h3>{{ .Title }}</h3>
      <!-- Editor Link -->
      <a href="cloudcannon:/collections/content/{{ .File.Path }}" class="editor-link">Edit post</a>
      <p>{{ .Summary }}</p>
      <a href="{{ .RelPermalink }}">Read more</a>
    </li>
  {{ end }}
</ul>
```


---

---
title: Lock builds for your Site
description: Learn how to lock build for your Site if you want to manage deployment manually.
url: https://cloudcannon.com/documentation/developer-articles/lock-builds-for-your-site/
content_type: developer article
last_modified: 2026-04-11
---

You can prevent a Site from building each time you [save your changes](/documentation/user-articles/save-your-changes/) by turning on *Building Locked* in the *Site Settings*. Locking builds on your Site is useful if you want to manage deployment manually.

CloudCannon uses your most recent, successful build to generate previews for the [Visual Editor](/documentation/user-articles/what-is-the-visual-editor/), the [Test Domain](/documentation/user-articles/what-is-a-testing-domain/), and screenshots in your [Collection](/documentation/user-articles/what-is-a-collection/) browser. When you lock builds on your Site, previews from the most recent successful build will remain live but will be out-of-date with any subsequent changes.

> CloudCannon automatically locks builds if you have not [configured your first build](/documentation/developer-articles/configure-your-first-build/) or selected [Headless Mode](/documentation/developer-articles/what-is-headless-mode/) on your Site.

To lock builds for your Site:

1. Navigate to the *Build configuration* page under *Site Settings*.
2. Check the *Building Locked* checkbox.
3. Click the *Update Site* button.

![A screenshot of the Build Configurations page shows a checkbox for Building Locked.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Build-Configuration.webp)

You can enable builds again by unchecking the *Building Locked* checkbox at any time.


---

---
title: Managing your connected DAMs
description: Learn how to update the details of your connected DAMs
url: https://cloudcannon.com/documentation/developer-articles/managing-your-connected-dams/
content_type: developer article
last_modified: 2026-03-29
---

Learn how to update the details of your connected DAMs.

## Updating your DAM details

To update the details that are stored in CloudCannon for connecting to your DAM:

1. In your Organization settings, navigate to *Files* / *Assets*
2. Locate the relevant DAM, and click the **Manage** button next to its name
3. In the **Configuration tab**, edit your details, then click **Update** to save your changes.

![The Configuration tab of an Azure DAM shows fields for Name, Base URL, Container name, Storage account name, Storage Access Key, and advanced options.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Assets-Dam-Configuration-Tab.webp)

### Limiting size of uploads to your DAM

You can use the **Maximum size for uploaded files** setting to prevent uploads exceeding a pre-determined size. This should be set in bytes. For example, to limit uploads to 1 GB you could set this to 1,000,000,000.

## Updating DAMs connected to your sites

To update the settings for using your DAM, on a site-by-site basis:

1. In your site’s settings, navigate to *Files* / *Assets*.
2. Locate your DAM from the list, and click the three dots in the top right corner.
3. From the context menu, click **Settings**
4. Edit the settings in the modal that appears, then click **Update** to save your changes.

![A screenshot of the Update site DAM modal shows fields for configuring a DAM linked to your site, including Reference Key and Uploads Locked options.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Assets-Update-DAM-Modal.webp)

### Prevent uploads to your DAM

> **Tenovos** DAMs do not support uploading within CloudCannon.

You check the **Uploads Locked** option to prevent your editors from uploading assets to the DAM from within the CloudCannon app. This is set per-site.

### Determine where on the site your DAM can be used

The `allowed_sources` configuration option can allow you to choose which "sources" (i.e. DAMs and site files) are available for different editing interfaces across a single site. To use this, you'll need to set a **Reference Key** in the site-level DAM configuration, which you can then reference in the `allowed_sources` array when configuring your inputs and editable regions.

The configuration might look something like this:

File: `cloudcannon.config.yml`

```YAML
_inputs:
  image:
    options:
      allowed_sources:
        - 'my-cloudinary-dam'
        - 'site-files'
```

The reference key can be any string, except for `site-files` which is reserved to refer to the files from your site. You also cannot have two DAMs with the same reference key on one site.

For more information, see the documentation for:

- [Configuring editable regions in your HTML](/documentation/developer-articles/define-editable-regions-in-your-html/#image-options)
- [Using rich text inputs](/documentation/user-articles/what-is-a-rich-text-input/#image-options)
- [Using upload inputs](/documentation/user-articles/what-is-a-file-input/)


---

---
title: Manually configure URLs
description: Learn how to disable CloudCannon's automatic URL detection and manually configure your URLs for faster builds.
url: https://cloudcannon.com/documentation/developer-articles/manually-configure-urls/
content_type: developer article
last_modified: 2026-03-29
---

By default, CloudCannon automatically detect the output URLs for your files and assigns them at [build](/documentation/developer-articles/what-is-a-site-build/) time. This is useful as you do not need to manually assign output URLs to each of your files.

However, this behavior may not be right for your Site if it has a larger number of files or custom Site configuration. For these Sites, CloudCannon's URLs assigning behavior may slow down your build time. For these Sites, you can disable automatic output URLs in CloudCannon and manually configure your output URLs.

> Before disabling CloudCannon's automatic URL detection, you must configure the `collections\_config.\[\*\].url` key for all output [Collections](/documentation/user-articles/what-is-a-collection/).

To manually configure your URLs:

1. Navigate to the *editing* page under *Site Settings*.
2. Click on the *Edit your configuration file* button to open your CloudCannon configuration file.
3. Navigate to the *Collections* array under the *Collections and Paths* section.
4. Click on each output Collections in the *Collections* array and ensure you have configured the *URL* key for each Collection.
5. When you are happy with your manually configured URLs for each output Collection, navigate to the *Build Configuration* page under *Site Settings*.
6. Check the *Manually Configure URLs* flag under *Build system options*.
7. Click the *Update Configuration and Build* button.

CloudCannon will immediately build your Site using the manually configured URLs.

![The Build Configuration page scrolled to the Build system options section, showing the Manually Configure URLs checkbox.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Build-Configuration-Manually-Configure-URLs.webp)

If you would prefer to configure the output URLs for your Collections in the Source Editor or your local development environment, you can achieve the same configuration with the following code:

File: `cloudcannon.config.yml`

```YAML
```

collections_config:
  blog:
    path: content/blog
    url___1___: /travel/[slug].html

```

**[1]** With automatic URL detection disabled, CloudCannon will use the explicitly configured output URL `/travel/[slug].html` for files in this Collection.
```


---

---
title: Merging and Pull Requests
description: Learn how to merge changes immediately or create and review pull requests with publishing workflows on CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/merging-and-pull-requests/
content_type: developer article
last_modified: 2026-03-29
---

> Merge Immediately and Pull Requests are [two modes of publishing](/documentation/developer-articles/connect-a-publish-branch/#change-your-publish-mode) from a branch site. To use these workflow options, you will need a connected Publish Branch. Read more about [connecting a Publish Branch](/documentation/developer-articles/connect-a-publish-branch/) or [creating a project](/documentation/developer-articles/create-a-project/) to get started.

## Merge Immediately

Merging is a straightforward method to push changes to your Publish Branch immediately. Your team members can publish changes from a branch site to the Publish Branch without approval. This mode is great for small teams or when you want less overhead.

To use merging:

1. Make changes to a branched site.
2. Once you have saved your changes, click the *Publish* button in the sidebar of the branched site.
3. On the *Publishing* page, click the *Publish* button.

CloudCannon will push your changes to your Publish Branch immediately.

![A screenshot of the CloudCannon app shows the Publishing page with a button to Publish pending changes.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Publishing-Page-Merge-Immediately.webp)

## Pull Requests

Pull Requests require approval before changes can be merged with your Publish Branch. You can also configure Pull Requests to trigger external builds and workflows.

To use Pull Requests:

1. Make changes to a branched site.
2. Once you have saved your changes, click the *Publish* button in the sidebar of the branched site.
3. On the *Publishing* page, edit the title and description of the Pull Request to provide context for the reviewer.
4. Click the *Create Pull Request* button.

![A screenshot of the CloudCannon app shows the Publishing page with fields to describe changes and a Create Pull Request button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Publishing-Page-Create-Pull-Request.webp)

### Merging a Pull Request

Once you or a team member have made a Pull Request, someone must review it before merging.

By default, anyone with the appropriate permissions can merge a Pull Request. However, you can set up additional restrictions to control who is allowed to merge a Pull Request through your Git provider. For more information about permissions, please read our documentation on [Permission Groups](/documentation/user-articles/what-are-permission-groups/).

To merge a Pull Request:

1. Click the *Publish Pending* button in the sidebar of the branched site.
2. Review the changes made to the site. Changes should be summarized in the Pull Request description, and a complete list will be visible under the *Changes* tab.
3. Click the *Merge* button to merge the changes to the Publish Branch or the *Close* button to reject the changes. If you close the Pull Request, the branch site will retain all changes until a team member updates the content or deletes the site.

![A screenshot of the CloudCannon app shows the Publishing page with a button to Merge or Close a Pull Request and a list of changes.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Publishing-Page-Open-Pull-Request.webp)

> CloudCannon will give you an error if you do not meet any additional restrictions set up in your Git provider when you attempt to merge a Pull Request.


---

---
title: Migrating to global configuration files
description: Learn how to migrate from SSG-based config to a CloudCannon Configuration File.
url: https://cloudcannon.com/documentation/developer-articles/migrating-to-global-configuration-files/
content_type: developer article
last_modified: 2026-04-11
---

> This article is deprecated.

How you set global configuration in CloudCannon has changed. We recommend updating, but the previous configuration will continue to work. CloudCannon now uses specific files rather than relying on your SSG configuration files. This allows us to provide a consistent experience across SSGs as we add more. This also separates the configuration itself, making your sites more maintainable.

To migrate, [create your CloudCannon configuration file with these instructions](/documentation/developer-articles/create-your-cloudcannon-configuration-file/), then move your configuration here.

Many of the configuration keys are the same. You can fin these keys in the [CloudCannon configuration file reference](/documentation/developer-reference/configuration-file/) documentation. Globally-scoped [configuration cascade values](/documentation/developer-articles/using-the-configuration-cascade/) must also be moved to your CloudCannon configuration file.

Here are the notable changes for your specific SSG:

> **For Jekyll sites**
> 
> CloudCannon used to read global configuration from your `_config.yml` file.
> 
> Base collection configuration is still automatically read from Jekyll itself. Collection settings are now set under `collections_config` in your global configuration file rather than in `collections` or `cloudcannon.collections` inside `_config.yml`. The contents are the same, except for [these renamed keys](#renamed-keys). Read more about [configuring your collections](/documentation/developer-articles/configure-your-collections/).
> 
> Including data files is now set in `data_config` in your global configuration file rather than in `cloudcannon.data` in `_config.yml`. The format is the same.
> 
> Your global uploads path is now set in `paths.uploads` in your global configuration file rather than in `uploads_dir` in `_config.yml`. The format is the same.

> **For Hugo sites**
> 
> CloudCannon used to read global configuration from your `config.toml` file.
> 
> Base collection configuration is still automatically read from Hugo top-level content sections. Collection configuration is now set under `collections_config` in your global configuration file rather than in `cloudcannon.collections` inside `config.toml`. The contents are the same, except for [these renamed keys](#renamed-keys). Read more about [configuring your collections](/documentation/developer-articles/configure-your-collections/).
> 
> Including data files is now set in `data_config` in your global configuration file rather than in `cloudcannon.data` in `config.toml`. The format is the same.
> 
> Your global uploads path is now set in `paths.uploads` in your global configuration file rather than in `uploads_dir` in `config.toml`. The format is the same.

> **For Eleventy sites**
> 
> CloudCannon used to read global configuration from your `_data/cloudcannon.*` file.
> 
> Base collection configuration is still automatically read from Eleventy itself. Collection configuration is now set under `collections_config` in your global configuration file rather than in `collections` inside `_data/cloudcannon.*`. The contents are the same, except for [these renamed keys](#renamed-keys). Read more about [configuring your collections](/documentation/developer-articles/configure-your-collections/).
> 
> By overwhelming demand, **defining collection configuration no longer overrides automatically-discovered collections**. If you want to restore this behavior, use the `collections_config_override` global setting.
> 
> Including data files is now set in `data_config` in your global configuration file rather than in `data` in `_data/cloudcannon.*`. The format is the same.
> 
> Your global uploads path is now set in `paths.uploads` in your global configuration file rather than in `uploads_dir` in `_data/cloudcannon.*`. The format is the same.

> **For all other sites**
> 
> CloudCannon already reads global configuration from your `cloudcannon.config.*` file for other SSGs. There are a couple of extra renamed keys here:
> 
> - `collections-config` to `collections_config`
> - `data-config` to `data_config`
> - `base-url` to `base_url`

### Renamed keys

Since collection-level configuration is now always defined separately, there's no longer any risk of clashing with SSG-specific configuration. We've taken this chance to clean up and rename the configuration keys that started with underscores in an effort to reduce that risk:

- `_collection_groups` to `collection_groups`
- `_source_editor` to `source_editor`
- `_subtext_key` to `subtext_key` inside `collections_config`
- `_image_key` to `image_key` inside `collections_config`
- `_image_size` to `image_size` inside `collections_config`
- `_singular_name` to `singular_name` inside `collections_config`
- `_singular_key` to `singular_key` inside `collections_config`
- `_disable_add` to `disable_add` inside `collections_config`
- `_icon` to `icon` inside `collections_config`
- `_add_options` to `add_options` inside `collections_config`
- `_sort_key` to `sort_key` inside `collections_config`

`sort_key` has been superseded by `sort` and `sort_options` [has been introduced](/documentation/developer-articles/configure-your-collections/).

The remaining underscore-prefixed configuration keys are not renamed so they can be identified as part of the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).


---

---
title: Migrating to input configuration
description: Learn how to migrate your input configuration to the consolidated _inputs key format in CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/migrating-to-input-configuration/
content_type: developer article
last_modified: 2026-04-11
---

How you configure inputs in CloudCannon has changed. We recommend updating, but **the previous configuration will continue to work**. There's now a consolidated key called `_inputs` that encompasses our previous keys:

- `_options`
- `_comments`
- `_instance_values`
- `_select_data`
- `_structures` (renamed from `_array_structures`)

Having the configuration keys at the top level forced you to redefine your input key multiple times, and spread the configuration for an input across multiple places. This proved to be progressively harder to maintain as you configured more inputs.

The `_inputs` configuration flips the input and configuration keys from the previous convention, allowing you to define everything for an input in one place.

We've also introduced two new configuration settings, `type` and `label`. These let you choose which kind of input you want, and what label text is shown separately from the naming conventions.

File: `Input configuration`

```yaml

anything:
_inputs:
  anything:
    type: markdown
    label: Main Content

```

## Examples

It's often easier to just see the before and after. Here are some examples covering the previous and current configurations:

### Comments

Now set with the `comment` key.

File: `Old configuration`

```yaml

brand_color: '#034ad8'
_comments:
  brand_color: Use a bold color here

```

File: `New configuration`

```yaml

brand_color: '#034ad8'
_inputs:
  brand_color:
    comment: Use a bold color here

```

### Options

Now set with the `options` key.

File: `Old configuration`

```yaml

hero_image: /uploads/hero.png
_options:
  hero_image:
    width: 500
    height: 600

```

File: `New configuration`

```yaml

hero_image: /uploads/hero.png
_inputs:
  hero_image:
    options:
      width: 500
      height: 600

```

### Instance Values

Now set with the `instance_value` key.

File: `Old configuration`

```yaml

_instance_values:
  _uuid: UUID
  created_at: NOW

```

File: `New configuration`

```yaml

_inputs:
  _uuid:
    instance_value: UUID
  created_at:
    instance_value: NOW

```

### Select data

There are no changes to `_select_data` itself:

File: `Input configuration`

```yaml

animal: Cow
_select_data:
  animals:
    - Cat
    - Cow

```

You can now choose the select values (separately from the naming convention) for a [Select input](/documentation/user-articles/what-is-a-select-input/) with `values`. Either define the values directly:

File: `Input configuration`

```yaml

animal: Cow
_inputs:
  animal:
    type: select
    options:
      values:
        - Cat
        - Cow

```

Or reference `_select_data` defined anywhere in the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/):

File: `Input configuration`

```yaml

animal: Cow
_inputs:
  animal:
    type: select
    options:
      values: _select_data.mammals
_select_data:
  mammals:
    - Cat
    - Cow

```

### Structures

Array Structures are now called [Structures](/documentation/developer-reference/configuration-file/types/_structures/), and configured with `_structures` instead of `_array_structures`. Outside of this rename, there are no changes to the configuration itself:

File: `Input configuration`

```yaml

gallery:
_structures:
  gallery:
    style: modal
    values:
      - label: Image
        icon: image
        value:
          image: /uploads/placeholder.png
          caption:
      - label: External link
        icon: link
        value:
          url:
          title:

```

You can now choose the structures (separately from the naming convention) for an [Array input](/documentation/user-articles/what-is-an-array-input/) with structures. Either define the values directly:

File: `Input configuration`

```yaml

gallery:
_inputs:
  gallery:
    type: array
    options:
      structures:
        style: modal
        values:
          - label: Image
            icon: image
            value:
              image: /uploads/placeholder.png
              caption:
          - label: External link
            icon: link
            value:
              url:
              title:

```

Or reference `_structures` defined anywhere in the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/):

File: `Input configuration`

```yaml

gallery:
_inputs:
  gallery:
    type: array
    options:
      structures: _structures.media_items
_structures:
  media_items:
    style: modal
    values:
      - label: Image
        icon: image
        value:
          image: /uploads/placeholder.png
          caption:
      - label: External link
        icon: link
        value:
          url:
          title:

```

## Where to configure inputs

The `_inputs` configuration is set alongside the inputs in the examples above. You can set it anywhere in the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/), just as the previous keys allowed. The keys inside `_inputs` entries are merged across the cascade, allowing you to overwrite or combine more specific configurations (e.g. setting comments globally and options per file).

> `_select_data` and `_structures` are defined in the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/) as well, so you can set them with or separately to `_inputs`.

## Other changes

- [Color inputs](/documentation/user-articles/what-is-a-color-input/) have new `format` and `alpha` options, falling back to the naming convention if these options are not set.
- [Hiding inputs](/documentation/developer-reference/configuration-file/types/_inputs/*/hidden/) is now set with `hidden` in an `_inputs` entry rather than an option, since it's available for any input type. This key also supports a string where the input is hidden based on the value of another input. This can start with a `!` to reverse the value.
- [Object structures are now supported](/documentation/user-articles/what-is-an-object-input/). These allow you to configure objects between an empty state (`null`) and a selection of object formats. Useful if you have components with a limited number of sub-components.
- Two new inputs: [Range number input](/documentation/user-articles/what-is-a-number-input/) and a [Switch boolean input](/documentation/user-articles/what-is-a-boolean-input/). These are only available with the new inputs config. More input types coming soon, contact support if you have specific requests.
- Comments now support a limited set of Markdown: links, bold, italic, subscript, superscript and inline code elements are allowed. Links in this block also support [Editor Links](/documentation/developer-articles/extending-in-app-navigation-with-editor-links/).


---

---
title: Migrating to preview options
description: How to migrate from our legacy preview option keys to the latest consolidated preview option.
url: https://cloudcannon.com/documentation/developer-articles/migrating-to-preview-options/
content_type: developer article
last_modified: 2026-04-11
---

How you configure previews in CloudCannon has changed. We recommend updating, but **the previous configuration will continue to work**. There’s now a consolidated key called `preview` that encompasses our previous keys:

- `text_key`
- `text`
- `subtext_key`
- `subtext`
- `icon_key`
- `icon`
- `image_key`
- `image`
- `image_size`
- `preview_image`
- `description`

As our configuration has grown, many of these keys were used inconsistently across different locations. We now offer [a single option called preview that contains each of these options](/documentation/developer-articles/configure-your-card-previews/) in a cascading process.

You can now define more than one option value for each preview option. Each option value is processed in order until a data value is found.

This is used in a number of places so far:

1. [Hugo Shortcodes](/documentation/developer-articles/snippets-using-hugo-shortcodes/) (Snippets)
2. Snippet Picker
3. [Structures](/documentation/developer-articles/what-is-a-structure/) inside [Array inputs](/documentation/user-articles/what-is-an-array-input/)
4. [Structure Picker](/documentation/developer-articles/create-a-structure/)
5. [Select-style inputs](/documentation/user-articles/what-is-a-select-input/)
6. [Object inputs](/documentation/user-articles/what-is-an-object-input/)
7. Non-structure items inside [Array inputs](/documentation/user-articles/what-is-an-array-input/)

## Examples

Here are a number of examples to show the difference before and after migrating.

### Collection items

Changing how collection items look in the collection file list:

File: `cloudcannon.config.yml (legacy)`

```yaml
collections_config:
  posts:
    text_key: heading
    subtext_key: author
    icon: event_available
    image_key: thumbnail
    image_size: contain
```

File: `cloudcannon.config.yml`

```YAML
collections_config:
  posts:
    icon: event_available
    preview:
      text_key:
        - key: heading
      subtext_key:
        - key: author
      icon: event_available # redundant here - defaults to icon above
      image: # Alternatively, migrate to preview.gallery.image
        - key: thumbnail
```

Changing how a collection item with a schema appears in the collection file list:

File: `cloudcannon.config.yml (legacy)`

```yaml
collections_config:
  posts:
    schemas:
      default:
        path: schemas/post.md
      news:
        path: schemas/news-post.md
        text_key: heading
        icon: newspaper
        image_key: cover_image
        image_size: cover
```

File: `cloudcannon.config.yml`

```YAML
collections_config:
  posts:
    schemas:
      default:
        path: schemas/post.md
      news:
        path: schemas/news-post.md
        preview:
          text:
            - key: heading
          icon: newspaper
          gallery:
            image:
              - key: cover_image
            fit: cover
```

### Object and Array inputs

Changing how an object input appears in the Data Editor before opening:

File: `cloudcannon.config.yml (legacy)`

```yaml
seo:
  title: About us
  description: A longer description of the page that is all about us.
  image: /uploads/seo-cover.png
_inputs:
  seo:
    text_key: title
    subtext_key: description
    icon: search
    image_key: image
```

File: `cloudcannon.config.yml`

```YAML
seo:
  title: About us
  description: A longer description of the page that is all about us.
  image: /uploads/seo-cover.png
_inputs:
  seo:
    preview:
      text:
        - key: title
      subtext:
        - key: description
      icon: search
      image:
        - key: image
```

Changing how a non-structure item within an array input appears in the Data Editor before opening:

File: `cloudcannon.config.yml (legacy)`

```yaml
quotes:
  - message: Great product!
    author: Jane
    image: /uploads/jane.png
  - message: Highly recommended.
    author: John
    image: /uploads/john.png
_inputs:
  quotes:
    text_key: message
    subtext_key: author
    icon: format_quote
    image_key: image
```

File: `cloudcannon.config.yml`

```YAML
quotes:
  - message: Great product!
    author: Jane
    image: /uploads/jane.png
  - message: Highly recommended.
    author: John
    image: /uploads/john.png
_inputs:
  quotes:
    preview:
      text:
        - key: message
      subtext:
        - key: author
      icon: format_quote
      image:
        - key: image
```

### Structures

Changing how a structure item appears when choosing a new one to add in the Data Editor:

File: `cloudcannon.config.yml (legacy)`

```yaml
_structures:
  gallery:
    style: modal
    values:
      - label: Image
        description: Full width image
        preview_image: https://example.com/image-screenshot.png
        image: /path/to/image.png
        icon: image
        text_key: caption
        subtext_key: image
        image_key: image
        image_size: cover
        tags:
          - Media
          - Asset
        value:
          image: /uploads/placeholder.png
          caption:
      - label: External link
        icon: link
        tags:
          - Media
        value:
          url:
          title:
```

File: `cloudcannon.config.yml`

```YAML
_structures:
  gallery:
    style: modal
    values:
      - label: Image
        icon: image
        tags:
          - Media
          - Asset
        value:
          image: /uploads/placeholder.png
          caption:
        preview:
          text:
            - key: caption
          icon: image
          subtext:
            - key: image
            - Full width image
          gallery:
            image:
              - key: image
              - /path/to/image.png
            fit: cover
        picker_preview:
          gallery:
            image: https://example.com/image-screenshot.png

      - label: External link
        icon: link
        tags:
          - Media
        value:
          url:
          title:
```


---

---
title: Mount a Site
description: Learn how to add Site Mounting with CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/mount-a-site/
content_type: developer article
last_modified: 2026-04-11
---

You can customize your settings on the *Site Mountings* page.

To mount a site:

1. Open the local site.
2. Navigate to *Site Mountings* under *Site Settings*.
3. Select your *Remote Site*. This site must be within the same Organization as the Local Site.
4. Select your *Remote artifact*, *Remote path*, and *Local path*.
5. Click the *Mount site* button.
6. CloudCannon will add the site to your *Sites mounted* list.

![The Site Mountings page shows an empty mounted sites list and a form to mount a new site with fields for Remote site, Remote artifact, Remote path, and Local path.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Site-Mountings.webp)


---

---
title: Netlify Hosting with CloudCannon Editing
description: Connect CloudCannon and Netlify to the same Git repo to enable both CloudCannon editing and Netlify builds and deployment.
url: https://cloudcannon.com/documentation/developer-articles/netlify-hosting-with-cloudcannon-editing/
content_type: developer article
last_modified: 2026-03-29
---

CloudCannon can enable editing of your Netlify-hosted static site by connecting to the same Git repo. CloudCannon pushes all content updates to your Git repo, which triggers your Netlify build and deploy.

### Setting up CloudCannon

CloudCannon works with SSG-based content. Any builder available on Netlify is available on CloudCannon. The first step is to select your Git repository.

![The Create a Site page with GitHub authorized and the Repository dropdown open, listing available repositories.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Create-a-Site-Repository-Dropdown.webp)

The next step is to select your SSG of choice; this is very similar to the build step in Netlify. If you want custom build commands we recommend using the “Custom” option. For options like Jekyll, Eleventy and Hugo, we automatically configure editing options out of the box. For more build configuration, use build hooks for prebuild, preinstall, and postbuild steps.

![The Site Settings Details page with Headless Mode selected under Site Building Mode.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Details-Headless.webp)

Once built you can configure your site and editing interface to your liking. Most of CloudCannon's interfaces are all configurable to your needs. See configuration options for more information.

### Setting up Netlify

Netlify works as a hosting provider connected to your Git site. If you need more advanced hosting for your site, Netlify offers a deep range of features. The first step is to connect your Git repository in Netlify. This needs to be the same repository that is connected to CloudCannon.

![](assets/external_screenshots/import-selected.png)

The next step is to select your SSG of choice. This is very similar to the build step in CloudCannon.

![](assets/external_screenshots/netlify-build-commands.webp)

Once built, any new commits from CloudCannon will trigger the build. CloudCannon enables your editors to push edits just like a developer. No webhooks or custom interactions required, just Git!


---

---
title: Optimize your Site
description: Learn how CloudCannon can optimize your site for faster loading by minifying CSS and JavaScript.
url: https://cloudcannon.com/documentation/developer-articles/optimize-your-site/
content_type: developer article
last_modified: 2026-03-29
---

CloudCannon optimizes sites to load as fast as possible. CloudCannon minifies CSS with [clean-css](https://github.com/GoalSmashers/clean-css) and JavaScript with [esbuild](https://esbuild.github.io/). Externally hosted assets are not optimized.

> Filenames containing -min or .min are not minified, as the filename suggests they have been minified already.

All files output from a build are hosted on our CDN. Assets referenced in the HTML and CSS are rewritten to include a unique hash in the URL, which will be seen as `?cchid=abfc7a...`. This hash allows files that haven't changed between subsequent builds of your site to remain in the cache, while all other files are purged.

Optimizations are on by default, to toggle optimizations for your site:

1. Go to the *Site Settings* / *Compressor* section
2. Toggle **Minify and serve assets from CDN**
3. Click **Update Build Details**

![Screenshot of compressor settings screen](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Build-Settings-Compressor.webp)

To turn off optimizations on individual elements, add the `.cms-no-rewrite` class to the element.

File: `index.html`

```html
<a href="/newsletters/january-summary.pdf" class="cms-no-rewrite">Download Latest Newsletter</a>

```

The element will not have the URL changed to append the `cchid`, but will have reduced cache performance.


---

---
title: Patching YAML number parsing for Jekyll
description: Learn how to apply a SafeYAML patch so Jekyll parses comma-separated numbers (e.g. 1,234) as strings in CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/patching-yaml-number-parsing-for-jekyll/
content_type: developer article
last_modified: 2026-04-11
---

This is a patch for SafeYAML (Jekyll YAML parser) to fix a parsing error.

Updating a text input in CloudCannon to 1,234 saves the value unquoted, allowed by the YAML specification. Jekyll then parses this as a number which can case unexpected results. This patch removes the comma when testing for a number.

File: `_plugins/patch.rb`

```ruby
# This is a patch for SafeYAML to fix a parsing error.
# It ensures the following is parsed as a string rather than a number:
#
# a_string: 1,234
#
# Rendering this with {{ page.a_string }}
# Unpatched is: 1234
# Patched is: 1,234

module SafeYAML
  class Transform
    class ToInteger
      MATCHERS = Deep.freeze([
        /\A[-+]?(0|([1-9][0-9_]*))\Z/, # decimal
        /\A0[0-7]+\Z/,                  # octal
        /\A0x[0-9a-f]+\Z/i,             # hexadecimal
        /\A0b[01_]+\Z/                  # binary
      ])

      def transform?(value)
        MATCHERS.each_with_index do |matcher, idx|
          return true, Integer(value) if matcher.match(value)
        end
        try_edge_cases?(value)
      end
    end
  end
end
```


---

---
title: Pin your dependency version
description: Learn how to pin dependency versions for Node, Hugo, Ruby, Python, and Deno builds on CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/pin-your-dependency-version/
content_type: developer article
last_modified: 2026-04-11
---

## Node.js

The following [Node.js](https://nodejs.org/) versions are installed:

- `14.21.3`
- `16.20.2`
- `18.20.8`
- `20.20.2`
- `22.22.2`
- `24.14.1`

Each Node.js version has the following packages preinstalled globally:

- [Rosey](https://www.npmjs.com/package/rosey)
- [Reseed](https://www.npmjs.com/package/reseed)
- [Yarn](https://classic.yarnpkg.com/lang/en/)
- [pnpm](https://pnpm.io/)

### Specifying your version

To specify the Node.js version used on your site:

1. Navigate to the *Build configuration* page under *Site Settings*.
2. Under *Library versions*, set *Node version* to the desired version from the list.
3. Click the *Update Site* button.

If you have your version already specified in a `.nvmrc` file in your repository, you can select the `Use my .nvmrc file` option in the *Node version* selector.

### Using alternative package managers

CloudCannon has npm, pnpm, and yarn pre-installed. Other package managers are not installed by default.

You can use `/.cloudcannon/preinstall` to add other package managers prior to your build/install commands. For more information, please read our documentation on [build hooks](/documentation/developer-articles/extending-your-build-process-with-hooks/#preinstall).

## Go

The following [Go](https://go.dev/) versions are installed:

- `1.21.6`

## Hugo

The preinstalled [Hugo](https://gohugo.io/) version available in the build environment is `0.128.1` (extended).

CloudCannon always installs the [extended](https://gohugo.io/installation/linux/#editions) version of Hugo.

The build environment also supports the Hugo Dart Sass transpiler with [Embedded Dart Sass](https://github.com/sass/dart-sass-embedded) preinstalled. The current supported version of [Embedded Dart Sass](https://github.com/sass/dart-sass-embedded) is `1.49.9`

### Specifying your version

To specify the Hugo version used on your site:

1. Navigate to the *Build configuration* page under *Site Settings*.
2. Under *Library versions*, set *Hugo version* to the desired version.
3. Click the *Update Site* button.

## Ruby

The following [Ruby](https://www.ruby-lang.org/) versions are installed:

- `2.6.7`
- `2.7.3`
- `3.0.1`
- `3.1.3`
- `3.2.0`
- `3.3.10`
- `3.4.8`
- `4.0.1`

### Specifying your version

To specify the Ruby version used on your site:

1. Navigate to the *Build configuration* page under *Site Settings*.
2. Under *Library versions*, set *Ruby version* to the desired version from the list.
3. Click the *Update Site* button.

If you have your version already specified in a `.ruby-version` file in your repository, you can select the `Use my .ruby-version file` option in the *Ruby version* selector.

## Python

The following [Python](https://go.dev/) versions are installed:

- `2.7.18`
- `3.10.12`

The following [pip](https://pypi.org/project/pip/) versions are installed:

- `22.0.2`

The following [pipenv](https://pipenv.pypa.io/en/latest/) versions are installed:

- `2026.2.2`

## Deno

The following [Deno](https://deno.com/) versions are installed:

- `1.44.4`
- `2.2.13`
- `2.7.1`
- `2.7.7`
- `2.7.12`

### Specifying your version

To specify the Deno version used on your site:

1. Navigate to the *Build configuration* page under *Site Settings*.
2. Under *Library versions*, set *Deno version* to the desired version from the list.
3. Click the *Update Site* button.

If you have your version already specified in a `.dvmrc` file in your repository, you can select the `Use my .dvmrc file` option in the *Deno version* selector.


---

---
title: Populate a Select input
description: Learn how to configure Select and Multiselect inputs to use fixed or dynamic lists from your data files or front matter.
url: https://cloudcannon.com/documentation/developer-articles/populate-a-select-input/
content_type: developer article
last_modified: 2026-03-29
---

> **Permissions required**
> 
> Members of all [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `site:file:write` permission, can configure inputs in all locations in the configuration cascade. You can limit permission to specific locations in the configuration using [file globs](/documentation/developer-articles/what-are-custom-permission-groups/#specify-a-file-glob).

[Select inputs](/documentation/user-articles/what-is-a-select-input/) are editing interfaces for selecting values from predefined lists. By configuring your inputs, you can customize the appearance and functionality for a better editing experience.

![The Select input in the Data Editor with the dropdown open, showing a list of options to choose from.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Select-Input-Dropdown-Open.webp)

> For a complete list of configuration keys available for inputs please read our [Inputs](/documentation/developer-reference/configuration-file/types/_inputs/) reference documentation.

All Select and Multiselect inputs must have a predefined list of value options from which to select. There are three ways to populate the list of options:

- Fixed data sets
- Collection items
- Data files

### Fixed data sets

A fixed data set is an array of predefined value options for your Select or Multiselect input, defined in the same place you configure your input. Fixed data sets are best suited to inputs with values that do not change often.

There are two ways to define a fixed data set: within the input configuration using the `options.values` key or anywhere in the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/) using the `_select_data` key.

To define the fixed data set within your input configuration, add your array of value options within the `values` key in the input `options`.

File: `cloudcannon.config.yml`

```YAML
```

_inputs:
  pets___1___:
    type: multichoice
    options:
      values___2___:
        - Dog
        - Cat
        - Rabbit

```

**[1]** This Multichoice input is called `pets`.

**[2]** You can configure a fixed data set directly inside your input under the `options.values` key. This fixed data set contains the options "Dog", "Cat", and "Rabbit".
```

To define your fixed data set elsewhere in the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/), create a nested key and array of value options within `_select_data`.

File: `cloudcannon.config.yml`

```YAML
```

_select_data___1___:
  animals___2___:
    - Dog
    - Cat
    - Rabbit

```

**[1]** You can configure a fixed data set anywhere in the configuration cascade using the `_select_data` key.

**[2]** The fixed data set called `animals` contains the options "Dog", "Cat", and "Rabbit".
```

Using the `values` key in the input `options`, you can reference a fixed data set defined elsewhere in the configuration cascade. Use the value `_select_data.key_name`, replacing `key_name` with the key name of your data set.

File: `cloudcannon.config.yml`

```YAML
```

_inputs:
  pets___1___:
    type: multichoice
    options:
      values___2___: _select_data.animals

```

**[1]** This Multichoice input is called `pets`.

**[2]** You can reference a fixed data set configured elsewhere in the configuration cascade using the `options.values` key. This input references a fixed data set called `animals`.
```

### Collections

A [Collection](/documentation/user-articles/what-is-a-collection/) is a single folder of files with a similar format. You can find your Collections in the *Site Navigation* sidebar. Using a Collection to populate your value options is useful when you want to reference pages or other content files created by team members (e.g., blogs, staff pages, or products).

You can reference a Collection for your Select or Multiselect input using the `values` key in the input `options`. Use the value `collections.key_name`, replacing `key_name` with the key name of your Collections.

File: `cloudcannon.config.yml`

```YAML
```

_inputs:
  product_carousel___1___:
    type: multiselect
    options:
      values___2___: collections.products

```

**[1]** This Multiselect input is called `product_carousel`.

**[2]** This input references a Collection called `products`.
```

> You must have [configured your Collections](/documentation/developer-articles/configure-your-collections/) for this configuration to work.

### Data files

A data file stores structured data. You can populate your input using a dedicated data file, which you can open and edit this file using the CloudCannon File Browser. Using a data file to populate your value options is useful when you want your team members to be able to edit the available options easily.

> Your Site may encounter issues if a team member removes an option from your data file that is in use by an input.

Data files must contain arrays of strings or objects. The Select or Multiselect input will use the strings if the data file contains an array, and the key names if it contains objects.

File: `theme_colors.yml`

```YAML

- Blue
- Green
- Red

```

You can reference a data file for your Select or Multiselect input using the `values` key in the input `options`. Use the value `data.key_name`, replacing `key_name` with the key name of your data file.

File: `cloudcannon.config.yml`

```YAML
```

_inputs:
  block_theme_color___1___:
    type: select
    options:
      values___2___: data.theme_colors

```

**[1]** This Select input is called `block_theme_color`.

**[2]** This input references a data file called `theme_colors`.
```

> You must have [defined your Data](/documentation/developer-articles/define-your-data/) for this configuration to work.

## Filters

A filter allows you to limit the available values for a Select or Multiselect input to a subset of possible values. Filters are available for any string value of `options.values` including fixed data sets defined under `_select_data`, Collections, or data files.

Filters use structured data keys to determine the correct subset of values. Let's walk through a few examples.

In our first example, we want to create two inputs populated by different subsets of the same fixed data set. We have the following fixed data set containing important information for our Site:

File: `cloudcannon.config.yml`

```YAML
```

_select_data___1___:
  food:
    - name: apple
      color: red
    - name: banana
      color: yellow
    - name: pineapple
      color: yellow

```

**[1]** We have defined our fixed data set under the `_select_data` key in our CloudCannon configuration file.
```

We want to configure:

1. A Multiselect input populated by all the entries in the `food` array and uses the `name` key in the input search bar to identify each entry.
2. A Choice input populated by a subset of the `food` array where the structured data key `color` has a value of `yellow` and uses the `name` key on the buttons to identify each entry.

We can configure the following filter on our input values:

File: `cloudcannon.config.yml`

```YAML
```

_inputs:
  food:
    type: multiselect
    options:
      values___1___: _select_data.food[*].name
  yellow_food:
    type: choice
    options:
      values___2___: _select_data.food[?(@.color == 'yellow')].name

```

**[1]** The `[*]` filter allows CloudCannon to use all items in the `food` fixed data set as values for the Mutiselect input `food`. By adding `.name` to the end of our value, we can specify that CloudCannon should use the `name` key to populate the input.

**[2]** The `[?(@.color == 'yellow')]` filter instructs CloudCannon to only use items in the `food` fixed data set where the `color` structured data key is equal to `yellow` as values for the Choice input `yellow_food`. By adding `.name` to the end of our value, we can specify that CloudCannon should use the `name` key to populate the input.
```

In our second example, we want to create a Multiselect input populated with the files in our `posts` Collection as value options. More specifically, we only want files where the structured data key `author` has a value of `Heather`. We can configure the following filter on our input values:

File: `cloudcannon.config.yml`

```YAML
```

_inputs:
  heathers_posts:
    type: multiselect
    label: Heather's Posts
    options:
      values___1___: "collections.posts[?(@.author == 'Heather')]"

```

**[1]** The `[?(@.author == 'Heather')]` filter instructs CloudCannon to only use items in the `posts` Collection where the `author` structured data key is equal to `Heather` as values for the Mutiselect input `heathers_posts`.
```

In our third example, we want to use data from a data file in multiple inputs. We have the following data file containing important information for our Site:

File: `example_data_file.yml`

```YAML

animals:
  - Cat
  - Dog
  - Bird
plants:
  - Tree
  - Vine
  - Shrub

```

We want to configure a Select input populated by the data in `example_data_file.yml`. More specifically, we only want values from the `animals` array within that data file. We can configure the following filter on our input values:

File: `cloudcannon.config.yml`

```YAML
```

data_config___1___:
  example_data:
    path: data/example_data_file.yml
_inputs:
  pets:
    type: select
    options:
      values___2___: data.example_data.animals

```

**[1]** In order for CloudCannon to use data from a dedicated data file, you must define the file path. For more information, please read our documentation on [defining your data](/documentation/developer-articles/define-your-data/).

**[2]** By adding `.animals` to the end of our value, we can specify that CloudCannon should only use data from the `animals` array to populate the input.
```


---

---
title: Populate an Array input
description: Learn how to configure Array inputs to use entry  input type or structures for new values.
url: https://cloudcannon.com/documentation/developer-articles/populate-an-array-input/
content_type: developer article
last_modified: 2026-03-29
---

## Populating an Array input

Without additional configuration, default Array inputs become misconfigured when empty.

In default Array inputs, CloudCannon will clone the last entry in the Array to add a new entry. This method is not possible with an empty Array. You can configure the entry input type or create a structure to avoid this issue and support empty Arrays.

### Entry input type

The entry input type defines what type of input CloudCannon should use to populate an Array or [Object](/documentation/user-articles/what-is-an-object-input/). Defining the entry input type for an Array input allows the Array to be empty without becoming misconfigured. All new entries added to an Array input will match the input type specified by the entry input type.

Array inputs with a defined entry input type avoid the issue of becoming misconfigured when empty. Because you have specified which input type to use in the Array, CloudCannon can repopulate the input if you delete the contents of the Array or create a new instance of that input.

![A screenshot of an Array input in the Data Editor.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Array-Input.webp)

You can configure the entry input type for your Array input under the `_inputs` key. To specify future entries within a particular Array, use the key name of the Array followed by the `[*]` characters. Define the type of input for those entries with the `type` key.

File: `cloudcannon.config.yml`

```YAML
```

_inputs:
  gallery:
    type: array
  gallery[*]___1___:
    type: image

```

**[1]** The entry input type determines how CloudCannon should populate an Array input. The entry input type for the `gallery` Array is `image` inputs.
```

### Structured Arrays

A structured Array allows your team to select a predefined template to populate the inputs.

> This input type relies on structures. For more information about how to configure structures, please read our [structures documentation](/documentation/developer-articles/what-is-a-structure/).

Structured Array inputs appear similar to the default input. However, unlike the default Array input, when you click the *+ Add* button to add a new array entry, CloudCannon will prompt you to select which structure to use.

![The structure picker dropdown on a structured Array input, showing available structures to add as a new entry.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Array-Input-Dropdown-Open.webp)

Structured Array inputs avoid the issue of becoming misconfigured when empty. Because you have configured at least one structure and linked it to your input, CloudCannon can repopulate the input if you delete the contents of the Array or create a new instance of that input.

![The structure picker dropdown on an empty structured Array input, showing available structures to add as a new entry.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Array-Input-Empty-Dropdown-Open.webp)

You can configure an Array input using the `structures` key. Define the `structures` key under `options` within your input key name. The value of the `structures` key can be a string or an object.

If you have defined your structures elsewhere under the `_structures` key, you can reference it by using the key name as the value (i.e., `_structures.key_name`).

File: `cloudcannon.config.yml`

```YAML
```

_inputs:
  staff___1___:
    type___2___: array
    options:
      structures___3___: _structures.staff_members

```

**[1]** This Object input is called `staff`.

**[2]** The value of the `type` key determines the input type. This is an `array` input.

**[3]** The `structures` option determines what should populate the input. In this case, it references the structure called `staff_members` defined under `_structures` elsewhere in the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).
```

Alternatively, you create an Array called `values` to define your structures directly within your input configuration.

File: `cloudcannon.config.yml`

```YAML
```

_inputs:
  staff___1___:
    type___2___: array
    options:
      structures___3___:
        values:
          - label: Manager
            icon: face
            value:
              name:
              job_description:
              profile_picture:
              url:
          - label: Employee
            icon: support_agent
            value:
              name:
              job_description:
              profile_picture:

```

**[1]** This Object input is called `feature_section`.

**[2]** The value of the `type` key determines the input type. This is an `object` input.

**[3]** The `structures` option determines what should populate the input. In this case, it is an object containing the `values` Array. For more information about how to configure structures, please read our [structures documentation](/documentation/developer-articles/what-is-a-structure/).
```


---

---
title: Reducing spam by adding Google reCAPTCHA
description: Protect form submissions from automated spam.
url: https://cloudcannon.com/documentation/developer-articles/reducing-spam-by-adding-google-recaptcha/
content_type: developer article
last_modified: 2026-04-11
---

[reCAPTCHA](https://developers.google.com/recaptcha/) embeds a CAPTCHA in your page to help prevent spam. [reCAPTCHA](https://developers.google.com/recaptcha/) requires additional configuration in the *Site Settings*.

![Gif of Google ReCAPTCHA succesfully verifying](assets/external_screenshots/hosting-forms-captcha.gif)

To add [reCAPTCHA](https://developers.google.com/recaptcha/) to your site:

1. In your organisation settings, under *Hosting > Forms* either create a new inbox or select *manage* on an existing inbox
2. Select [reCAPTCHA](https://developers.google.com/recaptcha/) as your captcha provider.
3. Sign up for an API key at [https://developers.google.com/recaptcha/](https://developers.google.com/recaptcha/)
4. Enter your secret as your captcha secret key, and your site key as your captcha site key.
5. Add reCAPTCHA to that form by following the instructions in the [reCAPTCHA documentation](https://developers.google.com/recaptcha/intro)

Once configured, any form submissions that fails to validate will return a 401 error page.

![Screenshot of form-submission failure screen](assets/external_screenshots/hosting-forms-401-error.png)

## reCAPTCHA v3

Additional JavaScript is required to use reCAPTCHA v3 with CloudCannon forms. This is to add the required input named `g-recaptcha-response` before submitting. An example of how to set this up is:

1. Add your form to the HTML
2. Include the reCAPTCHA script tag with your Site Key
3. Add JavaScript to catch form submissions
4. Generate the recaptcha token
5. Add token to a new input named `g-recaptcha-response`
6. Resubmit the form

HTML Form:

File: `contact.html`

```html

<form method="post" id="my-form" action="/contact-success">
  <label for="email_address">Email Address</label>
  <input id="email_address" type="text" name="email">

  <label for="message">Message</label>
  <textarea id="message" name="message"></textarea>

  <input type="hidden" name="_to" value="{{ site.data.company.contact_email_address }}">
  <input type="text" name="_gotcha" style="display: none;">

  <input type="submit" value="Send Message">
</form>

```

JavaScript:

File: `contact.html`

```html

<script src="https://www.google.com/recaptcha/api.js?render=SITE_ID"></script>
<script>
  var submitted = false;
  var tokenCreated = false;
  var formEl = document.getElementById('my-form');

  formEl.addEventListener("submit", function (event) {

    // Check if the recaptcha exists
    if (!tokenCreated) {

      // Prevent submission
      event.preventDefault();

      // Prevent more than one submission
      if (!submitted) {
        submitted = true;
        // needs for recaptacha ready
        grecaptcha.ready(function() {
          // do request for recaptcha token
          // response is promise with passed token
          grecaptcha.execute('SITE_ID', {action: 'create_comment'}).then(function (token) {
            // add token to form
            var input = document.createElement("input");
            input.type = "hidden";
            input.name = "g-recaptcha-response";
            input.value = token;
            formEl.appendChild(input);

            // resubmit the form
            tokenCreated = true;
            formEl.submit();
          });
        });
      }
    }
  });
</script>

```


---

---
title: Reducing spam by adding hCaptcha
description: Protect form submissions from automated spam.
url: https://cloudcannon.com/documentation/developer-articles/reducing-spam-by-adding-hcaptcha/
content_type: developer article
last_modified: 2026-04-11
---

[hCaptcha](https://www.hcaptcha.com/) embeds a CAPTCHA in your page to help prevent spam. [hCaptcha](https://www.hcaptcha.com/) requires additional configuration in your Site and Inbox Settings.

### Adding [hCaptcha](https://www.hcaptcha.com/) to an inbox

1. In your organisation settings, under *Hosting > Forms* either create a new inbox or select *manage* on an existing inbox
2. Select [hCaptcha](https://www.hcaptcha.com/) as your captcha provider.
3. Sign up at [https://www.hcaptcha.com/](https://www.hcaptcha.com/)
4. Enter your secret as your captcha secret key, and your site key as your captcha site key.

### Adding [hCaptcha](https://www.hcaptcha.com/) to your site

1. Connect your site to your hCaptcha enabled inbox in your site settings, under *Hosting > Forms.*
2. Ensure that you have selected *Require Captcha* in your site inbox settings.
3. Add a form to your site and connect it to your inbox by following the install instructions in your site inbox settings.
4. Add hCaptcha to that form by following the instructions in the [hCaptcha documentation](https://docs.hcaptcha.com/#add-the-hcaptcha-widget-to-your-webpage)

Once configured, any form submissions that fails to validate will return a 401 error page.


---

---
title: Reducing spam by adding Turnstile
description: Protect form submissions from automated spam.
url: https://cloudcannon.com/documentation/developer-articles/reducing-spam-by-adding-turnstile/
content_type: developer article
last_modified: 2026-04-11
---

[Cloudflare Turnstile](https://developers.cloudflare.com/turnstile/) embeds a CAPTCHA in your page to help prevent spam. Turnstile requires additional configuration in your Site and Inbox Settings.

### Adding [Turnstile](https://developers.cloudflare.com/turnstile/) to an inbox

1. In your Org Settings, under *Hosting > Forms* either create a new inbox or select *manage* on an existing inbox
2. Select [Turnstile](https://developers.cloudflare.com/turnstile/) as your captcha provider.
3. Sign into Cloudflare and follow [this guide](https://developers.cloudflare.com/turnstile/get-started/) to get your Turnstile captcha keys.
4. In CloudCannon, enter your secret as your captcha secret key, and your site key as your captcha site key.

### Adding [Turnstile](https://developers.cloudflare.com/turnstile/) to your site

1. Connect your site to your Turnstile enabled inbox in your Site Settings, under *Hosting > Forms.*
2. Ensure that you have selected *Require Captcha* in your site inbox settings.
3. Add a form to your site and connect it to your inbox by following the install instructions in your site inbox settings.
4. Add Turnstile to that form by following the instructions in the [Turnstile documentation](https://developers.cloudflare.com/turnstile/get-started/)

Once configured, any form submissions that fails to validate will return a 401 error page.


---

---
title: Remove a Custom Domain from your Site
description: Learn how to remove a Custom Domain from your Site and stop hosting your website content.
url: https://cloudcannon.com/documentation/developer-articles/remove-a-custom-domain-from-your-site/
content_type: developer article
last_modified: 2026-02-10
---

> **Permissions required**
> 
> Members of the Developers and Owners [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `site:settings:hosting:write` permission, can remove a Custom Domain from a Site.

A Custom Domain is a unique address used to identify a website (e.g., [cloudcannon.com](https://cloudcannon.com/)). You can connect a Custom Domain to your CloudCannon Organiation and add it to a Site to host your website content on that domain.

You may want to remove a Custom Domain from a CloudCannon Site to change the domain hosting your content, move a Custom Domain to a different CloudCannon Site, or to [disconnect a Custom Domain from your Organization](/documentation/developer-articles/disconnect-a-custom-domain-from-your-organization/).

> Removing a Custom Domain from your Site will stop all visitors from seeing your website and its content. Your website will go down until you add another a Custom Domain.

These instructions assume you have [connected a Custom Domain to your Organization](/documentation/developer-articles/connect-a-custom-domain-to-your-organization/) and [added a Custom Domain to your Site](/documentation/developer-articles/add-a-custom-domain-to-your-site/).

To remove a Custom Domain from your Site:

1. Click the *Sites* button in the *App Sidebar*. CloudCannon will open the *Sites browser*.
2. Identify the Site from which you want to remove a Custom Domain and click on the *Site* card. CloudCannon will open the *Dashboard* for that Site.
3. Navigate to the *Custom Domain* page under *Site Settings*.
4. Click the *Remove Custom Domain* button, and confirm your action in the *Click to confirm* modal.

CloudCannon will immediately stop hosting your website content on the Custom Domain.

![A screenshot of the Custom Domain page under Site Settings shows the Remove Custom Domain button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Custom-Domain-Success.webp)


---

---
title: Remove a mounted Site
description: Learn how to add Site Mounting with CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/remove-a-mounted-site/
content_type: developer article
last_modified: 2026-03-29
---

You can customize your settings on the *Site Mountings* page.

To remove a mounted site:

1. Open the local site.
2. Navigate to *Site Mountings* under *Site Settings*.
3. Identify the mounted site you want to remove and click the *Context Menu* icon in the top right corner.
4. Click the *Unmount* button.
5. On the *Confirm unmount site* pop-up window, click *Unmount*. Click again to confirm.
6. CloudCannon will remove the site from your *Sites mounted* list.

![A screenshot of the Site Mountings page showing a mounted site with the context menu open, displaying the Unmount option.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Site-Mountings-Context-Menu.webp)


---

---
title: Remove a team member from Site Sharing
description: Learn how to remove team members from Site Sharing.
url: https://cloudcannon.com/documentation/developer-articles/remove-a-team-member-from-site-sharing/
content_type: developer article
last_modified: 2026-03-29
---

To remove a team member from your Site:

1. Navigate to the *Site Sharing* page under *Site settings*.
2. Identify the team member you want to remove from this Organization. Click on the *Context Menu* in the top right of the member card.
3. Select the *Remove from Site* option from the *Context Menu* dropdown.
4. Confirm that you want to remove this team member from your Organization by clicking the *Remove from Site* button in the confirmation modal.

![A screenshot of the Site Sharing page showing a team member's context menu open, displaying the Remove from Site option.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Site-Sharing-Context-Menu.webp)


---

---
title: Remove SSO/SAML authentication
description: Learn how to remove Single Sign-On authentication from your CloudCannon Organization.
url: https://cloudcannon.com/documentation/developer-articles/remove-sso-saml-authentication/
content_type: developer article
last_modified: 2026-04-11
---

> **This feature is available on our [Enterprise plan](/pricing/).**
> 
> Want to chat about whether this feature is right for you? Our support team is always [happy to hear from you](mailto:success@cloudcannon.com?subject=A%20question%20about%20SSO%2FSAML).

To remove [SSO/SAML](/documentation/developer-articles/what-is-sso-saml/) from your Organization:

1. Navigate to the *Single Sign-On* page under *Org settings*.
2. Click on the *Danger Zone* tab.
3. Click on the *Remove SAML Authentication* button. Click again to confirm you want to remove SSO/SAML from your Organization.

> You cannot remove SSO/SAML from your Organization while your team members are using this feature. Please remove any team members using SSO/SAML from your Organization before removing this feature.


---

---
title: Resolve Syncing errors
description: Learn how to address conflicting updates in CloudCannon so you can save your changes when two sources attempt to update the same file.
url: https://cloudcannon.com/documentation/developer-articles/resolve-syncing-errors/
content_type: developer article
last_modified: 2026-04-11
---

A Syncing error occurs when CloudCannon is unable to update your Site with the incoming changes even after you try to [resume Syncing](/documentation/user-articles/resume-syncing/) by saving your changes, because the incoming changes conflict with the content you tried to save.

You cannot save unaffected files until you resolve the Syncing error and resume Syncing.

There are three was to resolve a Syncing error:

- Create a new branch and move the changes from your CloudCannon Site to it so that the current branch can sync from your Git provider. You can then attempt to merge the changes in your local development environment.
- Delete all changes on your CloudCannon Site and reset it using the version of your branch on your Git repository.
- Replace all the content on your CloudCannon Site by switching to a different branch. CloudCannon will immediately sync the files from the new branch, and will not delete any content previously deployed to the old branch.

Alternatively, you can ask your developer to resolve the Syncing error in their local development environment.

These instructions assume that [Syncing is paused](/documentation/user-articles/why-is-syncing-paused/) on your Site and you have attempted to resume Syncing by saving the changes to affected files.

![A screenshot of the Syncing page shows resolution options for a sync conflict, including creating a new branch, resetting from the Git repository, and switching to a different branch.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Syncing-Sync-Conflict.webp)

## Create a new branch

To resolve a Syncing error:

1. Navigate to the *Syncing* page, under *Site Settings*.
2. Under the *Syncing Error resolution options* section, click the *Push changes to a new branch* button under the *Create a new branch from CloudCannon changes* heading. CloudCannon will open the *Create a new branch* modal.
3. Enter the name for your new branch in the *New branch name* text field.
4. Click the *Create branch* button.

CloudCannon will immediately push the changes from your CloudCannon Site to the new branch, and sync the files from on your Git repository to the current branch.

## Reset your Site using the Git repository branch

To resolve a Syncing error:

1. Navigate to the *Syncing* page, under *Site Settings*.
2. Under the *Syncing Error resolution options* section, click the *Reset using Git repository* button under the *Reset your Site using the Git repository branch* heading. CloudCannon will open the *Reset using Git repository* modal.
3. Click the *Reset using Git repository* button.

CloudCannon will immediately sync the version of your Site on your Git repository.

![A screenshot of the Syncing page shows an error banner with options to reconnect with local changes or discard local changes and reconnect.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Syncing-Sync-Conflict.webp)

## Switch to a different branch

To resolve a Syncing error:

1. Navigate to the *Syncing* page, under *Site Settings*.
2. Under the *Syncing Error resolution options* section, click the *Switch branch* button under the *Switch this Site to a different branch* heading. CloudCannon will open the *Switch branch* modal.
3. Use the *Branch* dropdown to select the branch to which you want to switch this Site.
4. Click the *Switch branch* button.

![A screenshot of the Switch branch modal shows options to use an existing branch or create a new branch, with a branch dropdown and action buttons.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Syncing-Change-Branch-Modal-Element.webp)

CloudCannon will immediately sync the files from your chosen branch, without deleting any file previously deployed to the old branch.


---

---
title: Saving files from your build back to your source
description: Learn how to commit built or generated files from your build back to your source repository.
url: https://cloudcannon.com/documentation/developer-articles/saving-files-from-your-build-back-to-your-source/
content_type: developer article
last_modified: 2026-04-03
---

You can configure CloudCannon to commit built/generated files back to your source repository. This ensures that any generated files are consistent between CloudCannon and your source repository.

For example, if your site uses `npm`, you may want to automatically commit `package-lock.json` to your repository whenever it changes (e.g., by updating `package.json`).

### SYNC_PATHS

To configure file updates:

1. Navigate to *Site Settings* / *Build*
2. Add a new environment variable called `CLOUDCANNON_SYNC_PATHS`.
3. Add a comma-separated list of files and/or folders.

CloudCannon will use the value of this variable to determine which file's updates should be committed when your site builds. If you set a folder to be updated its entire contents will also be updated.

![Screenshot of build settings with sync paths configured](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Build-Configuration-Sync-Paths.webp)


---

---
title: Scheduling your builds manually
description: Manually scheduled builds are configured in the CloudCannon UI. They are useful for regular period builds or one-off future builds.
url: https://cloudcannon.com/documentation/developer-articles/scheduling-your-builds-manually/
content_type: developer article
last_modified: 2026-03-29
---

Manually scheduled builds are configured in the CloudCannon UI. They are useful for regular period builds or one-off future builds.

To configure a manual build:

1. Go to *Site Settings* / *Schedule*
2. Select the **Manual** tab
3. Add a **name**
4. Enter the **date** and **time** for the build to first run
5. If you want the build to repeat on a regular interval, select a **Repeat Interval**
6. Click **Create Schedule** to create a scheduled build.

> Repeat Intervals work from the original date selected. If you select a daily interval and your original time was 2pm, all future builds will run at 2pm.

![Manual Builds Schedule interface](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Schedule-Manual-Builds.webp)

To remove a build:

1. Go to *Site Settings* / *Schedule*
2. Select the **Manual** tab
3. Click **Cancel** on your selected build and then click again to confirm


---

---
title: Scheduling your next build automatically
description: After building your site, CloudCannon will read your _schedule.txt file and automatically configure a build at the specified time.
url: https://cloudcannon.com/documentation/developer-articles/scheduling-your-next-build-automatically/
content_type: developer article
last_modified: 2026-03-29
---

Automatic builds are configured by creating a `_schedule.txt` file in your site. After building your site, CloudCannon will read your `_schedule.txt` file and automatically configure a build at the specified time. This is useful for future posts.

### Schedule file format

The `_schedule.txt` is a comma separated list of values. It contains three values, which are used to schedule a build and generate the management UI.

1. **Run date**: Defines the date and time your build will be scheduled for.
2. **Build name**: A label that will be shown in the Scheduled Builds UI in CloudCannon.
3. **Source filename**: Path to a source file. The UI will show a button linking to the editor for that file. This is useful if you're scheduling a build to publish a particular file.

For example:

File: `_schedule.txt`

```
2020-10-22T10:00:00+00:00,Publish Post,_posts/2020-10-22-because-of-the-internet.md
2020-11-22T10:00:00+00:00,Publish Post,_posts/2020-11-22-the-history-of-marketing.md
```

### Generating the schedule

For convenience, it's likely you'll want to generate `_schedule.txt` programmatically.

> For Jekyll sites we recommend using our plugin, [jekyll-cloudcannon-schedule](https://github.com/CloudCannon/jekyll-cloudcannon-schedule) to generate `_schedule.txt`. This will parse all posts set for the future and generate a build on that date.
> 
> If automatic builds are not working, try adding the `–-future` flag to your Jekyll build command.
> 
> [![Build Status](https://travis-ci.com/CloudCannon/jekyll-cloudcannon-schedule.svg?branch=master)
> 
> ](https://travis-ci.com/CloudCannon/jekyll-cloudcannon-schedule)
> [![Gem Status](https://badge.fury.io/rb/jekyll-cloudcannon-schedule.svg)
> 
> ](https://badge.fury.io/rb/jekyll-cloudcannon-schedule)
> 
> Add the following to your `Gemfile`:
> 
> File: `Gemfile`
> 
> ```ruby
> group :jekyll_plugins do
>   gem 'jekyll-cloudcannon-schedule'
> end
> ```
> 
> Then add the following to your `_config.yml`:
> 
> File: `_config.yml`
> 
> ```yaml
> plugins:
>   - jekyll-cloudcannon-schedule
> ```
> 
> For Jekyll versions before 3.5.0, use `gems` instead of `plugins`.

### Viewing automatic builds

When `_schedule.txt` is correctly set up, your site will be built automatically at the specified times.

To view all available automatic builds:

1. Go to *Site Settings* / *Schedule*
2. Select the **Automatic** tab
3. Clicking **Update** will open the source filename in the content editor

![Automatic Builds Schedule interface](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Schedule-Automatic-Builds.webp)


---

---
title: Select your Static Site Generator
description: Learn how to update your site's SSG in CloudCannon if it is incorrect or you are switching SSGs.
url: https://cloudcannon.com/documentation/developer-articles/select-your-ssg/
content_type: developer article
last_modified: 2026-04-11
---

When you first [create a Site](/documentation/developer-guides/getting-started-with-cloudcannon/), CloudCannon will attempt to predict your SSG based on your Site files. It is important to confirm which Static Site Generator (SSG) your Site uses. CloudCannon uses your SSG to determine how to handle your files and provide suggestions for your [build configuration](/documentation/developer-articles/configure-your-command-line-options/).

You may need to change which SSG your Site uses if CloudCannon has detected the incorrect one or if you are rewriting it to use a different SSG.

To select your SSG:

1. Navigate to the *Details* page under *Site Settings*.
2. Click on the *Static Site Generator* dropdown and select the correct SSG option.
3. Click the *Update Site* button.

![A screenshot of the Site Details page shows the dropdown to select a Static Site Generator for this Site.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Details.webp)

> If your SSG is not available in the *Static Site Generator* dropdown, you should select *Custom*.


---

---
title: Set a default editing interface
description: Select the preferred editor and additional editors available to your team members for each file.
url: https://cloudcannon.com/documentation/developer-articles/set-a-default-editing-interface/
content_type: developer article
last_modified: 2026-02-10
---

Select the preferred editor and additional editors available to your team members for each file.

This option is set in the front matter of specific files. You can also set this [globally](/documentation/user-articles/introduction-to-editing/), or for all files in a collection when [configuring your collections](/documentation/developer-articles/configure-your-collections/).

**`_enabled_editors`** Array of strings

Controls how your team edits specific files, use this to set a preferred editor and/or disable the others. The first value sets which editor opens from the collection list, the other values specify which editors are accessible. Available values are:

- `visual` for the [Visual Editor](/documentation/user-articles/what-is-the-visual-editor/)
- `content` for the [Content Editor](/documentation/user-articles/what-is-the-content-editor/)
- `data` for the [Data Editor](/documentation/user-articles/what-is-the-data-editor/)

The [Source Editor](/documentation/user-articles/what-is-the-source-editor/) is always available for those with permission.

File: `Front Matter`

```yaml

_enabled_editors:
  - visual
  - content

```

### Hiding the content area

When files only use the front matter, it is better to display a full-screen front matter editor. You can do this by specifying `data` as the first enabled editor, and then omitting `content` from the list of enabled editors.

For example, to hide the content editor for all files in a collection called `staff`:

File: `cloudcannon.config.yml`

```YAML

collections_config:
  staff:
    _enabled_editors:
      - data
      - visual

```

This will set files in `staff` to open in the Data Editor by default, while still allowing the post to be opened in the Visual Editor. The Content Editor will be disabled.

![A screenshot of a data file open in the Data Editor.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Data-Editor.webp)


---

---
title: Set the Main Branch for your Project
description: Learn how to set or update the main branch for your CloudCannon Project.
url: https://cloudcannon.com/documentation/developer-articles/set-the-main-branch-for-your-project/
content_type: developer article
last_modified: 2026-03-11
---

Setting the **Main Branch** of your **Project** determines which branch CloudCannon will use as the default source when creating new **Sites**. You can set the *Main Branch* when you [create a Project](/documentation/developer-articles/create-a-project/), or update it at any time in *Project Settings*.

To set or update the *Main Branch*:

1. Click the *Projects* button in the *App Sidebar*. CloudCannon will open the *Projects Browser*.
2. Select the *Project* you want to update by clicking on the *Project Card*. CloudCannon will open the *Project Sites Browser*.
3. Navigate to the *Repository* section under the *Project Settings* tab.
4. Scroll down to the *Main Branch* text field and enter the name of the branch you want to use as your *Main Branch*.
5. Click the *Update Project* button.

CloudCannon will update your *Project* to use the new *Main Branch* for all new *Sites* when you use the *Create a Site* button.

![A screenshot of the Repository section in Project Settings, showing the Git Provider, Repository, and Main Branch fields.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Project-Settings-Repository.webp)


---

---
title: Set the path for new files
description: Learn how to configure Create Paths using a template string to control where CloudCannon should save new Collection files.
url: https://cloudcannon.com/documentation/developer-articles/set-the-path-for-new-files/
content_type: developer article
last_modified: 2026-03-29
---

When you create a file for a collection in CloudCannon, it is saved at a path generated from a configured pattern. These patterns are called "Create Paths". You can use these to keep your content files organized as your team members create them.

Create Paths are templates with a mixture of literal text and placeholders.

> [Placeholders](#placeholders) are dynamic parts of the create path that are replaced when saving the file. They are defined between these pairs of brackets: `[ ]` and `{ }`.

To change a create path:

- Open your global configuration file.
- Add create to a `collections_config` or `schemas` entry.

## Examples

Using the slugified title from inside the new file's front matter (or data):

File: `cloudcannon.config.yml`

```YAML

collections_config:
  pages:
    create:
      path: '[relative_base_path]/{title|slugify}.md'

```

> The example above is the default value for `create` if not configured.

If you are only setting the path inside create, you can set it directly as a string instead of an object:

File: `cloudcannon.config.yml`

```YAML

collections_config:
  pages:
    create: '[relative_base_path]/{title|slugify}.md'

```

Using various data from new file's front matter (or data):

File: `cloudcannon.config.yml`

```YAML

collections_config:
  archives:
    create:
      path: '[relative_base_path]/my-folder/{date|year}-{title|slugify}.md'

```

Using a fixed filename and a data-dependent folder:

File: `cloudcannon.config.yml`

```YAML

collections_config:
  main_pages:
    create:
      path: '[relative_base_path]/pages/{slug|deburr|slugify}/_index.md'

```

Defining a `filename` data placeholder based on `date` and `title`, then slugifies that to remove the potential leading hypens when `date` is unset (`slugify` removes leading and trailing hyphens):

File: `cloudcannon.config.yml`

```YAML

collections_config:
  posts:
    create:
      extra_data:
        filename: '{date|year}-{date|month}-{date|day}-{title}'
      path: '[relative_base_path]/{filename|slugify}.[ext]'

```

> Entries in `extra_data` are processed before `path`. They are accessible as data placeholders in `path`.

Overriding the default Create Path for a specific schema only:

File: `cloudcannon.config.yml`

```YAML

collections_config:
  posts:
    schemas:
      default:
        path: schemas/post.md
      news:
        path: schemas/post-news.md
        create:
          path: 'news/{date|year}/{slug}[count].md'

```

Escaping brackets to use them in your output path:

File: `cloudcannon.config.yml`

```YAML

collections_config:
  pages:
    create:
      path: '{section}/\[slug\].js'

```

## Placeholders

Create Paths have a number of placeholders available. There are two types of placeholders: file and data placeholders.

**File placeholders** are always available, are surrounded with `[ ]` brackets, and relate to the original file path the editor was opened at:

- `[slug]` is the original filename, excluding extension. Is an empty string if this results in “index”.
- `[filename]` is the original filename, including extension.
- `[ext]` is the last extension of the original file path.
- `[relative_path]` is the full original file path, relative to the collection path.
- `[relative_base_path]` is the original path excluding filename, relative to the collection path.
- `[full_slug]` is an alias for `[relative_base_path]/[slug]`.
- `[count]` becomes a hyphen and number if the processed file path clashes with an existing file (e.g. `file-1.md`)

**Data placeholders** are populated from front matter or data values in the editor. They are surrounded with `{ }` brackets. Here are some examples:

- `{title}` is the title from inside the file.
- `{id}` is the id from inside the file.
- `{title|lowercase}` is title from inside the file, lower cased.
- `{category|slugify}` is category from inside the file, slugified.
- `{tag|slugify|uppercase}` is tag from inside the file, slugified, then upper cased.
- `{date|year}` is date from inside the file, with the 4-digit year extracted.
- `{date|month}` is date from inside the file, with the 2-digit month extracted.
- `{date|day}` is date from inside the file, with the 2-digit day extracted.

Data placeholders support a number of **filters**. They are placed after a `|`, and multiple filters can be applied in sequence.

- `uppercase` transforms text to uppercase.
- `lowercase` transforms text to lowercase.
- `deburr` converts Latin-1 Supplement and Latin Extended-A letters to basic Latin letters and removes combining diacritical marks.
- `slugify` converts non-alphanumeric characters into hyphens, then collapses sequential hyphens, then removes leading/trailing and hyphens.
- `year` extracts the 4-digit year extracted from a date.
- `month` extracts the 2-digit month extracted from a date.
- `day` extracts the 2-digit day extracted from a date.

**Each data placeholder used in the Create Path adds an input to the save confirmation modal.**

> Changing the inputs in the save confirmation modal will also update those values in your data/front matter if those inputs are also present there.

![The save confirmation modal shows Date and Title inputs from the create path data placeholders.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Save-Confirmation.webp)

## Options

Create Paths have the following options available:

**`extra_data`** Object

Adds to the available data placeholders coming from the file. Entry values follow the same format as `path`, and are processed sequentially before `path`. These values are not saved back to your file.

**`path`** String

The raw template to be processed when creating files. Relative to the containing collection's `path`.

**`publish_to`** String

Defines a target collection when publishing. When a file is published (currently only relevant to Jekyll), the target collection's `create` definition is used instead.

*Unless you are changing the default Jekyll publish flow it is unlikely you need to set this.*

The `create` entry is part of the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/), extending the number of relevant [options available](/documentation/developer-articles/using-the-configuration-cascade/#options):

- `_inputs`
- `_select_data`
- `_structures`

File: `cloudcannon.config.yml`

```YAML

collections_config:
  posts:
    create:
      path: 'news/{date|year}/{slug}[count].md'
      _inputs:
        date:
          comment: Use the starting date here
        slug:
          comment: This is used for your filename

```


---

---
title: Snippets using Docusaurus Components
description: Learn how to add and edit components in the content of your Docusaurus website via CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/snippets-using-docusaurus-components/
content_type: developer article
last_modified: 2026-03-29
---

CloudCannon supports embedding rich Snippets in Markdown content when using the CloudCannon Content Editor. Once configured, Snippets in your content will be presented as blocks in rich text views, with the ability to add them as Snippets via the toolbar:

![The CloudCannon Content Editor toolbar showing the Insert Snippet button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Snippet-Toolbar.webp)

To start configuring Components in your MDX content, a Snippet configuration must be imported using the `_snippets_imports` key in your CloudCannon global configuration file.

File: `cloudcannon.config.yml`

```YAML

# Import the MDX Components Snippets:
_snippets_imports:
  mdx: true
  docusaurus_mdx: true

```

Docusaurus uses both regular MDX components along with custom extensions, so we import both the `mdx` Snippets and the `docusaurus_mdx` Snippets. You can find detailed documentation on the base `mdx` snippets on the [Editing with MDX Components](/documentation/developer-articles/snippets-using-mdx-components/) page.

By default, CloudCannon will show the `snippet` toolbar action in the content editor if snippets are available.

> If you have already customized which options are available via `_editables` in your CloudCannon config, you will need to include `snippet: true` for Snippets to be available. See the [Editables options documentation](/documentation/developer-articles/configure-your-rich-text-editors/) for more details.

## Disabling default Snippets

If you want to exclude specific default Snippets, you can add an `exclude` array to your configuration with the name of the snippet prefixed by `docusaurus_mdx_` (e.g., `docusaurus_mdx_truncate`).

File: `cloudcannon.config.yml`

```YAML

_snippets_imports:
  mdx: true
  docusaurus_mdx:
    exclude:
      - docusaurus_mdx_truncate

```

## Supported extensions

### Admonitions

With the Admonition snippet you can use Docusaurus [admonition syntax](https://docusaurus.io/docs/markdown-features/admonitions) to highlight rich content in the Content Editor.

File: `example.mdx`

```markdown

:::note Your Title

Some **content** with _Markdown_ `syntax`.

:::

```

### Code Blocks

The Code Block snippet allows you to create [Docusaurus code blocks](https://docusaurus.io/docs/markdown-features/code-blocks) with syntax highlighting, titles, and line numbers.

File: `example.mdx`

```markdown
```jsx title="/src/components/HelloCodeTitle.js" showLineNumbers
function HelloCodeTitle(props) {
  return <h1>Hello, {props.name}</h1>;
}
```
```

### Content Tabs

The Content Tabs snippet provides support for adding tab seperated content using the [Docusaurus Tabs component](https://docusaurus.io/docs/markdown-features/tabs). If you're using the Content Tab snippet we recommend registering it to the global scope by wrapping the MDX Component file. You can find [documentation on Docusaurus component scope](https://docusaurus.io/docs/markdown-features/react#mdx-component-scope) here.

File: `example.mdx`

```markdown

<Tabs>
  <TabItem value="apple" label="Apple" default>
    This is an apple 🍎
  </TabItem>
  <TabItem value="orange" label="Orange">
    This is an orange 🍊
  </TabItem>
  <TabItem value="banana" label="Banana">
    This is a banana 🍌
  </TabItem>
</Tabs>

```

### Truncate

The Truncate snippet allows you to mark which content should be included in the blog post summary when using the [Docusaurus blog feature](https://docusaurus.io/docs/blog).

File: `example.mdx`

```markdown

<!--truncate-->

```


---

---
title: Snippets using Eleventy Shortcodes
description: Learn how to add and edit Snippets in the content of your Eleventy website via CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/snippets-using-eleventy-shortcodes/
content_type: developer article
last_modified: 2026-03-29
---

CloudCannon supports embedding rich Snippets in Markdown content when using the CloudCannon Content Editor. Once configured,  Snippets in your content will be presented as blocks in rich text views, with the ability to add them  as Snippets via the toolbar:

![The CloudCannon Content Editor toolbar showing the Insert Snippet button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Snippet-Toolbar.webp)

To start configuring Snippets in your Eleventy content, a Snippet configuration must be imported using the `_snippets_imports` key in your CloudCannon global configuration file.

Currently, CloudCannon supports Snippets in the Nunjucks and Liquid templating languages, which can imported with the `eleventy_nunjucks` and `eleventy_liquid` keys:

File: `cloudcannon.config.yml`

```YAML
```
_snippets_imports:
  eleventy_nunjucks___1___: true
  eleventy_liquid___2___: true
```

**[1]** Import the Eleventy Nunjucks Snippets.

**[2]** Import the Eleventy Liquid Snippets.
```

CloudCannon provides support for the `raw` tag out of the box for both the `eleventy_nunjucks` and `eleventy_liquid` Snippet imports.  If this isn't desired, you can exclude this snippet like so:

File: `cloudcannon.config.yml`

```YAML
```
_snippets_imports:
  eleventy_nunjucks___1___:
    exclude:
      - eleventy_nunjucks_raw
  eleventy_liquid___2___:
    exclude:
      - eleventy_liquid_raw
```

**[1]** Exclude the Nunjucks raw tag.

**[2]** Exclude the Liquid raw tag.
```

## Enabling snippets in the toolbar

By default, CloudCannon will show the `snippet` toolbar action in the content editor if snippets are available.

> If you have already customized which options are available via `_editables` in your CloudCannon config, you will need to include `snippet: true` for Snippets to be available. See the [Editables options documentation](//documentation/developer-articles/configure-your-rich-text-editors/) for more details.

## Custom Eleventy Shortcodes

After importing the `eleventy_liquid` Snippets configurations, any custom liquid tags in your content will be displayed in the Content Editor as an `Unknown Shortcode` or `Unknown shortcode pair`. The same is true for `eleventy_nunjucks` and nunjuck tags. This allows an editor to move and delete a Snippet, but prevents editing of its arguments or content:

![The Content Editor showing an Unknown Shortcode block for an unconfigured custom shortcode.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Unknown-Shortcode.webp)

To enable editing and provide the custom Snippet in the toolbar, your custom Snippet must be configured using the `_snippets` object in your CloudCannon global config file. CloudCannon Snippets can be built from scratch to support nearly any syntax or SSG, but importing a Snippet configuration provides a set of snippet templates for common use cases in Eleventy.

To help illustrate configuring custom Snippets, we will first cover a few examples. First, let's look a custom `tint` Snippet on our Eleventy site that takes a string and applies a color to it:

File: `post.md`

```markdown
# My Post

{% tint "#ff0000" %}This text should be red{% endtint %}

```

The first thing we need to do is decide which Snippet template to use, which we can determine from the following aspects:

- First, we want to configure this shortcode for the `Nunjucks` templating language
- Next, this is an Eleventy "shortcode" rather than an "include" or other tag
- Lastly, in Eleventy terms this is a "paired" shortcode, since it has a start and an end tag that wrap some content.

Looking at the list of [snippet templates](#eleventy-snippet-templates) further down this page, this means we should configure this snippet using the `eleventy_nunjucks_paired_shortcode_positional_args` template. A full example configuration for this Snippet thus might look like the following:

File: `cloudcannon.config.yml`

```YAML
# Import the Eleventy Nunjucks Snippet templates
_snippets_imports:
  eleventy_nunjucks: true

_snippets:
  eleventy_tint:
    template: eleventy_nunjucks_paired_shortcode_positional_args
    inline: true
    preview:
      text: Tint
    definitions:
      shortcode_name: tint
      content_key: inner_text
      positional_args:
        - editor_key: tint_color
          type: string
    _inputs:
      tint_color:
        type: color
      inner_text:
        comment: This text will be tinted
```

Each snippet definition lives under a top level key, `eleventy_tint` in this example. This is the unique name that CloudCannon uses to identify this snippet, but is otherwise unused in the shortcode configuration itself.

We specify the template that this snippet should inherit from, and also specify that it is an `inline` snippet, since it can live anywhere in the content (such as in the middle of a sentence).

In the `preview` object we configure how this snippet is displayed while editing, using the [CloudCannon card preview options](/documentation/developer-articles/configure-your-card-previews/).

In `definitions` we need to specify some values that are required for the template we picked. For the `eleventy_nunjucks_paired_shortcode_positional_args` template, we need to specify:

- The `shortcode_name` — in this case we're configuring our `tint` shortcode
- The `content_key` — this controls the key that CloudCannon will use to edit the text in between the start and end tags of the shortcode.
- The `positional_args` — for our `tint` shortcode we need to configure that the first argument should be captured with the key `tint_color`

Finally, we can specify any other keys from the [CloudCannon configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/) here. In this example, we configure the inputs for the keys that this snippet will generate. With that in place, we can now add and edit our tint shortcode anywhere on our site.

![The Content Editor showing a Tint Snippet block selected with the data editor panel open, displaying Color and Inner Text inputs.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Snippet-Edit-Panel.webp)

Next, let's quickly look at a shortcode with a different syntax:

File: `post.md`

```markdown
# My Post

{% include 'callout' type: 'info' message: 'This is my shortcode' %}

```

This time, we have an unpaired Liquid include that takes `type` and `message` argument keys. This syntax matches the `eleventy_liquid_include` template.

In CloudCannon, we could configure this snippet using the following global configuration:

File: `cloudcannon.config.yml`

```YAML
# Import the Eleventy Liquid Snippets:
_snippets_imports:
  eleventy_liquid: true

_snippets:
  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
```

This should now be familiar, but with a few changes:

- We want this snippet to be a block-level element in the editor, so we set `inline` to `false`.
- Since this include does not have an end tag, we have no `content_key`
- Instead of `positional_args`, we now have `named_args`

Configuring named arguments uses most of the same options as the positional arguments earlier, but here we can additionally specify `source_key` and `editor_key` separately. In this example, we want the key in our shortcode to be `type`, but tell CloudCannon to treat that value as the `label` key, which we then configure using our inputs configuration.

![The Content Editor showing a Callout Snippet block selected with the data editor panel open, displaying Type and Inner Text inputs.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Callout-Snippet-Edit-Panel.webp)

## Snippet options

The following options are available for Eleventy snippets:

**`template`** String

The template that this snippet should inherit, out of the available [Eleventy Snippet Templates](#eleventy-snippet-templates).

**`definitions`** Object

The variables required for the selected template.

**`inline`** Boolean

Whether this Snippet can appear inline (within a sentence). Defaults to `false`, which will treat this Snippet as a block-level element in the content editor.

**`preview`** Object

A preview definition for displaying this Snippet in the CloudCannon editor. See the [preview options documentation](/documentation/developer-articles/configure-your-card-previews/).

**`_inputs`** Object

Input configurations for the keys contained in this Snippet.

## Eleventy Snippet Templates

The first step to configure your custom Snippet is to identify which Snippet template to use, as each Snippet template requires a set of `definitions` keys to be configured. The following Snippet templates are available:

### Shortcode with positional arguments

File: `example.md`

```markdown
# eleventy_nunjucks_shortcode_positional_args
{% custom_shortcode arg1 arg2 %}

# eleventy_liquid_shortcode_positional_args
{% custom_shortcode arg1, arg2 %}
```

#### Example config

File: `cloudcannon.config.yml`

```YAML
_snippets:
  custom_snippet:
    template: eleventy_nunjucks_shortcode_positional_args
    inline: false
    preview:
      text: My Custom Snippet
    definitions:
      shortcode_name: custom_shortcode
      positional_args:
        - editor_key: argument_one
          type: string
        - editor_key: argument_two
          type: string
```

#### Definitions

**`shortcode_name`** String

The name of your shortcode, as used in your Eleventy content files.

**`positional_args`** Array of [argument options](#argument-options)

An ordered list of each argument the shortcode takes.

### Paired shortcode with positional arguments

File: `example.md`

```markdown
# eleventy_nunjucks_paired_shortcode_positional_args
{% custom_shortcode arg1, arg2 %} content {% endcustom_shortcode %}

# eleventy_liquid_paired_shortcode_positional_args
{% custom_shortcode arg1 arg2 %} content {% endcustom_shortcode %}
```

#### Example config

File: `cloudcannon.config.yml`

```YAML
_snippets:
  custom_snippet:
    template: eleventy_liquid_paired_shortcode_positional_args
    inline: false
    preview:
      text: My Custom Snippet
    definitions:
      shortcode_name: custom_shortcode
      content_key: custom_key
      positional_args:
        - editor_key: argument_one
          type: string
        - editor_key: argument_two
          type: string
```

#### Definitions

**`shortcode_name`** String

The name of your shortcode, as used in your Eleventy content files.

**`content_key`** String

The key to use in the data panel for editing the inner contents of the shortcode.

**`positional_args`** Array of [argument options](#argument-options)

An ordered list of each argument the shortcode takes.

### Shortcode with named arguments

File: `example.md`

```markdown
# Only supported in Nunjucks
# eleventy_nunjucks_shortcode_named_args
{% custom_shortcode arg="value" %}
```

#### Example config

File: `cloudcannon.config.yml`

```YAML
_snippets:
  custom_snippet:
    template: eleventy_nunjucks_shortcode_named_args
    inline: false
    preview:
      text: My Custom Snippet
    definitions:
      shortcode_name: custom_shortcode
      named_args:
        - editor_key: arg
          type: string
```

#### Definitions

**`shortcode_name`** String

The name of your shortcode, as used in your Eleventy content files.

**`named_args`** Array of [argument options](#argument-options)

A list of each key-value pair the shortcode takes.

### Paired shortcode with named arguments

File: `example.md`

```markdown
# Only supported in Nunjucks
# eleventy_nunjucks_paired_shortcode_named_args
{% custom_shortcode arg="value" %} content {% endcustom_shortcode %}
```

#### Example config

File: `cloudcannon.config.yml`

```YAML
_snippets:
  custom_snippet:
    template: eleventy_nunjucks_paired_shortcode_named_args
    inline: false
    preview:
      text: My Custom Snippet
    definitions:
      shortcode_name: custom_shortcode
      content_key: custom_key
      named_args:
        - editor_key: arg
          type: string
```

#### Definitions

**`shortcode_name`** String

The name of your shortcode, as used in your Eleventy content files.

**`content_key`** String

The key to use in the data panel for editing the inner contents of the shortcode.

**`named_args`** Array of [argument options](#argument-options)

A list of each key-value pair the shortcode takes.

### Eleventy Include

File: `example.md`

```markdown
# eleventy_liquid_include
{% include 'custom_include' arg="value" %}

# eleventy_nunjucks_include
{% include 'custom_include.njk' %}
```

#### Example config

File: `cloudcannon.config.yml`

```YAML
_snippets:
  custom_snippet:
    template: eleventy_liquid_include
    inline: false
    preview:
      text: My Custom Include
    definitions:
      include_name: custom_include
      named_args:
        - editor_key: arg
          type: string
```

#### Definitions

**`include_name`** String

The name of the file being included.

**`named_args`** Array of [argument options](#argument-options)

Supported in liquid only, a list of each key-value pair the include takes.

### Eleventy Render

File: `example.md`

```markdown
# eleventy_liquid_render
{% render 'custom_render' arg="value" %}
```

#### Example config

File: `cloudcannon.config.yml`

```YAML
_snippets:
  custom_snippet:
    template: eleventy_liquid_render
    inline: false
    preview:
      text: My Custom Render
    definitions:
      render_name: custom_render
      named_args:
        - editor_key: arg
          type: string
```

#### Definitions

**`render_name`** String

The name of the file being rendered.

**`named_args`** Array of [argument options](#argument-options)

A list of each key-value pair the render takes.

### Eleventy Bookshop Tags

File: `example.md`

```markdown
# eleventy_liquid_bookshop_component
{% bookshop 'my_component' arg="value" %}

# eleventy_liquid_bookshop_include
{% bookshop_include 'my_helper' arg="value" %}
```

#### Example config

File: `cloudcannon.config.yml`

```YAML
_snippets:
  custom_snippet:
    template: eleventy_liquid_bookshop_component
    inline: false
    preview:
      text: My Custom Render
    definitions:
      component_name: my_component
      named_args:
        - editor_key: arg
          type: string
```

#### Definitions

**`component_name`** String

For components, the name of the component.

**`include_name`** String

For includes, the name of the include.

**`named_args`** Array of [argument options](#argument-options)

A list of each key-value pair the tag takes.

## Argument options

The following options are available for positional and named argument option objects:

**`editor_key`** String

Determines the key that will be used for this argument in the CloudCannon data panel.

**`source_key`** String

Determines the key of the key-value pair as it appears in the shortcode.

Only used for named arguments, and will default to the `editor_key` if unset.

**`default`** Any

The default value that should be used for this argument when creating a new snippet in the CloudCannon editor.

**`type`** String

Restrict this argument to parse as the specified type. Useful to ensure booleans get parsed as the boolean value, rather than a string such as "true".

One of:

- string
- boolean
- number
- array

**`optional`** Boolean

Whether this argument is required for the shortcode. If `false`, shortcodes in your templates missing this argument will not match this snippet definition.

Defaults to `false`.

**`remove_empty`** Boolean

Whether this argument should be omitted from the output shortcode if the value is empty.

Only used for named arguments, defaults to `false`.

**`allowed_values`** Array of values

A list of values that this argument must be in order to match this snippet definition. Allows you to match different usages of the same shortcode to separate snippet definitions based on the value of an argument.

**`implied_boolean`** Boolean

Output a boolean for whether this argument is present, rather than the value of the argument itself.

Only used for positional arguments.


---

---
title: Snippets using Hugo Shortcodes
description: Learn how to add and edit shortcodes in the content of your Hugo website via CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/snippets-using-hugo-shortcodes/
content_type: developer article
last_modified: 2026-03-29
---

CloudCannon supports embedding rich snippets in Markdown content when using the CloudCannon Content Editor. For sites built with Hugo, CloudCannon includes support for most of the built-in Hugo shortcodes without any configuration. Any existing shortcodes in your content will be presented as blocks in rich text views, with the ability to add the built-in shortcodes via the toolbar:

![The CloudCannon Content Editor toolbar showing the Insert Snippet button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Snippet-Toolbar.webp)

The builtin shortcodes can be configured via a `_snippets_imports` key in your CloudCannon global configuration file:

File: `cloudcannon.config.yml`

```YAML
```
_snippets_imports:
  hugo___1___: false
```

**[1]** Exclude all builtin Hugo shortcodes.
```

File: `cloudcannon.config.yml`

```YAML
```
_snippets_imports:
  hugo___1___:
    include:
      - hugo_youtube
      - hugo_vimeo
```

**[1]** Exclude all shortcodes by default, but import the youtube and vimeo shortcodes specifically.
```

File: `cloudcannon.config.yml`

```YAML
```
_snippets_imports:
  hugo___1___:
    exclude:
      - hugo_embed
```

**[1]** Import all shortcodes by default, but exclude the embed shortcode.
```

Hugo's `instagram` shortcode is excluded by default, as it is not functional without configuring an Instagram API key in your Hugo configuration. In other words, for sites configured to build with Hugo on CloudCannon, the following configuration will be applied by default:

File: `cloudcannon.config.yml`

```YAML
```
_snippets_imports:
  hugo___1___:
    exclude:
      - hugo_instagram
```

**[1]** The default snippet import for Hugo sites.
```

To override this default and import all shortcodes, set `hugo: true` in your global `_snippets_imports`:

File: `cloudcannon.config.yml`

```YAML
```
_snippets_imports:
  hugo___1___: true
```

**[1]** Force all shortcodes to be available.
```

## Enabling snippets in the toolbar

By default, CloudCannon will show the `snippet` toolbar action in the content editor if snippets are available.

> If you have already customized which options are available via `_editables` in your CloudCannon config, you will need to include `snippet: true` for Snippets to be available. See the [Editables options documentation](//documentation/developer-articles/configure-your-rich-text-editors/) for more details.

## Custom Hugo Shortcodes

By default, a custom shortcode in Hugo content will be displayed in the Content Editor as an `Unknown shortcode` or `Unknown shortcode pair`. This allows an editor to move and delete a shortcode, but prevents editing of its arguments or content:

![The Content Editor showing an Unknown Shortcode block for an unconfigured custom shortcode.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Unknown-Shortcode.webp)

To enable editing and provide the custom shortcode in the toolbar, your custom shortcode must be configured using the `_snippets` object in your CloudCannon global config file. CloudCannon Snippets can be built from scratch to support nearly any syntax or SSG, but a set of snippet templates are provided for Hugo shortcodes to cover most use cases in Hugo.

To help illustrate this configuration, we will first cover a few examples of custom shortcode configurations. First, let's look a custom `tint` shortcode on our Hugo site that takes a string and applies a color to it:

File: `post.md`

```markdown
# My Post

{{< tint "#ff0000" >}}This text should be red{{< /tint >}}

```

The first thing we need to do is decide which shortcode template to use, which we can determine from the following aspects:

- First, in Hugo terms this is a "paired" shortcode, since it has a start and end tag that wrap some content.
- Next, this shortcode takes "positional" arguments, so rather than using keys and values (like `color="#ff0000"`) we have the value `#ff0000` in the first position.
- Lastly, the fact that our shortcode uses the `<` and `>` characters means it outputs HTML, rather than the markdown that `%` characters would represent.

Looking at the list of [shortcode templates](#hugo-shortcode-templates) further down this page, this means we should configure this snippet using the `hugo_paired_shortcode_positional_args` template. A full example configuration for this shortcode thus might look like the following:

File: `cloudcannon.config.yml`

```YAML
_snippets:
  hugo_tint:
    template: hugo_paired_shortcode_positional_args
    inline: true
    preview:
      text: Tint
    definitions:
      shortcode_name: tint
      content_key: inner_text
      positional_args:
        - editor_key: tint_color
          type: string
    _inputs:
      tint_color:
        type: color
      inner_text:
        comment: This text will be tinted
```

Each snippet definition lives under a top level key, `hugo_tint` in this example. This is the unique name that CloudCannon uses to identify this snippet, but is otherwise unused in the shortcode configuration itself.

We specify the template that this snippet should inherit from, and also specify that it is an `inline` snippet, since it can live anywhere in the content (such as in the middle of a sentence).

In the `preview` object we configure how this snippet is displayed while editing, using the [CloudCannon card preview options](/documentation/developer-articles/configure-your-card-previews/).

In `definitions` we need to specify some values that are required for the template we picked. For the `hugo_paired_shortcode_positional_args` template, we need to specify:

- The `shortcode_name` — in this case we're configuring our `tint` shortcode
- The `content_key` — this controls the key that CloudCannon will use to edit the text in between the start and end tags of the shortcode.
- The `positional_args` — for our `tint` shortcode we need to configure that the first argument should be captured with the key `tint_color`

Finally, we can specify any other keys from the [CloudCannon configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/) here. In this example, we configure the inputs for the keys that this snippet will generate. With that in place, we can now add and edit our tint shortcode anywhere on our site.

![The Content Editor showing a Tint Snippet block selected with the data editor panel open, displaying Color and Inner Text inputs.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Snippet-Edit-Panel.webp)

Next, let's quickly look at a shortcode with a different syntax:

File: `post.md`

```markdown
# My Post

{{< callout type="info" message="This is my shortcode" >}}

```

This time, we have an unpaired shortcode that takes `type` and `message` argument keys. This syntax matches the `hugo_shortcode_named_args` template.

In CloudCannon, we could configure this snippet using the following global configuration:

File: `cloudcannon.config.yml`

```YAML
_snippets:
  callout:
    template: hugo_shortcode_named_args
    inline: false
    preview:
      text: Callout
    definitions:
      shortcode_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
```

This should now be familiar, but with a few changes:

- We want this snippet to be a block-level element in the editor, so we set `inline` to `false`.
- Since this shortcode does not have an end tag, we have no `content_key`
- Instead of `positional_args` we have `named_args`

Configuring our named arguments uses most of the same options as the positional arguments earlier, but here we can additionally specify `source_key` and `editor_key` separately. In this example, we want the key in our shortcode to be `type`, but tell CloudCannon to treat that value as the `label` key, which we then configure using our inputs configuration.

![The Content Editor showing a Callout Snippet block selected with the data editor panel open, displaying Label and Inner Text inputs.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Callout-Snippet-Edit-Panel.webp)

## Snippet options

The following options are available for Hugo shortcode snippets:

**`template`** String

The template that this snippet should inherit, out of the available [Hugo Shortcode Templates](#hugo-shortcode-templates).

**`definitions`** Object

The variables required for the selected template.

**`inline`** Boolean

Whether this shortcode can appear inline (within a sentence). Defaults to `false`, which will treat this shortcode as a block-level element in the content editor.

**`preview`** Object

A preview definition for displaying this shortcode in the CloudCannon editor. See the [preview options documentation](/documentation/developer-articles/configure-your-card-previews/).

**`_inputs`** Object

Input configurations for the keys contained in this shortcode. See the [input configuration documentation](/documentation/user-articles/what-are-inputs/).

## Hugo Shortcode Templates

Hugo allows a range of shortcode syntaxes, and each has a matching shortcode template provided by CloudCannon.

The first step to configure your custom shortcode is to identify which shortcode template to use, as each shortcode template requires a set of `definitions` keys to be configured. The following shortcode templates are available:

### Shortcode with positional arguments

File: `example.md`

```markdown
# hugo_shortcode_positional_args
{{< custom_shortcode arg1 arg2 >}}

# hugo_markdown_shortcode_positional_args
{{% custom_shortcode arg1 arg2 %}}
```

#### Example config

File: `cloudcannon.config.yml`

```YAML
_snippets:
  custom_snippet:
    template: hugo_shortcode_positional_args
    inline: false
    preview:
      text: My Custom Snippet
    definitions:
      shortcode_name: custom_shortcode
      positional_args:
        - editor_key: argument_one
          type: string
        - editor_key: argument_two
          type: string
```

#### Definitions

**`shortcode_name`** String

The name of your shortcode, as used in your Hugo content files.

**`positional_args`** Array of [argument options](#argument-options)

An ordered list of each argument the shortcode takes.

### Paired shortcode with positional arguments

File: `example.md`

```markdown
# hugo_paired_shortcode_positional_args
{{< custom_shortcode arg1 arg2 >}} content {{< /custom_shortcode >}}

# hugo_paired_markdown_shortcode_positional_args
{{% custom_shortcode arg1 arg2 %}} content {{% /custom_shortcode %}}
```

#### Example config

File: `cloudcannon.config.yml`

```YAML
_snippets:
  custom_snippet:
    template: hugo_paired_shortcode_positional_args
    inline: false
    preview:
      text: My Custom Snippet
    definitions:
      shortcode_name: custom_shortcode
      content_key: custom_key
      positional_args:
        - editor_key: argument_one
          type: string
        - editor_key: argument_two
          type: string
```

#### Definitions

**`shortcode_name`** String

The name of your shortcode, as used in your Hugo content files.

**`content_key`** String

The key to use in the data panel for editing the inner contents of the shortcode.

**`positional_args`** Array of [argument options](#argument-options)

An ordered list of each argument the shortcode takes.

### Shortcode with named arguments

File: `example.md`

```markdown
# hugo_shortcode_named_args
{{< custom_shortcode arg="value" >}}

# hugo_markdown_shortcode_named_args
{{% custom_shortcode arg="value" %}}
```

#### Example config

File: `cloudcannon.config.yml`

```YAML
_snippets:
  custom_snippet:
    template: hugo_shortcode_named_args
    inline: false
    preview:
      text: My Custom Snippet
    definitions:
      shortcode_name: custom_shortcode
      named_args:
        - editor_key: arg
          type: string
```

#### Definitions

**`shortcode_name`** String

The name of your shortcode, as used in your Hugo content files.

**`named_args`** Array of [argument options](#argument-options)

A list of each key-value pair the shortcode takes.

### Paired shortcode with named arguments

File: `example.md`

```markdown
# hugo_paired_shortcode_named_args
{{< custom_shortcode arg="value" >}} content {{< /custom_shortcode >}}

# hugo_paired_markdown_shortcode_named_args
{{% custom_shortcode arg="value" %}} content {{% /custom_shortcode %}}
```

#### Example config

File: `cloudcannon.config.yml`

```YAML
_snippets:
  custom_snippet:
    template: hugo_paired_shortcode_named_args
    inline: false
    preview:
      text: My Custom Snippet
    definitions:
      shortcode_name: custom_shortcode
      content_key: custom_key
      named_args:
        - editor_key: arg
          type: string
```

#### Definitions

**`shortcode_name`** String

The name of your shortcode, as used in your Hugo content files.

**`content_key`** String

The key to use in the data panel for editing the inner contents of the shortcode.

**`named_args`** Array of [argument options](#argument-options)

A list of each key-value pair the shortcode takes.

## Argument options

The following options are available for positional and named argument option objects:

**`editor_key`** String

Determines the key that will be used for this argument in the CloudCannon data panel.

**`source_key`** String

Determines the key of the key-value pair as it appears in the shortcode.

Only used for named arguments, and will default to the `editor_key` if unset.

**`default`** Any

The default value that should be used for this argument when creating a new snippet in the CloudCannon editor.

**`type`** String

Restrict this argument to parse as the specified type. Useful to ensure booleans get parsed as the boolean value, rather than a string such as "true".

One of:

- string
- boolean
- number
- array

**`optional`** Boolean

Whether this argument is required for the shortcode. If `false`, shortcodes in your templates missing this argument will not match this snippet definition.

Defaults to `false`.

**`remove_empty`** Boolean

Whether this argument should be omitted from the output shortcode if the value is empty.

Only used for named arguments, defaults to `false`.

**`allowed_values`** Array of values

A list of values that this argument must be in order to match this snippet definition. Allows you to match different usages of the same shortcode to separate snippet definitions based on the value of an argument.

**`implied_boolean`** Boolean

Output a boolean for whether this argument is present, rather than the value of the argument itself.

Only used for positional arguments.


---

---
title: Snippets using MDX Components
description: Learn how to add and edit components in the content of your MDX website via CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/snippets-using-mdx-components/
content_type: developer article
last_modified: 2026-03-29
---

CloudCannon supports embedding rich Snippets in Markdown content when using the CloudCannon Content Editor. Once configured,  Snippets in your content will be presented as blocks in rich text views, with the ability to add them as Snippets via the toolbar:

![The CloudCannon Content Editor toolbar showing the Insert Snippet button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Snippet-Toolbar.webp)

To start configuring Components in your MDX content, a Snippet configuration must be imported using the `_snippets_imports` key in your CloudCannon global configuration file.

File: `cloudcannon.config.yml`

```YAML
# Import the MDX Components Snippets:
_snippets_imports:
  mdx: true

```

## Enabling snippets in the toolbar

By default, CloudCannon will show the `snippet` toolbar action in the content editor if snippets are available.

> If you have already customized which options are available via `_editables` in your CloudCannon config, you will need to include `snippet: true` for Snippets to be available. See the [Editables options documentation](/documentation/developer-articles/configure-your-rich-text-editors/) for more details.

## Custom MDX Components

After importing the `mdx` Snippets configurations, any custom components in your content will be displayed in the Content Editor as an `Unknown Component`. This allows an editor to move and delete a Component, but prevents editing of its arguments or content:

![The Content Editor showing an Unknown Shortcode block for an unconfigured custom component.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Unknown-Shortcode.webp)

To enable editing and provide the custom component in the toolbar, your custom component must be configured using the `_snippets` object in your CloudCannon global config file. CloudCannon Snippets can be built from scratch to support nearly any syntax or SSG, but importing a Snippet configuration provides a set of snippet templates for common use cases in MDX.

To help illustrate configuring custom Snippets, we will first cover a few examples. First, let's look a custom `Tint` component on our MDX site that takes a string and applies a color to it:

File: `post.md`

```markdown
# My Post

<Tint tint_color="#ff0000">This text should be red</Tint>

```

The first thing we need to do is decide which Snippet template to use. Looking at the list of [snippet templates](#mdx-component-templates) further down this page, we see that MDX has two templates `mdx_component` and `mdx_paired_component`. Our component has child content so we should configure this snippet using the `mdx_paired_component` template. A full example configuration for this Snippet thus might look like the following:

File: `cloudcannon.config.yml`

```YAML
# Import the MDX Snippet templates
_snippets_imports:
  mdx: true

_snippets:
  mdx_tint:
    template: mdx_paired_component
    inline: true
    preview:
      text: Tint
    definitions:
      component_name: tint
      content_key: inner_text
      named_args:
        - editor_key: color
          source_key: tint_color
          type: string
    _inputs:
      tint_color:
        type: color
      inner_text:
        comment: This text will be tinted
```

Each snippet definition lives under a top level key, `mdx_tint` in this example. This is the unique name that CloudCannon uses to identify this snippet, but is otherwise unused in the component configuration itself.

We specify the template that this snippet should inherit from, and also specify that it is an `inline` snippet, since it can live anywhere in the content (such as in the middle of a sentence).

In the `preview` object we configure how this snippet is displayed while editing, using the [CloudCannon card preview options](/documentation/developer-articles/configure-your-card-previews/).

In `definitions` we need to specify some values that are required for the template we picked. For the `mdx_paired_component` template, we need to specify:

- The `component_name` — in this case we're configuring our `tint` component.
- The `content_key` — this controls the key that CloudCannon will use to edit the text in between the start and end tags of the component.
- The `named_args` — for our `tint` component we need to configure that the `tint_color` should be captured with the key `color`

Finally, we can specify any other keys from the [CloudCannon configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/) here. In this example, we configure the inputs for the keys that this snippet will generate. With that in place, we can now add and edit our tint component anywhere on our site.

![The Content Editor showing a Tint Snippet block selected with the data editor panel open, displaying Color and Inner Text inputs.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Snippet-Edit-Panel.webp)

Next, let's quickly look at a component with a different syntax:

File: `post.md`

```markdown
# My Post

<Callout type="info" message="This is my component"/>

```

This time, we have an unpaired component that takes `type` and `message` argument keys. This syntax matches the `mdx_component` template.

In CloudCannon, we could configure this component using the following global configuration:

File: `cloudcannon.config.yml`

```YAML
_snippets:
  callout:
    template: mdx_component
    inline: false
    preview:
      text: Callout
    definitions:
      component_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
```

This should now be familiar, but with a few changes:

- We want this snippet to be a block-level element in the editor, so we set `inline` to `false`.
- Since this component does not have an end tag, we have no `content_key`

In this example, we want the key in our component to be `type`, but tell  CloudCannon to treat that value as the `label` key, which we then configure using our inputs configuration.

![The Content Editor showing a Callout Snippet block selected with the data editor panel open, displaying Label and Inner Text inputs.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Callout-Snippet-Edit-Panel.webp)

## Snippet options

The following options are available for MDX component snippets:

**`template`** String

The template that this snippet should inherit, out of the available [MDX Component Templates](#mdx-component-templates).

**`definitions`** Object

The variables required for the selected template.

**`inline`** Boolean

Whether this component can appear inline (within a sentence). Defaults to `false`, which will treat this component as a block-level element in the content editor.

**`preview`** Object

A preview definition for displaying this component in the CloudCannon editor. See the [preview options documentation](/documentation/developer-articles/configure-your-card-previews/).

**`_inputs`** Object

Input configurations for the keys contained in this component.

## MDX Component Templates

The first step to configure your custom component is to identify which component template to use, as each component template requires a set of `definitions` keys to be configured. The following component templates are available:

### Component with named arguments

File: `example.md`

```markdown
<CustomComponent arg1="my arg1" arg2="my arg2"/>
```

#### Example config

File: `cloudcannon.config.yml`

```YAML
_snippets:
  custom_snippet:
    template: mdx_component
    inline: false
    preview:
      text: My Custom Component
    definitions:
      component_name: CustomComponent
      named_args:
        - editor_key: arg1
          type: string
        - editor_key: arg2
          type: string
```

#### Definitions

**`component_name`** String

The name of your component, as used in your MDX content files.

**`named_args`** Array of [argument options](#argument-options)

A list of each key-value pair the component takes.

### Paired component with named arguments

File: `example.md`

```markdown
<CustomComponent arg1="my arg1" arg2="my arg2"> content </CustomComponent>
```

#### Example config

File: `cloudcannon.config.yml`

```YAML
_snippets:
  custom_snippet:
    template: mdx_paired_component
    inline: false
    preview:
      text: My Custom Component
    definitions:
      component_name: CustomComponent
      content_key: custom_key
      named_args:
        - editor_key: arg1
          type: string
        - editor_key: arg2
          type: string
```

#### Definitions

**`component_name`** String

The name of your component, as used in your MDX content files.

**`content_key`** String

The key to use in the data panel for editing the inner contents of the component.

**`named_args`** Array of [argument options](#argument-options)

A list of each key-value pair the component takes.

## Argument options

The following options are available for named argument option objects:

**`editor_key`** String

Determines the key that will be used for this argument in the CloudCannon data panel.

**`source_key`** String

Determines the key of the key-value pair as it appears in the component.

Will default to the `editor_key` if unset.

**`default`** Any

The default value that should be used for this argument when creating a new snippet in the CloudCannon editor.

**`type`** String

Restrict this argument to parse as the specified type. Useful to ensure booleans get parsed as the boolean value, rather than a string such as "true".

One of:

- string
- boolean
- number
- array

**`optional`** Boolean

Whether this argument is required for the component. If `false`, components in your templates missing this argument will not match this snippet definition.

Defaults to `false`.

**`remove_empty`** Boolean

Whether this argument should be omitted from the output component if the value is empty.

Defaults to `false`.

**`allowed_values`** Array of values

A list of values that this argument must be in order to match this snippet definition. Allows you to match different usages of the same component to separate snippet definitions based on the value of an argument.


---

---
title: Snippets using Python Markdown
description: Learn how to add and edit snippets in the content of your Python website via CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/snippets-using-python-markdown/
content_type: developer article
last_modified: 2026-03-29
---

CloudCannon supports embedding rich Snippets in Markdown content when using the CloudCannon Content Editor. Once configured, Snippets in your content will be presented as blocks in rich text views, with the ability to add them as Snippets via the toolbar:

![The CloudCannon Content Editor toolbar showing the Insert Snippet button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Snippet-Toolbar.webp)

To start configuring Snippets in your Markdown content, a Snippet configuration must be imported using the `_snippets_imports` key in your CloudCannon global configuration file.
Your SSG and theme may not enable the full set of Python Markdown extensions so we recommend using the `include` option to import only the Snippets you're using.

File: `cloudcannon.config.yml`

```YAML
# Import the Python MarkdownSnippets:
_snippets_imports:
  python_markdown_extensions:
    include:
      - ...

```

## Enabling snippets in the toolbar

By default, CloudCannon will show the `snippet` toolbar action in the content editor if snippets are available.

> If you have already customized which options are available via `_editables` in your CloudCannon config, you will need to include `snippet: true` for Snippets to be available. See the [Editables options documentation](//documentation/developer-articles/configure-your-rich-text-editors/) for more details.

## Supported extensions

### Abbreviations

The Abbreviation snippet allows you to add standard [Python Markdown abbreviations](https://python-markdown.github.io/extensions/abbreviations/) to your content.

File: `example.md`

```
The HTML specification is maintained by the W3C.

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

```

#### Example Config

File: `cloudcannon.config.yml`

```YAML
# Import the Python MarkdownSnippets:
_snippets_imports:
  python_markdown_extensions:
    include:
      - python_markdown_abbreviation
```

### Admonitions

The Admonition snippet allows you to add standard [Python Markdown admonitions](https://python-markdown.github.io/extensions/admonition/) to your content.
In addition, collapsible admonitions from the [Details extension](https://facelessuser.github.io/pymdown-extensions/extensions/details/) are supported
with the Collapsible Admonition snippet:

File: `example.md`

```
!!! note

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.
```

File: `example.md`

```
??? note

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.
```

#### Example Config

File: `cloudcannon.config.yml`

```YAML
# Import the Python MarkdownSnippets:
_snippets_imports:
  python_markdown_extensions:
    include:
      - python_markdown_admonition
      - python_markdown_collapsible_admonition
```

### Code Blocks

CloudCannon supports both fenced codeblocks with the Code Block snippet, and inline code highlighting from
the [InlineHilite extension](https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/) with the
Inline Code snippet:

File: `example.md`

```
```py title="bubble_sort.py"
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```
```

File: `example.md`

```
The `#!python range()` function is used to generate a sequence of numbers.
```

#### Example Config

File: `cloudcannon.config.yml`

```YAML
# Import the Python MarkdownSnippets:
_snippets_imports:
  python_markdown_extensions:
    include:
      - python_markdown_code_block
      - python_markdown_inline_code
```

### Content Tabs

The Tabs snippet supports creating tabbed content using the [Tabbed extension](https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/).

File: `example.md`

```
=== "Unordered list"

    * Sed sagittis eleifend rutrum
    * Donec vitae suscipit est
    * Nulla tempor lobortis orci

=== "Ordered list"

    1. Sed sagittis eleifend rutrum
    2. Donec vitae suscipit est
    3. Nulla tempor lobortis orci
```

#### Example Config

File: `cloudcannon.config.yml`

```YAML
# Import the Python MarkdownSnippets:
_snippets_imports:
  python_markdown_extensions:
    include:
      - python_markdown_tabs
```

### Footnotes

Footnote support consists of two snippets, a footnote snippet and a footnote marker snippet.
The footnote snippets lets you define the content of a footnote, and then the marker snippet allows
you to reference a footnote in text.

File: `example.md`

```
Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.

[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
```

#### Example Config

File: `cloudcannon.config.yml`

```YAML
# Import the Python MarkdownSnippets:
_snippets_imports:
  python_markdown_extensions:
    include:
      - python_markdown_footnote
      - python_markdown_footnote_marker
```

### Icons

The Icon snippet adds support for adding graphics with the [Emoji extension](https://facelessuser.github.io/pymdown-extensions/extensions/emoji/).

File: `example.md`

```
:smile: :heart: :thumbsup:
```

#### Example Config

File: `cloudcannon.config.yml`

```YAML
# Import the Python MarkdownSnippets:
_snippets_imports:
  python_markdown_extensions:
    include:
      - python_markdown_icon
```

### Arithmatex

The Arithmatex snippets allow you to insert LaTeX style math equations which work with the [Arithmatex extension](https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/).

File: `example.md`

```
$$
\operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}}
$$

The homomorphism $f$ is injective if and only if its kernel is only the 
singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such 
that $f(a)=f(b)$.
```

#### Example Config

File: `cloudcannon.config.yml`

```YAML
# Import the Python MarkdownSnippets:
_snippets_imports:
  python_markdown_extensions:
    include:
      - python_markdown_arithmatex
      - python_markdown_inline_arithmatex
```

### Reference links

The first part of reference-style links support is the reference snippet, which allows you to create a named reference
and set its URL.

File: `example.md`

```
[my-reference]: markdownguide.org/basic-syntax/#reference-style-links
[my-image]: example.com/image.png
```

You can then use that reference in links in your page using the reference link snippet, or the reference template snippet
if your link title is the same as the reference name. If you're using reference links you must also include the regular link
snippet.

File: `example.md`

```
[my-reference]
[My link text][my-reference]
```

You can also use references in images with the reference image snippet, or the reference template image snippet
if image text is the same as the reference name. If you're using reference images you must also include the regular image
snippet.

File: `example.md`

```
![my-image]
![My image text][my-image]
```

File: `cloudcannon.config.yml`

```YAML
# Import the Python MarkdownSnippets:
_snippets_imports:
  python_markdown_extensions:
    include:
      - python_markdown_reference
      - python_markdown_reference_link
      - python_markdown_reference_image
      - python_markdown_link
      - python_markdown_image
      - python_markdown_reference_template_image
      - python_markdown_reference_template
```

## Custom Snippets

Some Python extensions don't work out of the box and require additional configuration. These are the [Snippet extension](https://facelessuser.github.io/pymdown-extensions/extensions/snippets/) and the [Markdown in HTML extension](https://python-markdown.github.io/extensions/md_in_html/).
By default any instance of these extensions will be escaped into either an HTML element or an Unknown Snippet, this allows an editor to move and delete these Snippets, but prevents editing of their arguments or content:

![The Content Editor showing an unknown HTML block that cannot be edited.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Unknown-HTML-Block.webp)

To enable editing and provide the custom snippet in the toolbar, your custom snippet must be configured using the `_snippets` object in your CloudCannon global config file. CloudCannon Snippets can be built from scratch to support nearly any syntax or SSG, but importing a Snippet configuration provides a set of snippet templates for common use cases in Python Markdown.

To help illustrate configuring custom Snippets, we will first cover a few examples. First, let's look a custom glossary snippet that includes a set of abbreviations for our site:

File: `post.md`

```markdown
# My Post

--8<-- "glossary.html"

```

The first thing we need to do is decide which Snippet template to use. Looking at the list of [snippet templates](#python-markdown-templates)
further down this page, we see that Python Markdown has two templates `python_markdown_snippet` and `python_markdown_markdown_in_html`.
Our glossary is using the Snippet extension so we should configure this snippet using the `python_markdown_snippet` template. A full example configuration for this Snippet thus might look like the following:

File: `cloudcannon.config.yml`

```YAML
# Import the Python Markdown Snippet templates
_snippets_imports:
  python_markdown_extensions:

_snippets:
  glossary:
    template: python_markdown_snippet
    inline: false
    preview:
      text: Glossary
    definitions:
      snippet_name: glossary.html
```

Each snippet definition lives under a top level key, `glossary` in this example. This is the unique name that CloudCannon uses to identify this snippet, but is otherwise unused in the snippet configuration itself.

We specify the template that this snippet should inherit from, and also specify that it is not an `inline` snippet, so it can only be used on a line on its own.

In the `preview` object we configure how this snippet is displayed while editing, using the [CloudCannon card preview options](/documentation/developer-articles/configure-your-card-previews/).

In `definitions` we need to specify some values that are required for the template we picked. For the `python_markdown_snippet` template, we need to specify:

- The `snippet_name` — in this case we're configuring a snippet for the `glossary.html` file.

Finally, we can specify any other keys from the [CloudCannon configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/) here. In this example, we configure the inputs for the keys that this snippet will generate. With that in place, we can now add and edit our glossary snippet anywhere on our site.

![The Content Editor showing a Glossary Snippet block.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Python-Snippet-Glossary.webp)

Next, let's quickly look at a snippet using Markdown in HTML:

File: `post.md`

```markdown
# My Post

<figure markdown class="diagram">
  [My figure](figure.png)
  An example of a figure
</figure>

```

This time, we have an HTML figure with a class attribute of diagram and we want to be able to edit its contents in Markdown. This syntax matches the `python_markdown_markdown_in_html` template.

In CloudCannon, we could configure this snippet using the following global configuration:

File: `cloudcannon.config.yml`

```YAML
_snippets_imports:
  python_markdown_extensions:
_snippets:
  diagram:
    template: python_markdown_markdown_in_html
    inline: false
    preview:
      text: Diagram
    definitions:
      tag_name: figure
      content_key: content
      tag_attributes:
        - source_key: class
          type: string
          default: diagram
          allowed_values:
            - diagram
```

In this example, we want to ensure that our block has a class of `diagram` but we don't want the class to be editable in CloudCannon. By using `source_key` with no `editor_key` we prevent
the class from being editable in CloudCannon, then the `default` and `allowed_values` settings ensure that all instances of this snippet have class `diagram`.

![The Content Editor showing a Diagram Snippet block selected with the data editor panel open, displaying the Content input.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Python-Snippet-Diagram-Edit-Panel.webp)

## Snippet options

The following options are available for custom snippets:

**`template`** String

The template that this snippet should inherit, out of the available [Python Markdown Templates](#python-markdown-templates).

**`definitions`** Object

The variables required for the selected template.

**`inline`** Boolean

Whether this snippet can appear inline (within a sentence). Defaults to `false`, which will treat this snippet as a block-level element in the content editor.

**`preview`** Object

A preview definition for displaying this snippet in the CloudCannon editor. See the [preview options documentation](/documentation/developer-articles/configure-your-card-previews/).

**`_inputs`** Object

Input configurations for the keys contained in this snippet.

## Python Markdown Templates

The first step to configure your custom snippet is to identify which snippet template to use, as each snippet template requires a set of `definitions` keys to be configured. The following snippet templates are available:

### Snippets

File: `example.md`

```markdown
--8<-- "filename.ext"
```

#### Example config

File: `cloudcannon.config.yml`

```YAML
_snippets:
  custom_snippet:
    template: python_markdown_snippet
    inline: false
    preview:
      text: My Custom Snippet
    definitions:
      snippet_name: filename.ext
```

#### Definitions

**`snippet_name`** String

The file name of the snippet that you want to include.

### Markdown in HTML

File: `example.md`

```markdown
<div markdown class="result">
This is a *Markdown* Paragraph.
</div>
```

#### Example config

File: `cloudcannon.config.yml`

```YAML
_snippets:
  custom_html:
    template: python_markdown_markdown_in_html
    inline: false
    preview:
      text: My Custom HTML
    definitions:
      tag_name: div
      content_key: content
      tag_attributes:
        - source_key: class
          default: result
          allowed_values:
            - result
```

#### Definitions

**`tag_name`** String

The HTML tag name of your element.

**`content_key`** String

The key to use in the data panel for editing the inner contents of the element.

**`tag_attributes`** Array of [argument options](#argument-options)

A list of the HTML attributes to include on your element.

## Argument options

The following options are available for named argument option objects:

**`editor_key`** String

Determines the key that will be used for this argument in the CloudCannon data panel.

**`source_key`** String

Determines the key of the key-value pair as it appears in the shortcode.

Will default to the `editor_key` if unset.

**`default`** Any

The default value that should be used for this argument when creating a new snippet in the CloudCannon editor.

**`type`** String

Restrict this argument to parse as the specified type. Useful to ensure booleans get parsed as the boolean value, rather than a string such as "true".

One of:

- string
- boolean
- number
- array

**`optional`** Boolean

Whether this argument is required for the shortcode. If `false`, shortcodes in your templates missing this argument will not match this snippet definition.

Defaults to `false`.

**`remove_empty`** Boolean

Whether this argument should be omitted from the output shortcode if the value is empty.

Defaults to `false`.

**`allowed_values`** Array of values

A list of values that this argument must be in order to match this snippet definition. Allows you to match different usages of the same shortcode to separate snippet definitions based on the value of an argument.


---

---
title: Split your Configuration File
description: Learn how to split your Site configuration across multiple files.
url: https://cloudcannon.com/documentation/developer-articles/split-your-configuration-file/
content_type: developer article
last_modified: 2026-02-10
---

> **Permissions required**
> 
> Members of the Owners, Developers, or Technical Editors [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `site:source-editor:write` and `site:file:write`permissions, can edit your *CloudCannon Configuration File*. You can limit permission to specific files using [file globs](/documentation/developer-articles/what-are-custom-permission-groups/#specify-a-file-glob).

You can split your [CloudCannon Configuration File](/documentation/developer-articles/what-is-the-cloudcannon-configuration-file/) into multiple files for easier maintenance. For more information, please read our documentation on [why you might split your Configuration File](/documentation/developer-articles/why-split-your-configuration-file/), [best practices for splitting your configuration](/documentation/developer-articles/best-practice-for-splitting-your-configuration-file/), and [defining the same key in multiple Configuration Files](/documentation/developer-articles/defining-the-same-key-in-multiple-configuration-files/).

These instructions assume your *Site* uses [Unified Configuration](/documentation/developer-guides/unified-configuration-migration-guide/).

To split your *CloudCannon Configuration File*:

1. Navigate to your *File Browser* and open your *CloudCannon Configuration File* in the Source Editor, or open it in your local development environment.
2. Identify the configuration key you want to split out into a new file (e.g., a *Collection* under `collections_config`).
3. Copy all the configuration content under the key to a new file with the appropriate `.cloudcannon.[].yml` file extension.
4. Reference the location of the new *Configuration File* (relative to the root of your repository) in the original *Configuration File* using the appropriate `*_from_glob` key. If the original *Configuration File* is not your main *CloudCannon Configuration File* (i.e., `cloudcannon.config.yml`), ensure that every *Configuration File* ultimately connects back to your main *Configuration File* using `*_from_glob` keys.
5. Save the changes to your *Site*.

Whenever you load your *Site* or update a *Configuration File*, CloudCannon will merge your configuration and apply it to your *Site*.

## Configuration keys

CloudCannon allows you to split the specific configuration keys into separate *Configuration Files*. Here is an example of two *Configuration Files* using some of the most commonly used keys for splitting configuration.

File: `cloudcannon.config.yml`

```YAML

source: /
collections_config_from_glob:
  - '/.cloudcannon/collections/*.cloudcannon.collections.yml'
_inputs_from_glob:
  - '/.cloudcannon/inputs/*.cloudcannon.inputs.yml'
_structures_from_glob:
  - '/.cloudcannon/structures/*.cloudcannon.structures.yml'

```

File: `/.cloudcannon/collections/posts.cloudcannon.collections.yml`

```YAML

posts:
  path: src/content/
  schemas_from_glob:
    - '/.cloudcannon/schemas/blogPost.cloudcannon.schemas.yml'
    - '/.cloudcannon/schemas/companyAnnouncement.cloudcannon.schemas.yml'
    - '/.cloudcannon/schemas/caseStudy.cloudcannon.schemas.yml'

```

For a complete list of configuration keys available for the *CloudCannon Configuration File*, please read our [Configuration File](/documentation/developer-reference/configuration-file/) reference documentation.

These keys configure which files CloudCannon should use for *Site* configuration.

**`collections_config_from_glob`** Array of Strings

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`. You can use this key anywhere you would use the `collections_config` key.

This key has no default.

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

File: `cloudcannon.config.yml`

```YAML
collections_config_from_glob:
  - '/.cloudcannon/collections/*.cloudcannon.collections.yml'
```

File: `/.cloudcannon/collections/posts.cloudcannon.collections.yml`

```YAML
posts:
  path: content/posts
  icon: event
```

**`schemas_from_glob`** Array of Strings

This key defines globs that filter which files CloudCannon should use for *Schema* 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.schemas.yml`. You can use this key anywhere you would use the `schemas` key.

This key has no default.

In this example, we have several *Schemas Configuration Files* in the `.cloudcannon/schemas/` folder. The value of the `schemas_from_glob` key tells CloudCannon to use all files in that folder that match the glob `*.cloudcannon.schemas.yml` except for `pages.cloudcannon.schemas.yml` due to the negative glob.

File: `/.cloudcannon/collections/posts.cloudcannon.collections.yml`

```YAML
posts:
  path: content/posts
  icon: event
  schemas_from_glob:
    - '/.cloudcannon/schemas/*.cloudcannon.schemas.yml'
    - '!/.cloudcannon/schemas/pages.cloudcannon.schemas.yml'
```

**`_inputs_from_glob`** Array of Strings

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.

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.

File: `cloudcannon.config.yml`

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

File: `/.cloudcannon/inputs/seo.cloudcannon.inputs.yml`

```YAML
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
```

**`_structures_from_glob`** Array of Strings

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](/documentation/developer-reference/configuration-file/types/structure/values_from_glob/) for defining individual *Structure* values in a split *Configuration File*.

This key has no default.

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.

File: `cloudcannon.config.yml`

```YAML
_structures_from_glob:
  - '/.cloudcannon/structures/staffMembers.cloudcannon.structures.yml'
```

File: `/.cloudcannon/structures/staffMembers.cloudcannon.structures.yml`

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

**`values_from_glob`** Array of Strings

This key defines globs that filter which files CloudCannon should use for *Structure* value 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.structure-value.yml` (note the singular form of "value"). You can use this key anywhere you would use the `_structures.*.values` key. Please see our documentation on [structures_from_glob](/documentation/developer-reference/configuration-file/types/_structures_from_glob/) for defining a *Structure* in a split *Configuration File*.

This key has no default.

In this example, the `staff` Array Input uses inline *Structure* values from the main *Configuration File* and also references another value from the `boardMember.cloudcannon.structure_value.yml` in the `/.cloudcannon/structures/` folder.

File: `cloudcannon.config.yml`

```YAML
_inputs:
  staff:
    type: array
    options:
      structures:
      values_from_glob: /.cloudcannon/structures/boardMember.cloudcannon.structure-value.yml
      values:
        - label: Employee
          value:
            name:
            title:
            profile_picture:
        - label: Manager
          value:
            name:
            title:
            profile_picture:
            url:
```

File: `/.cloudcannon/structures/boardMember.cloudcannon.structure-value.yml`

```YAML
label: Board
value:
  name:
  title:
  profile_picture:
  url:
  description:
```

**`_snippets_from_glob`** Array of Strings

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.

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.

File: `cloudcannon.config.yml`

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

File: `/.cloudcannon/snippets/callout.cloudcannon.snippets.yml`

```YAML
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_from_glob`** Array of Strings

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

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

File: `cloudcannon.config.yml`

```YAML
_snippets_imports_from_glob:
  - '/.cloudcannon/snippets/*.cloudcannon.snippets-imports.yml'

```

File: `/.cloudcannon/snippets/docusaurusSnippets.cloudcannon.snippets-imports.yml`

```YAML
mdx: true
docusaurus_mdx:
  exclude:
    - docusaurus_mdx_truncate
```

**`_editables_from_glob`** Array of Strings

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.

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

File: `cloudcannon.config.yml`

```YAML
_editables_from_glob:
  - '/.cloudcannon/editables/*.cloudcannon.editables.yml'
```

File: `/.cloudcannon/editables/textEditableRegions.cloudcannon.editables.yml`

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

## Common errors

If you have any questions about configuring your *Site* on CloudCannon, don't hesitate to contact our friendly [support team](/support/).

### *Site* configuration is not loading

- Check that the glob pattern in your `*_from_glob` key correctly matches the name of your *Configuration File*.
- Check that the value of your `*_from_glob` key references the correct file extension (e.g., `collections_config_from_glob` must reference a file with the `.cloudcannon.collections.yml` extension).
- Ensure that the value of `*_from_glob` is relative to the root repository, not the source directory.
- Verify that your *Site* uses [Unified Configuration](/documentation/developer-guides/unified-configuration-migration-guide/).

### One configuration is unexpectedly overwriting another

- Check where you have defined you configuration. If you have defined a configuration key multiple times at the same level of the [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/), CloudCannon will preferentially use the configuration defined in files later in the [import order](/documentation/developer-articles/defining-the-same-key-in-multiple-configuration-files) (i.e., inline configuration first, followed by configuration from other files in Unicode order).

### Array items are missing

- Check that the glob pattern in your `*_from_glob` key correctly matches the name of your *Configuration File*.
- Array items referenced in another *Configuration File* using a `*_from_glob` key are appended to any array items defined in your main *Configuration File*. Check all array items are present in the files referenced by your `values_from_glob` key.


---

---
title: Structures in the configuration cascade
description: Learn how to create a structure at any level of the configuration cascade.
url: https://cloudcannon.com/documentation/developer-articles/structures-in-the-configuration-cascade/
content_type: developer article
last_modified: 2026-03-29
---

[Structures](/documentation/developer-articles/what-is-a-structure/) are part of the CloudCannon [configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/). You can configure them for your site as a whole and for a specific page or collection. You can define your structures in the following places:

1. [The CloudCannon Configuration File](/documentation/developer-articles/create-your-cloudcannon-configuration-file/)
2. [Collection configuration](/documentation/developer-articles/configure-your-collections/)
3. [Schema configuration](/documentation/developer-articles/create-a-schema)
4. File front matter
5. Within another [structure](/documentation/developer-articles/what-is-a-structure/)

When you define a structure in multiple places, CloudCannon uses the highest priority source and does not merge the structures. For example, a structure defined in the front matter of a file will take priority over one defined in collections.

## Define a structure at the collection level

To configure for an individual collection, use the `_structures` key under your collection in `collections_config`.

Here is a structure configuration for the collection Blog:

File: `cloudcannon.config.yml`

```YAML
```
collections_config___1___:
  blog___2___:
    _structures___3___:
      example___4___:
        style: select
        values:
          - label: Product
            value:
              name:
              description:
              image:
```

**[1]** The `collections_config` key contains all the collections and any configuration for those collections.

**[2]** The `blog` key matches our collection “Blog”.

**[3]** The `_structures` key contains all the structures defined at a given level of the configuration cascade. In this code, structures defined here will only be available inside the collection “blog”.

**[4]** The key name for our structure group is `example`. Under example we have defined a single structure labelled “Product” with the fields for `name`, `description`, and `image`.
```

The structures defined under the key `example` will only be available for array or object inputs in the collection "Blog".

## Define a structure within another structure

You can nest structures by defining a structure within another structure. These “sub-structures” will only affect arrays within the containing structure.

For this example, we want to create a page builder called `page_sections`. Within the structure for the `page_sections` array, let’s create an option for a hero, content, and call-to-action section. Then, within the option for `content`, let’s define a second structure for the array `elements`. The `elements` structure will have the options for text and image.

Here is our structure configuration:

File: `home.md`

```markdown
---
page_sections: []
---
```

File: `cloudcannon.config.yml`

```YAML
```
_inputs___1___:
  page_sections___2___:
    type: array
    options:
      structures: _structures.page_sections

_structures___3___:
  page_sections___4___:
    values:
      - label: Hero
        icon: title
        value:
          _type: hero
          title:
          description:
      - label___5___: Content
        icon: subject
        value:
          _type: content
          content___6___: []
        _inputs___7___:
          content:
            type: array
            options:
              structures: _structures.elements
        _structures___8___:
          elements___9___:
            values:
              - label: Text
                icon: article
                value:
                  content:
                _inputs:
                  content:
                    type: textarea
              - label: Image
                icon: image
                value:
                  image:
                  description:
      - label: Call to action
        icon: smart_button
        value:
          _type: cta
          url:
          content:
```

**[1]** The `_inputs` key contains all the inputs defined at a given level of the configuration cascade.

**[2]** The key name of the array or object input which contains the sub-structure. In this code, we have called our input `page_sections`. The `options.structures` key is set to `_structures.page_sections`.

**[3]** The `_structures` key contains all the structures defined at a given level of the configuration cascade.

**[4]** The key name of your structure. In this code, we have called our structure `page_sections`.

**[5]** Under the key `page_sections` we have defined three structures. The second structure is labelled "Content", and contains a sub-structure.

**[6]** The Structure labelled "Content" contains an array named `content`. We will populate this array with a structure defined within a structure.

**[7]** The `_inputs` key contains all the inputs defined at a given level of the configuration cascade. In this case, inputs defined here are only available within the item "content".

**[8]** Within the structure labelled "Content", we have defined another structure.

**[9]** The key name of your sub-structure. In this code, we have called our sub-structure `elements`. The structures defined under `elements` will only be available within the item "Content" where `page_sections` is used in an aray or object input.
```

Let’s populate the arrays for `page_sections` and `elements` with sample content to see this substructure in action. Here is how the arrays look in the sidebar of the Content Editor.

![The sidebar of the Content Editor shows a Page Sections array with Hero, Content, and Call to action items, and a dropdown to add more.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Structure-Page-Builder-Picker.webp)

![The sidebar of the Content Editor shows nested structure options within the Content item, with Text and Image sub-elements.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Structure-Page-Builder-Elements-Picker.webp)

For more information, read our reference documentation on [using the configuration cascade](/documentation/developer-articles/using-the-configuration-cascade/).


---

---
title: Syncing build files from CloudCannon to an external provider
description: Configure a Build Deploy to commit the built version of your site to a repository.
url: https://cloudcannon.com/documentation/developer-articles/output-a-built-site-from-cloudcannon-to-an-external-provider/
content_type: developer article
last_modified: 2026-03-18
---

Configure a Build Deploy to commit the built version of your site to a repository. With a Build Deploy you can have CloudCannon handle your build and easily deploy the site to your own infrastructure.

## Adding a Build Deploy

1. First, create a repository that you would like to sync your site to, and connect it to a git provider.
2. Go to *Site Settings* / *Build Deploys* and choose your provider from the dropdown. If you have not yet authenticated CloudCannon with your provider, you will be prompted to do so.
3. Once authenticated, choose your repository from the dropdown, and choose an existing branch or create a new one.
4. Click **Connect and Sync** in the top right of the page.

> Your chosen branch will be overwritten once connected as a Build Deploy. Please ensure your chosen repository + branch is correct before proceeding.

![The Build Deploys page shows a GitHub repository connected as the output provider, with options to disconnect, change branch, view deploy history, and configure the deploy step and excluded paths.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Build-Deploys-Connected.webp)

Once connected, your most recently compiled site will replace the contents of the configured branch. This process will repeat after every build.

You can change the what part of the build step is synced after selecting the provider. By default, the compiled output of the build step is synced.

## Select a Deploy Step

Once you have connected to your repository, you can select which build step you would like to be synced.

Go to *Site Settings* / *Build Deploys* and click the dropdown menu under *Deploy Step*. Select from one of the following:

- **Build**: Once built, your site will be synced to your output repository before any further work is done on it.
- **I18n**: Sync your built site after translations have been performed on it.
- **Process**: Sync your built site after encrypting form details.
- **Compress**: Sync your built site after assets have been minified.

Then click **Update Build Deploy**.

![The Switch branch modal with a Branch dropdown and options to use an existing branch or create a new one.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Build-Deploys-Change-Branch-Modal.webp)

These options are listed in build-order. For example, selecting **Process** will sync your site once it has been built, translated, and processed, but before CloudCannon performs any compression.

In some cases the repo you're deploying to may contain special files you don't want to be overwritten by your deploy. The Excluded Paths setting allows you to specify a comma separated list of file prefixes, files matching one of these prefixes will not be updated by CloudCannon.

In the case that a file exists in your repo but not as part of your build, adding it as an excluded path will prevent if from being deleted by a deploy.

## Removing a Build Deploy

Go to *Site Settings* / *Build Deploys* and click **Disconnect <Provider>**.


---

---
title: Transferring sites between Organizations
description: Transfer the ownership of a site to another Organization.
url: https://cloudcannon.com/documentation/developer-articles/transferring-sites-between-organizations/
content_type: developer article
last_modified: 2026-03-29
---

Transfer the ownership of a site to another Organization.

Transferring a site will transfer all data and resources required to run that site. This may include SSL certificates, domain names, and other sites under the same domain.

Transfers are a two-step process; transfer requests and transfer confirmation.

## Initiating a transfer

To begin transferring a site:

1. Go to *Site Settings* / *Transfer Site*
2. **Select** an organization to transfer the site to
3. At the bottom of the page, click **Send Transfer Request**
4. Click again to confirm

![Screenshot of site transfer interface](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Transfer-Site-Page.webp)

Once the transfer request has been sent, the receiving account must accept the transfer. If you are an owner/administrator of the Organization you are transferring to, the transfer is automatically accepted.

> To transfer to an Organization, you must first be a part of that team.

## Accepting Transfer Requests

To accept a transfer:

1. Go to *Account Settings* / *Transfer Requests*
2. Find the request that you want to accept
3. Click the related **Accept** button

> To accept a transfer to an Organization, you must be an administrator or owner.

![Screenshot of site transfer interface with transfer request incoming](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Transfer-Requests-Incoming.webp)

## Cancelling Transfer Requests

To cancel a transfer you have initiated:

1. Go to *Account Settings* / *Transfer Requests*
2. Find the request that you want to cancel
3. Click the related **Remove** button

> A transfer cannot be canceled after it has been accepted. A transfer from the receiving account will need to be initiated to your account for it to be returned.

![Screenshot of site transfer interface with outgoing site transfer](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Transfer-Requests-Outgoing.webp)


---

---
title: Turn on Client Sharing for a Site
description: Learn how to enable Client Sharing for your Site.
url: https://cloudcannon.com/documentation/developer-articles/turn-on-client-sharing-for-a-site/
content_type: developer article
last_modified: 2026-03-29
---

To add a [Client Sharing](/documentation/user-articles/what-is-client-sharing/) password to your Site:

1. Navigate to the *Client Sharing* page under *Site settings*.
2. Under the *Password* tab, set the password to log in to the Site. For security reasons, the password must be at least six characters long
3. Click the *Set password and turn on* button to enable Client Sharing for this Site.

![A screenshot of the Client Sharing page shows fields for setting the Client password and enabling Client Sharing.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Client-Sharing-Page.webp)

Clients can now log in to your Site on the Client Login Page using the password you set. The Client Login Page will be the Site domain with the suffix “/update” unless you have [configured the URL to use a different subpath](/documentation/developer-articles/configure-the-client-login-page/).

![A screenshot of the Client Sharing page showing options to reset the password and disable Client Sharing.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Client-Sharing-Enabled-Password-Tab.webp)

To open the Client Login Page for your Site, click the *Open Client Login Page* button.

To turn off Client Sharing for a Site, click the *Turn Off* button at the top of the *Client Sharing* page.


---

---
title: Unified Configuration Flags
description: Learn about the live data and configuration editing flag and the Unified Configuration flag and how they might affect your Site
url: https://cloudcannon.com/documentation/developer-articles/unified-configuration-flags/
content_type: developer article
last_modified: 2026-04-11
---

> As of October 2024, CloudCannon uses the Unified Configuration format for your CloudCannon configuration file by default for all new Sites. Site created before this data can also upgrade to the Unified Configuration format.
> 
> For more information, please read our guide on [migrating to Unified Configuration](/documentation/developer-guides/unified-configuration-migration-guide/) or contact our friendly [support team](/support/).

These flags may not be visible to all users depending on your Site and Organization configuration.

## Step 1: Enable live configuration and data reloading

The *Enable live configuration and data reloading* flag controls whether CloudCannon will automatically load changes to your data and configuration files without the need for a build. Enabling this flag may override the configuration from your last successful build.

All Sites can enable this behavior independantly from migrating to the Unified Configuration file format. You can enable this behavior by checking the *Enable live configuration and data reloading* flag on the *Flags* page of your Site, under *Site Settings*.

For more information, please read our documentation on [Live Configuration and Data Editing](/documentation/developer-guides/unified-configuration-migration-guide/live-configuration-and-data-editing/).

## Step 2: Use Unified Configuration

> Please do not enable this flag before reading our [migration guide](/documentation/developer-guides/unified-configuration-migration-guide/).

The *Use Unified Configuration* flag controls whether CloudCannon will expect your CloudCannon configuration file to be in the Unified Configuration file format. All Sites created on new Organizations after October 2024 use Unified Configuration by default.

You can enable this behavior by checking the *Use Unified Configuration* flag on the *Flags* page of your Site, under *Site Settings*.

You can also enable this behavior on an Organization level checking the *Use Unified Configuration* flag on the *Flags* page of your Site, under *Org Settings*. This Organization level flag will ensure all new Sites created in your Organization use the Unified Configuration format.


---

---
title: Update the fallback redirect for your Custom Domain
description: Learn how to update the fallback redirect for your Custom Domain and prevent 404 errors.
url: https://cloudcannon.com/documentation/developer-articles/update-the-fallback-redirect-for-your-custom-domain/
content_type: developer article
last_modified: 2026-02-10
---

> **Permissions required**
> 
> Members of the Developers and Owners [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `base-domain:settings:details:write` permission, can update the fallback redirect for a Custom Domain.

A Custom Domain is a unique address used to identify a website (e.g., [cloudcannon.com](https://cloudcannon.com)). If you have [connected a Custom Domain to your Organization](/documentation/developer-articles/connect-a-custom-domain-to-your-organization/), you can host your Site on a subdomain by [adding a Custom Domain to your Site](/documentation/developer-articles/add-a-custom-domain-to-your-site/). CloudCannon will use the fallback redirect domain for any subdomains you do not add to a CloudCannon Site.

- **Fallback redirect** — The domain to which CloudCannon will redirect visitors when they attempt to access an unconfigured subdomain.

The fallback redirect prevents your visitors from encountering 404 errors if they enter an incorrect domain name in their Internet browser. By default, CloudCannon will use your base domain as your fallback redirect (e.g., *.example.com will redirect to example.com).

You can configure which domain or subdomain is your fallback redirect on the *Network* tab of your Custom Domain's *Domain* page. To select a Custom Domain as your fallback redirect, you must add that domain to a CloudCannon Site.

These instructions assume you have connected the Custom Domain to your Organization and added the domain you want to use as your fallback redirect to a Site.

To configure your fallback redirect:

1. Log in to CloudCannon and select the Organization with the Custom Domain you want to update.
2. Click the *Domains* button in the *App Sidebar*. CloudCannon will open the *Domains browser*.
3. Identify the domain you want to update and click on the *Domain* card. CloudCannon will open the *Domain* page for this Custom Domain.
4. On the *Network* tab, click the *Update fallback redirect* button under the *Fallback redirect* heading. CloudCannon will open the *Update your fallback redirect* modal.
5. Select the subdomain you want to use as your fallback redirect using the *Subdomain* dropdown.
6. Click the *Update fallback redirect* button.

CloudCannon will update you fallback redirect.

![A screenshot of the Network tab on the Domain page shows the fallback redirect section and Update fallback redirect button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Domains-Network-Tab.webp)

![A screenshot of the Update your fallback redirect modal on the Network tab shows a Subdomain dropdown for selecting a new fallback redirect.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Domains-Network-Tab-Fallback-Redirect-Modal.webp)

> If you have configured your [DNS](/documentation/developer-articles/what-is-dns/) to point a specific domain at a service outside of CloudCannon, CloudCannon will not be able to redirect that domain to your main domain.


---

---
title: Update the output URL for a Collection
description: Learn how to update the output URL CloudCannon uses to match output files to source files, enabling the Visual Editor and screenshots.
url: https://cloudcannon.com/documentation/developer-articles/update-the-output-url-for-a-collection/
content_type: developer article
last_modified: 2026-02-12
---

> **Permissions required**
> 
> Members of the Owners, Developers, and Technical Editors [Default Permission Groups](/documentation/articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/articles/what-are-custom-permission-groups/) with the `site:source-editor:write` and `site:file:write` permissions, can edit your *CloudCannon Configuration File*. You can limit permission to specific files using [file globs](https://cloudcannon.com/documentation/articles/what-are-custom-permission-groups/#specify-a-file-glob).

An output URL is the URL your SSG outputs your files to during a [Site build](/documentation/articles/what-is-a-site-build/).  After each successful build, CloudCannon automatically determines the likely output URL to match an [output file](/documentation/articles/what-is-an-output-file/) to a source file, enabling the [Visual Editor](/documentation/articles/what-is-the-visual-editor/) and screenshots in the *Collection Browser*.

If CloudCannon has incorrectly determined the output URL for your source files, you may notice the wrong webpage screenshot in the gallery section of your *File Cards* (or no screenshot), or that the *Visual Editor* opens to an incorrect webpage. To fix this issue, you can explicitly specify the output URL for each *Collection* using a template string.

To update the output URL CloudCannon uses to match a output files to source files:

1. Navigate to the *Collection* for which you want to update the output URL CloudCannon uses.
2. Turn on *Configuration Mode* using the switch on the right of the *Site Header*. Purple *Edit Configuration* buttons will appear in the *Collection Browser*.
3. Click the *Edit Advanced* in the top right of the *Collection Browser*. CloudCannon will open the *Edit Advanced* data panel.
4. Identify the *URL* text field and enter the template string for the correct output URL.
5. Save the change to your *Site*.

CloudCannon will automatically update which output URL it uses to match output files to source files for that *Collection*.

![A screenshot of the Collection Browser shows the Edit Advanced data panel open with a text field for URL configuration.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-Configuration-Mode-Edit-Advanced-URL.webp)

> Updating the `url` key does not change where your SSG will output your files.

## Template string placeholders

You can use a template string to define the correct output URL for matching output files in a *Collection*. Template strings allow you to use placeholders as well as plain text.

You can use fixed or data placeholders, and filters to modify the value of data placeholders, allowing you to reference structured data from your files to create the correct URL format.

### Fixed placeholders

The following fixed placeholders are available for your output URL template string:

- `[filename]` — Populated by the original filename including the file extension.
- `[slug]` — Populated by the original filename excluding the file extension. If the filename is "index", this will result in an empty string.
- `[relative_path]` — Populated by the original file name including the file extension, relative to the *Collection* path.
- `[relative_base_path]` — Populated by the original file name excluding the file extension, relative to the *Collection* path.
- `[full_slug]` — An alias for the template path `[relative_base_path]/[slug]`.
- `[path]` — Populated by the original file name including the file extension, relative to your *Site* source.
- `[base_path]` — Populated by the original file name excluding the file extension, relative to your *Site* source.
- `[collection]` — Populated by the key for the *Collection* to which the file belongs.
- `[ext]` — Populated by the last file extension in the original file path.

Let's go through an example.

The `url` template string `/[relative_bath_path]/[slug]/` for our "Pages" *Collection* will resolve to the following output URLs:

- The file `/pages/index.md` becomes the output URL `/` (e.g., a Home landing page).
- The file `/pages/about.md` becomes the output URL `/about`.
- The file `/pages/contact/index.md` becomes the output URL `/contact/`.
- The file `/pages/contact/book-an-appointment.md` becomes the output URL `/contact/book-an-appointment`

### Data placeholders

You can reference any front matter field from your file in your output URL template string by using the key name in curly brackets (e.g., `{key}`).

You can also apply filters to your data placeholders by using the `|` character after your front matter key name, followed by the name of the filter.

Let's go through an example.

The `url` template string `/news/{date|year}/{date|month}-{date|day}_{title|slugify}/` for our "News" *Collection* will resolve to the following output URLs:

- The file `/news/our-next-feature.md` with the front matter fields `title: Our next feature!` and `date:05/11/2026` becomes the output URL `/2026/05-11_our-next-feature`.

For a complete list of filters available for data placeholders in your output URL template string, please read our documentation on [template strings](/documentation/articles/configure-your-template-strings/).


---

---
title: Using arrays to make a gallery
description: Learn how to set the structure for new items in a gallery array.
url: https://cloudcannon.com/documentation/developer-articles/using-arrays-to-make-a-gallery/
content_type: developer article
last_modified: 2026-04-11
---

Create reusable components which content editors use to create their own feature-rich pages. To set up a structure, you define the different components available. CloudCannon then provides editors the option to select one of the components when adding an item to the array. This adds that component to the array where they can then fill out the inputs.

For example, set the structure for new items in a `gallery` array with:

File: `Configuration`

```yaml
_structures:
  gallery:
    style: modal
    values:
      - label: Image
        icon: image
        tags:
          - Media
          - Asset
        value:
          image: /uploads/placeholder.png
          caption:
        preview:
          gallery:
            image: /path/to/source-image.png
      - label: External link
        icon: link
        tags:
          - Media
        value:
          url:
          title:
```


---

---
title: Using relative paths for DAM assets
description: Learn about using relative paths for DAM assets
url: https://cloudcannon.com/documentation/developer-articles/dam-assets-with-relative-paths/
content_type: developer article
last_modified: 2026-04-11
---

You can choose one DAM to use relative paths on your site. This means that your DAM URLs may start with "/", instead of being fully qualified. A fully qualified URL is a complete Internet address and must include a hostname and top-level domain.

By default, all the URLs for assets on your DAM need to be fully qualified in order to preview them on CloudCannon. Similarly, CloudCannon will always save fully qualified URLs in your code when you upload an asset to a DAM through the CMS. This behaviour can be turned off by choosing to use relative paths for your DAM.

This option can be useful if your SSG prepends the DAM's base url during the build.

### Using relative paths

By default, relative paths in your site must refer to the site files.

> If you choose to use relative paths with a DAM, you will not be able to browse assets from, or upload to, your site files in CloudCannon.

1. In your site’s settings, navigate to *Files/Assets*
2. Locate your DAM from the list, and click the three dots in the top right corner
3. From the context menu, click **Use Relative Paths**
4. Click the Confirm button

> When changing this setting, you might need to rewrite existing URLs on the site to avoid broken previews in CloudCannon.

To undo this change, repeat the steps above but use the context menu on *Site Files* in the list.


---

---
title: Using the configuration cascade
description: Learn how the configuration cascade lets you set options for Collections, Schemas, Files, and Structures.
url: https://cloudcannon.com/documentation/developer-articles/using-the-configuration-cascade/
content_type: developer article
last_modified: 2026-04-11
---

The configuration cascade is a set of sources containing customizable options for the editor. Each source has a different scope and priority. This allows you to set global defaults and override those for specific collections or files.

When CloudCannon needs an option you have set in the configuration cascade, it looks at each scope in order. In most cases, the cascade stops looking when an option is found. This means the most specific value is used in place of any less specific values.

> [Input configuration](/documentation/user-articles/what-are-inputs/) (i.e. `_inputs`) has a different cascading default, where CloudCannon continues looking over less specific sources to merge into a single option.

## Sources

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

1. [CloudCannon configuration file](/documentation/developer-articles/create-your-cloudcannon-configuration-file/)
2. [Collection](/documentation/user-articles/what-is-a-collection/) configuration
3. [Schema](/documentation/developer-articles/what-is-a-schema/) configuration
4. Front matter
5. Containing [structure](/documentation/developer-articles/what-is-a-structure/)

### Global configuration

For configuring everywhere on your site. For example:

File: `cloudcannon.config.yml`

```YAML

_inputs:
  image_path:
    type: image
    comment: Helpful message here
    options:
      width: 90
      height: 120
_select_data:
  colors:
    - Red
    - Blue

```

### Collection configuration

For configuring all files within a collection. For example:

File: `cloudcannon.config.yml`

```YAML

collections_config:
  pages:
    _inputs:
      image_path:
        type: image
        comment: Helpful message here
        options:
          width: 90
          height: 120
    _select_data:
      colors:
        - Red
        - Blue

```

### Schema configuration

For configuring all files within one of a collection's schemas. For example:

File: `cloudcannon.config.yml`

```YAML

collections_config:
  pages:
    schemas:
      default:
        path: 'schemas/page.md'
        _inputs:
          image_path:
            type: image
            comment: Helpful message here
            options:
              width: 90
              height: 120
      landing_page:
        path: 'schemas/landing-page.md'
        _select_data:
          colors:
            - Red
            - Blue

```

### Front matter

For configuring a single file. For example:

File: `Configuration`

```yaml

image_path: /uploads/me.png
_inputs:
  image_path:
    type: image
    comment: Helpful message here
    options:
      width: 90
      height: 120
_select_data:
  colors:
    - Red
    - Blue

```

### Containing structure

For configuring inputs inside a structure. For example:

File: `Configuration`

```yaml

_structures:
  gallery:
    values:
      - label: Image
        icon: image
        _inputs:
          image:
            type: image
            options:
              width: 50
              height: 50
          caption:
            comment: Applies inside this structure
        _select_data:
          colors:
            - Red
            - Blue
        value:
          image: /uploads/placeholder.png
          caption:
          color:

```

> For nested structured data, you can nest `_structures` alongside the other configuration groups inside a structure definition.

## Options

Since configuration cascade options can be defined alongside your data, they always begin with an underscore in an effort to avoid clashing with a key you would use.

The following configuration cascade options are available:

**`_editables`** Object

Contains options for the *WYSIWYG toolbar* in the Content Editor and rich text inputs. Read more about the [configuring your rich text toolbar options](/documentation/developer-articles/configure-your-rich-text-editors/).

**`_enabled_editors`** Array of strings

Controls how your team edits specific files, use this to set a preferred editor and/or disable the others. The first value sets which editor opens from the collection list, the other values specify which editors are accessible. Available values are:

- `visual` for the [Visual Editor](/documentation/user-articles/what-is-the-visual-editor/)
- `content` for the [Content Editor](/documentation/user-articles/what-is-the-content-editor/)
- `data` for the [Data Editor](/documentation/user-articles/what-is-the-data-editor/)

The [Source Editor](/documentation/user-articles/what-is-the-source-editor/) is always available for those with permission.

**`_inputs`** Object

Contains configuration for controlling the behavior and appearance of your inputs in the Data Editor. Read more about [how inputs work](/documentation/user-articles/what-are-inputs/).

**`_select_data`** Object

This key defines which data is available 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](/documentation/developer-articles/using-the-configuration-cascade/), `_select_data` will default to any values configured in the [CloudCannon configuration file](/documentation/developer-articles/what-is-the-cloudcannon-configuration-file/).

For more information, please read our documentation on [Select inputs](/documentation/user-articles/what-is-a-select-input/).

**`_structures`** Object

Provides structure definitions at a global scope. This allows you to provide multiple values when editors set objects or [add items to arrays in the Data Editor](/documentation/developer-articles/create-a-structure/).


---

---
title: Visual Data Bindings with Bookshop
description: Bookshop will automatically add data bindings when live editing in CloudCannon
url: https://cloudcannon.com/documentation/developer-articles/visual-data-bindings-with-bookshop/
content_type: developer article
last_modified: 2026-04-11
---

Bookshop defines a convention for building self-contained components in the templating languages supported by common static site generators. Using these conventions, Bookshop provides developer tooling that empowers you to integrate these components with your stack, build and browse UI components locally, and provide rich live editing experiences for your editors.

By default, Bookshop will automatically add data bindings when live editing. Read [the Bookshop Visual Data Bindings documentation for further information](https://github.com/CloudCannon/bookshop/blob/main/guides/visual-data-bindings.adoc).


---

---
title: Visual data bindings with React
description: React allows you to add the `data-cms-bind` attribute on any DOM element
url: https://cloudcannon.com/documentation/developer-articles/visual-data-bindings-with-react/
content_type: developer article
last_modified: 2026-04-11
---

React allows you to add the `data-cms-bind` attribute on any DOM element. It is recommended that these are added recursively into each object. If you are using an older version of React, you may need to forward this on differently. Please refer to the [React documentation](https://reactjs.org/blog/2017/09/08/dom-attributes-in-react-16.html#data-and-aria-attributes).

File: `heading.jsx`

```jsx
class Heading extends React.Component {
  render() {
    return (
      <h1 data-cms-bind="title">{this.props.title}</h1>
    );
  }
}
```

It is recommended that you pass the parent binding as a prop. This way your component can be reused in any stack. For the base case a empty string should be used as the binding. If you have an array component and a component for each array, it is recommended to skip the array binding to reduce the number of editor clicks.


---

---
title: Visual data previews with Bookshop
description: Preview live changes to static websites using CloudCannon's Bookshop framework
url: https://cloudcannon.com/documentation/developer-articles/visual-data-previews-with-bookshop/
content_type: developer article
last_modified: 2026-04-11
---

Bookshop defines a convention for building self-contained components in the templating languages supported by common static site generators. Using these conventions, Bookshop provides developer tooling that empowers you to integrate these components with your stack, build and browse UI components locally, and provide rich live editing experiences for your editors.

Bookshop provides the ability for your editors to preview changes live while editing your page in CloudCannon. Read [the Bookshop live editing documentation to setup](https://github.com/CloudCannon/bookshop/blob/main/guides/live-editing.adoc).


---

---
title: Visual data previews with React
description: Live editing on CloudCannon with React. Edit Front Matter and see the changes show up live.
url: https://cloudcannon.com/documentation/developer-articles/using-live-editing-with-react/
content_type: developer article
last_modified: 2026-04-11
---

React is a great at receiving new data and rerendering components. To make this integration easier CloudCannon has developed an open source library for easy installation. [`@cloudcannon/react-connector`](https://github.com/CloudCannon/react-connector) is a higher order component that listens to live editing events and passes the new props to your component.

## Installation

Cloudcannon React Connector is available on npm. To install run:

File: `Shell`

```shell
npm i @cloudcannon/react-connector
```

## Next.js Integration

Update the code in `pages/_app.jsx` from:

File: `pages/_app.jsx`

```jsx
export default function App({ Component, pageProps }) {
  return <Component {...pageProps} />
}
```

to:

File: `pages/_app.jsx`

```jsx
import { CloudCannonConnect } from '@cloudcannon/react-connector'
export default function App({ Component, pageProps }) {
  const AppComponent = CloudCannonConnect(Component);
  return <AppComponent {...pageProps}/>
}
```

This should make no difference to your development or production environment. Loading the site in CloudCannon's Visual Editor and changing front matter will push new changes directly into the page props.

Any issues, please contact support or [raise an issue on the GitHub repository](https://github.com/CloudCannon/react-connector/issues).


---

---
title: Visual data previews with Svelte
description: Data previews on CloudCannon with Svelte. Edit Front Matter and see the changes show up live.
url: https://cloudcannon.com/documentation/developer-articles/live-editing-with-svelte/
content_type: developer article
last_modified: 2026-04-11
---

Svelte is great at receiving new data and rerendering components. To make this integration work we hook into the Svelte lifecycle. onMount and onDestroy can set up event listeners that update the pages properties.

## Requirements for data previews

- Components must have an output URL. SvelteKit routes are a good example.
- Components must get their data from a data/content file somewhere in your project. This is critical, as the Visual Editor cannot open the components themselves.
- These data/content files must be configured as a CloudCannon Collection. See the [CloudCannon Reader documentation](https://github.com/CloudCannon/reader#readme) for more information.
- Components will need to use the Svelte `onDestroy` and `onMount` functions.

## Installation and Usage

The CloudCannon Svelte connector is [available on npm](https://www.npmjs.com/package/@cloudcannon/svelte-connector).

To install, run:

File: `Shell`

```shell
npm i @cloudcannon/svelte-connector
```

Next, add the following code to any component that you want to add live editing to:

File: `index.svelte`

```html
<script>
  import { onDestroy, onMount } from 'svelte';
  import { onCloudCannonChanges, stopCloudCannonChanges } from '@cloudcannon/svelte-connector';

  // pageDetails is passed from parent, or via SvelteKit load function
  export let pageDetails;

  onMount(async () => {
    onCloudCannonChanges((newProps) => pageDetails = newProps);
  });

  onDestroy(async () => {
    stopCloudCannonChanges();
  });
</script>
```

In the above code, `pageDetails` is an object that contains data for the markup portion of the component.

After loading the content file in the Visual Editor, changing the data in the sidebar will push the new props to `pageDetails`. This will display the new values in the Visual Editor immediately.

This should make no difference to your development or production environment.

For an example integration, check out our [Urban SvelteKit template](https://cloudcannon.com/community/themes/urban/). If you have any issues, please [contact support](https://cloudcannon.com/contact/), or [raise an issue on the GitHub repository](https://github.com/CloudCannon/svelte-connector/issues).


---

---
title: Visual data previews with vanilla JavaScript
description: Live editing on CloudCannon with vanilla JS. Create your own live previews by hooking into document events.
url: https://cloudcannon.com/documentation/developer-articles/using-live-editing-with-vanilla-js/
content_type: developer article
last_modified: 2026-04-11
---

Live editing in CloudCannon is all based on an injected JavaScript object `CloudCannon` and custom events triggered on the `document` object.

## CloudCannon Events

When your website is loaded in the Visual Editor, CloudCannon will trigger [CustomEvents on the global `document` object](https://developer.mozilla.org/en-US/docs/Web/Events/Creating_and_triggering_events). This is a feature available in all major browsers.

### Load Event

Triggers when CloudCannon live editing API is available. Triggers before the `CloudCannon` object is  injected onto the `window` object."

```javascript
document.addEventListener('cloudcannon:load', function (e) {
  onLiveEditorLoad(e.detail.CloudCannon);
});
```

Depending on when the JavaScript is run, the load event might have already been triggered. In this case, the CloudCannon object will be available on the global `window` object.

```javascript
if (!window.CloudCannon) {
  document.addEventListener('cloudcannon:load', function (e) {
    onLiveEditorLoad(e.detail.CloudCannon);
  });
} else {
  onLiveEditorLoad(window.CloudCannon);
}
```

### Update event

Using the `CloudCannon` object, we need to enable the other document events. To do this we need to use the following code:

Once this CloudCannon object is saved, you can enable live editing. To demonstrate, we are using the function called in the last code snippet.

```javascript
function onLiveEditorLoad(CloudCannon) {
  CloudCannon.enableEvents();
}
```

With that enabled, we can register an event listener to the update event. The `cloudcannon:update` event is triggered after every front matter change.

```javascript
document.addEventListener('cloudcannon:update', async function (e) {
  useNewPageProps(e.detail.CloudCannon);
});
```

All events provide the `CloudCannon` object available on the event details.

## The CloudCannon Object

All events provide the `CloudCannon` object available on the event details. Alternatively this object is available at `window.CloudCannon`. This object gives you access to the CloudCannon interface.

### Fetching the current front matter value

Using the `CloudCannon` object, we can fetch the latest value of the front matter. This paired with the update event is the key to live previews. To do this, we use the `CloudCannon.value()` function. This function returns a promise, when awaited will return a json object of the latest value.

```javascript
async function useNewPageProps(CloudCannon) {
  const latestValue = await CloudCannon.value();
}
```

### Updating a front matter key

Using the `CloudCannon` object, we can set a value of a key in the front matter. This allows us to build custom controls directly on our page. To do this, we use the `CloudCannon.set(slug, value)` function.

```javascript
CloudCannon.set('title', 'new title value');
```


---

---
title: Visual data previews with Vue
description: Data previews on CloudCannon with Vue. Edit Front Matter and see the changes show up live.
url: https://cloudcannon.com/documentation/developer-articles/live-editing-with-vue/
content_type: developer article
last_modified: 2026-04-11
---

As a modern web framework, Vue is purpose-built to handle reactive components that re-render when their data changes.
This power can be used to configure live editing within the CloudCannon CMS.

> This guide will focus on components that use the [Vue Composition API](https://vuejs.org/guide/introduction.html#composition-api).

## Requirements for data previews

- Components must have an output URL. If your site is built with Nuxt using the Nuxt Content module, components in the `pages/` directory are a good example.
- Components must get their data from a data/content file somewhere in your project. This is critical, as the Visual Editor cannot open the components themselves.
- These data/content files must be configured as a CloudCannon Collection. See the [CloudCannon Reader documentation](https://github.com/CloudCannon/reader#readme) for more information.
- Components will need to use the Vue `onMounted` and `onBeforeUnmount` hooks.

## Installation

The CloudCannon Visual Editor connector is [available on npm](https://www.npmjs.com/package/@cloudcannon/visual-editor-connector).

To install, run:

File: `Shell`

```shell
npm i -D @cloudcannon/visual-editor-connector
```

## Integration

Below is a component with the bare minimum needed for live editing in the Visual Editing.

File: `pages/[...slug].vue`

```html
```
<script setup>
  import { onMounted, onBeforeUnmount, ref } from 'vue';
  import { onCloudCannonChanges, stopCloudCannonChanges } from '@cloudcannon/visual-editor-connector';

  const { page } = useContent(); //1

  const pageData = ref(page.value); //2

  onMounted(async () => {
    onCloudCannonChanges((latestValue) => {
      pageData.value = latestValue; //3
    });
  });

  onBeforeUnmount(async () => {
    stopCloudCannonChanges(); //4
  });
</script>
```

**[1]** `useContent()` is a function that is provided by [Nuxt Content's Document-driven mode](https://content.nuxtjs.org/guide/writing/document-driven).
It fetches the file in the `content/` directory that reflects the current URL. Replace this line with however you fetch page data.

**[2]** [Vue's ref function](https://vuejs.org/api/reactivity-core.html#ref) creates a mutable reactive object.
Whenever the value of `pageData` changes, any component that relies on that data will re-render.

**[3]** The `onCloudCannonChanges()` hook takes a callback function that is triggered whenever the page is edited in CloudCannon.
For example, editing the front matter of the corresponding page in the Data Editor will run the code here.
The callback takes the updated page data as a parameter, and assigns the new data to the `pageData` object.

Because `pageData` is reactive, this will re-render and display the updated component in the Visual Editor immediately.

**[4]** This needs to be run in the `onBeforeUnmount()` hook to tear-down listeners before the component is destroyed.
```

You should be able to make these additions with no difference to your build output or production environment.

For an example integration, check out our [Sendit Nuxt template](https://cloudcannon.com/community/themes/sendit/).
If you have any issues, please [contact support](/support/), or [raise an issue on the GitHub repository](https://github.com/CloudCannon/visual-editor-connector/issues).


---

---
title: What are Custom Permission Groups?
description: Learn about Custom Permission Groups in CloudCannon and fine-grained control over team permissions.
url: https://cloudcannon.com/documentation/developer-articles/what-are-custom-permission-groups/
content_type: developer article
last_modified: 2026-04-11
---

> **This feature is available on our [Team and Enterprise plans](/pricing/).**
> 
> Want to chat about whether this feature is right for you? Our support team is always [happy to hear from you](mailto:success@cloudcannon.com?subject=A%20question%20about%20custom%20Permission%20Groups).

## What are Custom Permission Groups?

Custom Permission Groups give you fine-grained control over the permissions in your Organizations.

Using Custom Permission Groups, you can:

- Select which resources are available to each Group and define what actions are allowed (Read, Write, or Create).
- Alter the scope of a permission from Global to Project, Site, Group, or Base Domain.
- Define file globs and exceptions for each Group for more precise permissions.
- Add multiple permissions and exceptions at different scopes.

The maximum number of Custom Permission Groups you can create will depend on your [pricing plan](/pricing/). For more information on Permission Groups in general, please read our documentation on [Permission Groups](/documentation/user-articles/what-are-permission-groups/).

### Selecting resources

Custom Permission Groups use the same list of resources as [Default Groups](/documentation/user-articles/what-are-default-permission-groups/). A resource is something you can interact with in CloudCannon, such as an individual Site, Pull Request settings, or billing information. Each resource has one or more associated actions: Read, Write, or Create.

Custom Permission Groups can have multiple permissions, each with their own scope, resources, and allowed actions. When you create a Custom Permission Group, you must select which resources you want to add and what actions you want to allow for each resource. Adding a resource to a permission will allow all members of that Group to interact with that resource.

![A screenshot of the Add Permission modal shows the option to select resources and scope for a Custom Permission Group.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Team-Add-Permission-Modal-Global-Scope.webp)

CloudCannon uses a tree structure to define resources. When you select a resource for your Custom Permission Group, you can choose a broad resource heading (e.g., `site:write`), or drill down to more specific resources (e.g., `site:settings:site-mounting:write` or `site:publish:pull-requests:merge:write`). Adding more specific resources allows your Permission Group to be as fine-grained as you require.

Let’s walk through an example.

We want to create a Permission Group where members cannot see any existing Sites in the Organization but can add new Sites, which they can then see and edit. This type of Permission Group might work well to keep teams within your Organization from accessing each other’s content. In this case, we should add the resource `site:create` but not `site:read` to our permission.

The create action allows you to create new instances of a resource (in this example, Sites). When you create an instance of a resource, CloudCannon will automatically give you permission to Read and Write that instance. By choosing not to add `site:read` to this permission, existing Sites in our Organization will not appear in the CloudCannon interface.

For more information, including a complete list of resources available, please read our [permissions](/documentation/developer-reference/permissions/) reference documentation.

### Permission scope

The scope of a permission defines how broadly it is applied. Permissions in the [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/) have a Global scope. Permissions for [Site Sharing](/documentation/user-articles/share-a-site-with-site-sharing/) or [Client Sharing](/documentation/user-articles/what-is-client-sharing/) Groups have a Site scope.

With Custom Permission Groups, you can set a permission at one of five scopes: Global, Project, Site, Group, and Base Domain.

- **Global** — This scope encompasses your entire Organization (e.g., the resource `project:create` with the scope Global will allow all members of the Permission Group to create new Projects in your Organization, which they then have permission to edit).
- **Project** — This scope encompasses a specific Project (e.g., the resource `site:publish:pull-request:open:write` with a Project scope will allow all members of the Permission Group to create Pull Requests for any site within the chosen Project, but not merge them).
- **Site** — This scope encompasses a specific Site (e.g., the resource `site:analytics:read` with a Site scope will allow all members of the Permission Group to view the hosting and building analytics for the chosen Site).
- **Group** — This scope encompasses a specific Group (e.g., the resource `group:member:write` with a Group scope will allow all members of the Permission Group to edit the members of a specific Group).
- **Base Domain** — This scope encompasses a specific Base Domain (e.g., the resource `base-domain:settings:dns:write` with a Domain scope will allow all members of the Permission Group to edit DNS records for a specific domain).

Custom Permission Groups can include permissions with different scopes. For example, you might want to create a Group that can approve Pull Requests for a specific Project and manage the Domain associated with one Site in that Project. This Permission Group would contain two permissions: one with a Project scope and the resource `site:publish:pull-request:merge:write`, and one with a Base Domain scope and the resource `base-domain:write`.

When you select Project, Site, Group, or Base Domain as a scope, CloudCannon will prompt you to select the Target of that scope.

- **Target** — Which instance you want a scope to pertain to (e.g., name the specific Site or Permission Group).

![A screenshot of the Add Permission modal shows that selecting the Group scope will add a Target field.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Team-Add-Permission-Modal-Group-Scope.webp)

Not all resources work with all scopes. For example, you can’t give someone the resource `project:delete:write` with a Site scope, as Sites cannot contain Projects, or `org:billing:write` with a Group scope, as you cannot control billing at the Group level. When you create a Custom Permission Group, CloudCannon will filter out the resources that don’t apply to your scope.

For best practices and examples, please read our documentation on [best practices for selecting resources](/documentation/developer-articles/best-practices-for-custom-permission-groups/#resources).

### Exceptions

Exceptions allow you to set broad permissions and then remove specific permissions from a Group. For example, a team member might have permission to edit all Sites within a Project except for the Production Site.

You can add multiple exceptions to a Custom Permission Group. For each exception you must select a scope and a list of resources.

![A screenshot of the Custom Permission Group Settings tab, scrolled down to show the Add exception button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Team-Custom-Group-Exceptions.webp)

Permission Groups are always additive. In other words, permissions or exceptions in  one Group do not negate permissions or exceptions in another. If one Group allows an action, an exception in a second Permission Group does not prevent access to that resource.

Exceptions are more efficient than explicitly providing permission for many resources. Let’s walk through an example.

We want to prevent a team member from editing the Production site but enable editing for all other Sites within the Project. We could explicitly give permission for all those Sites. However, each time someone adds a new Site to the Project, we would need to update the Permission Group. Using an exception, we can remove permission for a single site and set the scope of the Permission Group as “Project” to allow editing permissions for all future Sites.

### Specify a file glob

A file glob is a pattern used to identify matching files. Files globs look similar to a file path with a mix of literal text and special characters such as `*` and `{ }`. In CloudCannon, you can specify read or write access to specific file globs in a Custom Permission Group. You can specify which collections, folders, filenames, and file extensions a team member is allowed to read or edit, allowing for fine-grain control over reading and editing site files.

A read or write action is associate with each file glob. Additionally, when you specify a file glob in a permission or an exception, this will override any `site:files:read` and `site:files:write` resources selected from the resource tree. Because specifying a file glob implicitly includes the resource for read or write, the `site:files` checkbox in the resource tree is enabled by default.

To create a file glob, type the file path of any files you want to determine access for. For more general file paths, you can create a glob using the special characters `*` and `{ }`. The `*` character denotes any file, while `/**/` denotes any number of folder. Using the `{ }` brackets, you can specify a list of options separated by a comma.

For example, if we add a permission to write the file glob `/posts/**/*.{md,html}`, CloudCannon will allow members of this Permission Group to read and edit any Markdown or HTML files within any subfolders of the Collection "Posts".

![A screenshot of the Add Permission modal shows two fields specifying file globs, one at read level and one at write.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Team-Add-Permission-File-Glob.webp)

For best practices and examples of how to use file globs, please read our documentation on [file glob best practices](/documentation/developer-articles/best-practices-for-custom-permission-groups/#file-globs).

> If you need assistance setting up file globs in your Organization, our [support team](/support/) is always happy to help.

## Default vs. Custom Permission Groups

CloudCannon provides [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/) on every pricing plan. The Default Permission Groups (Owner, Developer, Technical Editor, and Editor) are hierarchical, meaning that each Group also contains the permissions of all Groups below it in the hierarchy. Default Permission Groups are convenient if you have fewer team members, less complex sharing requirements, or do not want to configure Custom Permission Groups.

The Default Permission Groups may not be right for you if:

- You want non-hierarchical Permission Groups.
- You want to define a subset of your Sites that team members can access (e.g., a project, all sites except the production Site, or a specific Site).
- You want to define who can perform specific actions (e.g., making vs approving pull requests, reading vs editing content, branching, inbox management).
- You want to prevent a team member from accessing existing Sites but allow them to create new Sites in your Organization, which they can edit.
- You want to define which files within a Site a team member can edit (e.g., a collection, specific file types, or a single file).

Because Default Permission Groups have a Global scope, CloudCannon will give Group members the same permissions for every Site in your Organization. Additionally, you cannot edit the permissions granted by Default Permission Groups.

You can overcome these limitations by creating Custom Permission Groups.

## Custom Permission Groups vs. Site Sharing

Using the four Global Default Permission Groups, you cannot limit access to an individual Site. You can address this problem using [Site Sharing](/documentation/user-articles/share-a-site-with-site-sharing/) or using Custom Permission Groups.

Site Sharing allows you to invite a team member to view, edit, and publish content for a specific Site. Each Site has two permission groups for Site Sharing, identical to the Technical Editor and Editor Default Permission Groups except with a Site scope.

Custom Permission Groups do everything Site Sharing does and more. For [Team and Enterprise customers](/pricing/), we recommend using Custom Permission Groups rather than Site Sharing for finer control over your content.


---

---
title: What are Editable Regions?
description: Learn about Editable Regions, including how they look in the Visual Editor.
url: https://cloudcannon.com/documentation/developer-articles/what-are-editable-regions/
content_type: developer article
last_modified: 2026-02-12
---

*Editable Regions* allow you to edit your content in the [Visual Editor](/documentation/user-articles/what-is-the-visual-editor/).

An *Editable Region* in the Visual Editor is signified by a yellow box around a piece of content. Clicking into the *Editable Region* will have a different result depending on the type of content it contains.

[Video: Visual Editor with editable regions](https://player.vimeo.com/progressive_redirect/playback/949770919/rendition/1080p/file.mp4?loc=external&signature=bef4d0471cb24f6c2370b8900c416e265e48c863df627ab7369f06c210777d8a)

In CloudCannon, defining *Editable Regions* in your files is as simple as adding an HTML attribute to any DOM element or inserting a web component on any file in your website that outputs to an HTML webpage after a [Site build](/documentation/developer-articles/what-is-a-site-build/). You can make an entire *Collection* of content files visually editable in minutes.

File: `BlogPost.astro`

```Astro
```

<h1 data-editable="text" data-prop="title" >{title}</h1> /*1*/

```

**[1]** We have added the `data-editable` and `data-prop` HTML attributes to the `<h1>` tag in our Blog Post layout to create a Text *Editable Region* around the Title field.
```

> Want to add *Editable Regions* to your *Site*? Check out our guide: [Set up Visual Editing](/documentation/developer-guides/set-up-visual-editing/).

There are five types of *Editable Regions*:

- [Text Editable Regions](/documentation/developer-articles/configure-text-editable-regions/) — Allows you to edit text values stored in front matter, content, or HTML with plain text or rich text formatting options.
- [Image Editable Regions](/documentation/developer-articles/configure-image-editable-regions/) — Allows you to upload images from your local storage, select existing images from your repository or DAM, and manage image details like title or alt text.
- [Source Editable Regions](/documentation/developer-articles/configure-source-editable-regions/) — Allows you to edit rich text stored in HTML.
- [Array Editable Regions](/documentation/developer-articles/configure-array-editable-regions/) — Allows you to add, remove, and reorder array values stored in front matter and generated by HTML-like files with templating.
- [Component Editable Regions](/documentation/developer-articles/configure-component-editable-regions/) — Allows you to edit registered Astro or React components.

For a complete list of HTML attributes for configuring *Editable Regions*, please read our [Editable Regions](/documentation/developer-reference/editable-regions/) reference documentation.


---

---
title: What are flags?
description: Learn about flags in CloudCannon and how you can use them to opt into app behavior.
url: https://cloudcannon.com/documentation/developer-articles/what-are-flags/
content_type: developer article
last_modified: 2026-02-10
---

Flags can enable optional behavior in CloudCannon. These optional settings are kept separate from other configuration for your Site because they have the potential to significantly alter your Site's behavior. This could be because a flag enables experimental or legacy behavior, or it enables a feature that could negatively affect your Site if misconfigured.

For this reason, we recommend you thoroughly understand the function of a flag before enabling it on your Site, or doing so on a separate branch to prevent flag behavior affecting your main Site.

> Flags can be tricky. If you need assistance, please don't hesitate to contact our friendly [support team](/support/).

You can find your Site Flags on the *Flags* page under *Site Settings*.

![A screenshot of the Flags page in your Site Settings shows three checkboxes for enabling opt-in behavior in CloudCannon.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Flags-Page.webp)

For more information about specific flags in CloudCannon, please read their dedicated documentation:

- [General Flags](/documentation/developer-articles/general-flags/)
- [Unified Configuration Flags](/documentation/developer-articles/unified-configuration-flags/)
- [Input Naming Convention Flags](/documentation/developer-articles/input-naming-convention-flags/)
- [Legacy Option Flags](/documentation/developer-articles/legacy-option-flags/)


---

---
title: What are rich text editors?
description: Learn about rich text editors in CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/what-are-rich-text-editors/
content_type: developer article
last_modified: 2026-03-29
---

A rich text editor is an interface for editing content on your Site, with tools to format and style your content. Rich text editors use a WYSIWYG editing area, meaning that the way you format the content in the editor will resemble the way it will look on your web page (WYSIWYG is an acronym for What-You-See-Is-What-You-Get). CloudCannon's rich text editors support Markdown, HTML, and MDX formats.

CloudCannon has three kinds of rich text editors:

- [The Content Editor](/documentation/user-articles/what-is-the-content-editor/)
- [Editable Regions](/documentation/developer-articles/define-editable-regions-in-your-html/) in the [Visual Editor](/documentation/user-articles/what-is-the-visual-editor/)
- [Rich Text Inputs](/documentation/user-articles/what-is-a-rich-text-input/)

![A screenshot of the Content Editor, an editing interface for content-heavy markup files.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor.webp)

For each rich text editor, you can configure the WYSIWYG toolbar (including which text and image formatting tools are available for each editor), the upload paths or filenames for any assets uploaded through an editor, and how CloudCannon should handle custom markup.

## The WYSIWYG toolbar

![A closeup of the WYSIWYG toolbar, including tools for formatting rich text.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-WYSIWYG-Toolbar.webp)

The *WYSIWYG toolbar* is found at the top of all rich text editors in CloudCannon. This toolbar is populated with tools to help you format your content. This might include adding images, links, and lists, changing the alignment of your text, or simple tools such as bolding, italicizing, or underlining text. The number of tools available in your *WSYIWYG toolbar* will depend on [how your rich text editor is configured](/documentation/developer-articles/configure-your-rich-text-editors/).

> As soon as you define one key for the WYSIWYG toolbar, CloudCannon will interpret any omitted keys as false and disable those options.

For a complete list of options available, please read our reference documentation on the [WYSIWYG toolbar in rich text editors](/documentation/developer-reference/configuration-file/types/_editables/).

## Paths

When you upload an asset through a rich text editor, you can specify which folder CloudCannon should upload that asset to. You can also define file names for those assets. For a complete list of options available, please read our reference documentation on [paths in rich text editors](/documentation/developer-reference/configuration-file/types/_editables/).

## Custom markup

Custom markup is any HTML or Markdown structure that cannot be recreated in the rich text editor (e.g., `<div>` tags or style attributes). This is normally any structure that cannot be produced by the *WYSIWYG toolbar*. Editing custom markup in a rich text editor is risky, as you can accidentally delete HTML objects that the rich text editor cannot recreate. For information about custom markup in rich text editors, please read our documentation on [best practices for rich text](/documentation/developer-articles/best-practices-for-rich-text/).

Each rich text editor has different defaults when editing custom markup. To configure how CloudCannon handles custom markup in your rich text editors, please read our reference documentation on [custom markup in rich text editors](/documentation/developer-reference/configuration-file/types/_editables/).


---

---
title: What are visual data bindings
description: Make your elements in the Visual Editor interact with their data in CloudCannon
url: https://cloudcannon.com/documentation/developer-articles/what-are-visual-data-bindings/
content_type: developer article
last_modified: 2026-04-11
---

> Since October 2025, this method of visual editing has been deprecated. CloudCannon cannot guarantee support for this feature. Please consider using [Editable Regions](/documentation/developer-articles/what-are-editable-regions/) or Bookshop.

Visual data bindings are a way to tell CloudCannon what elements correlate to what data. With this information CloudCannon can generate inline controls for editing directly onto the page. Editors can simply click what they want to edit, and change, remove, move, clone and add items directly. This, paired with visual data previews, means they can see what changes as they change it.

Data bindings tell CloudCannon to add overlays to the Visual Editor. These overlays are absolutely positioned on the page. Once clicked, the overlay is selected and the controls become available. These controls are dependant on the type of data that is bound. Edit, for example, will always be available. Clicking off the selected area will unselect the current element.

Elements that have data bindings can contain elements with data bindings. In this case, the child data bindings are only available to click once the parent is selected. This helps to keep the interface clean and reduce confusion.

## Adding a data binding

Data bindings are added by adding the `data-cms-bind` attribute to any element. The value of this attribute is the slug of object/key you want to edit. Starting from the base of your structure, name each item as a step towards your desired object. Each object or property is separated by a dot. An array item is denoted by an open square bracket, an integer starting from 0, followed by a closing square bracket (`[index]`). For example:

- `#title` Targets the title of the current page
- `#seo.title` Targets the title within the seo object
- `#people[0]` Targets the first array item in an array named people.
- `#people[0].title` Targets the title of the first array item within an array named people.

File: `index.html`

```html

<h1 data-cms-bind="#title">Edit the title</h1>

```

## Working with arrays

Data bindings on arrays give a few extra controls:

1. Add/Clone above and below
2. Move up/down and left/right depending on their relative position from their siblings
3. Remove with a double click confirm

## Working with z-indexes

Data binding overlays can sometimes get in the way of important navigation elements. By default, overlays are positioned between a 9000 and 9010 z-index. The lower bound of this range can be configured with the `--editor-panel-zindex` CSS variable. If your navigation is at 100 z-index, we recommend using a 90 z-index. In this example, you can use the following code snippet:

File: `index.html`

```css

:root {
  --editor-panel-zindex: 90;
}

```


---

---
title: What are visual data previews
description: Live editing on CloudCannon lets your editors see exactly what they are changing as they change it.
url: https://cloudcannon.com/documentation/developer-articles/what-are-visual-data-previews/
content_type: developer article
last_modified: 2026-04-11
---

CloudCannon sends events to your website when editors make changes to the front matter in the Visual Editor. Your JavaScript can capture these events and extend the functionality any way you want. Rerender your page as changes happen, or update your front matter with custom controls — CloudCannon puts the control in your hands.


---

---
title: What is a Custom Domain?
description: Learn about Custom Domains, subdomains, and subpaths, and whether you need one for your Site.
url: https://cloudcannon.com/documentation/developer-articles/what-is-a-custom-domain/
content_type: developer article
last_modified: 2026-03-31
---

A Custom Domain is a unique address used to identify a website. For example, CloudCannon's domain is [cloudcannon.com](https://cloudcannon.com/). The domain is the part of your URL that users will most likely remember. You can purchase a Domain Name from a Domain Registrar.

- **Domain Name** — The unique address used to access a website (e.g., [cloudcannon.com](https://cloudcannon.com/)). This is made of a name of your choice (normally your brand name) and a TLD from the [available list](https://www.icann.org/resources/pages/tlds-2012-02-25-en) (e.g., .com, .org, .site, .io).
- **Domain Registrar** — A third-party company that handles the reservation of domain names and assigns IP addresses to domain names. Most CloudCannon users purchase a domain name from a Registrar (e.g., [Cloudflare Registrar](https://www.cloudflare.com/en-gb/products/registrar/), [NameCheap](https://www.namecheap.com/)).

![A diagram of a URL shows labels for protocol, subdomain, domain, top-level domain, subdirectory, slug, and path.](assets/diagrams/CloudCannon-Documentation-URL-Structure-Diagram.png)

To use a Custom Domain on CloudCannon you can [connect a Custom Domain to your Organization](/documentation/developer-articles/connect-a-custom-domain-to-your-organization/), then [add a Custom Domain to your Site](/documentation/developer-articles/add-a-custom-domain-to-your-site/). Every time you [save changes](/documentation/user-articles/save-your-changes/) to your Site's content, CloudCannon will [build your Site](/documentation/developer-articles/what-is-a-site-build/) and serve the new content on your Custom Domain.

## Do I need a Custom Domain?

Owning a Custom Domain for business or personal use is useful to improve brand recognition and search engine optimization.

You don't need to purchase a Custom Domain to create and edit a Site on CloudCannon, as CloudCannon automatically provides a free [Testing Domain](/documentation/user-articles/what-is-a-testing-domain/) to all Sites. However, we don't recommend using your Testing Domain as your primary URL for two reasons.

One, you cannot change the automatically generated testing domain name without creating a new Site on CloudCannon. The automatically generated domain may not be right for you or your Site. You can generate a new one by creating a new Site with the same files; however, this can be inefficient.

Two, by default, CloudCannon automatically de-indexes Testing Domains so that they do not appear in search engines.

## Using subdomains and subpaths

You can separate and organize your website content into multiple Sites on CloudCannon and serve that content on a specific subdomain or subpath of your Custom Domain.

- **Base Domain** — The unmodified domain name of a website, including the TLD (e.g., example.com or cloudcannon.com). Also called a root or apex domain.
- **Subdomain** — An additional name on the front of your URL, prefixing your base domain name (e.g., "docs" in docs.example.com or "blog" in blog.example.com).
- **Subpath** — An additional name prefixing your page slug and suffixing your base domain name (e.g., "articles" in example.com/articles/what-is-a-custom-domain/, or "staff" in example.com/staff/). Also called a subdirectory.

Separating your content onto different CloudCannon Sites can improve clarity for your content editors and users and enable you to use separate Git repositories for distinct areas of your website.

Let's walk through an example.

We want to separate the content on our website for our team members and users to improve clarity around the layout of information. To do this, we can create two CloudCannon Sites for our team members and two subdomains for our users.

- Site One: Our website's Marketing content. This is connected to our main domain (e.g., example.com) and uses our Marketing Git repository with branded page themes.
- Site Two: Our website's Documentation content. This is connected to a subdomain (e.g., docs.example.com) and uses our Documentation Git repository with simpler page themes.

We could also accomplish the same goal by hosting content on the dedicated subpaths (example.com and example.com/docs/). Whether you use subdomains or subpaths is a matter of personal preference.

> Having your website content on separate CloudCannon Sites means you can specify which content different teams are allowed to edit using [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/).

If you use [CloudCannon DNS](/documentation/developer-articles/configure-cloudcannon-dns/), CloudCannon will redirect all unconfigured subdomains to the main domain. For example, suppose you have one Site connected to example.com and another Site connected to the subdomain docs.subdomain.com. In that case, CloudCannon will redirect anyone trying to access an unconfigured subdomain (e.g., app.example.com) or a misspelled subdomain name to the main domain, example.com.

For more information on adding and managing subdomains and subpaths, please read our documentation on [adding a Custom Domain to your Site](/documentation/developer-articles/add-a-custom-domain-to-your-site/) and [updating the fallback redirect for your Custom Domain](/documentation/developer-articles/update-the-fallback-redirect-for-your-custom-domain/).


---

---
title: What is a form?
description: A brief introduction to forms on CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/what-is-a-form/
content_type: developer article
last_modified: 2026-04-11
---

> Forms are only available for Sites hosted through CloudCannon. If you host your Site externally, or use CloudCannon in [Headless Mode](/documentation/developer-articles/what-is-headless-mode/), Forms will not work.

CloudCannon forms allow you to receive form submissions from visitors to your website without requiring your own backend server. With CloudCannon forms, you can view your form submissions in CloudCannon, forward them to an email address, or integrate them with your workflow using webhooks. All submissions can be exported from within CloudCannon.

Forms are easy to set up and integrate a number of external providers. Spam checkers reduce the noise with optional extra security with Google ReCaptcha or hCaptcha.

![](assets/diagrams/forms-diagram.svg)

CloudCannon integrates with four external providers at the moment:

1. IFTTT
2. Make
3. Slack
4. Zapier

Reach out if you need more from forms for your next project. We plan to build on forms in the future. Knowing we can help our customers could speed things up.


---

---
title: What is a Pull Request template?
description: Learn how Pull Request templates can configure the default and allowed values for Pull Requests on your Site.
url: https://cloudcannon.com/documentation/developer-articles/what-is-a-pull-request-template/
content_type: developer article
last_modified: 2026-03-04
---

If your *Site* uses [Pull Requests](/documentation/developer-articles/merging-and-pull-requests/) as the publishing method, you can [configure a Pull Request template](/documentation/developer-articles/configure-a-pull-request-template/) to define the default values for the title and body of your Pull Requests.

![A screenshot of the Publishing page shows the Pull Request template dropdown for selecting a template.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Publishing-Page-Create-Pull-Request-with-Template.webp)

When you create a Pull Request, you can select which Pull Request template you want to use with the dropdown menu on the *Publishing* page.

By defining a Pull Request template, you can define the default values for title and body fields, make fields required, control which rich text formatting options are allowed in your Pull Request, and reference a Markdown file for more complex Pull Request content.


---

---
title: What is a schema?
description: Learn about schemas in CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/what-is-a-schema/
content_type: developer article
last_modified: 2026-03-29
---

A schema is a predefined template that determines what should populate a [collection](/documentation/user-articles/what-is-a-collection/) file. You can configure several schemas for each collection, creating a list of file templates for you and your team.

Schemas are excellent for creating files with consistent content and populating the initial contents of a new file. Schemas can apply to structured, markup, and combination files by containing both front matter and markup content or only data or markup content. When you use a schema to populate a new file, you can be sure that the inputs you need are available in the sidebar of the [Visual](/documentation/user-articles/what-is-the-visual-editor/) or [Content Editor](/documentation/user-articles/what-is-the-content-editor/).

A blog schema might contain title, author, and hero image inputs in the front matter. A changelog schema for a technical documentation site might contain a date input in the front matter and headings for “Features” and “Fixes” in the Markdown content. A review schema might contain inputs for title, author, and rating, and “Today, we are reviewing the…” as the opening line in the Markdown content.

Once you have configured your schemas, your team members can easily create new files for a collection by clicking the *+ Add* button in the top right of the collection browser and selecting the file template they want from a dropdown menu.

![A closeup of the Collection Browser shows the controls bar and multiple options in the Add dropdown.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-Controls-Add-Menu-Dropdown.webp)

> Schemas are a good place to configure your [inputs](/documentation/user-articles/what-are-inputs/). Inputs configured in your schema will only affect files created with that schema.

For more information, including a list of all keys available for schema configuration, please read our reference documentation for [schemas](/documentation/developer-reference/configuration-file/collections_config/*/schemas/).

## Default behavior for new collection files

You can add new files to your collection without configuring a schema. Clicking the *+ Add* button in the top right of the collection browser will clone the last file in the collection and clear the content and values for any inputs in the front matter. This behavior is convenient if you have simple collection files or do not want to configure schemas.

The default behavior may not be right for you if:

- Your collection does not contain at least one file.
- You want to have different file types in your collection.

Because the default behavior clones existing files in a collection, CloudCannon cannot create a new file if the collection is empty. Additionally, cloning existing files does not allow for variation in file structure. You can manually add different inputs and content to your files. However, this can become inefficient to maintain.

You can overcome these limitations by configuring schemas for your collections.


---

---
title: What is a Site build?
description: Learn about Site builds in CloudCannon, including build logs and how building supports some CloudCannon features.
url: https://cloudcannon.com/documentation/developer-articles/what-is-a-site-build/
content_type: developer article
last_modified: 2026-03-31
---

A “build” is when CloudCannon converts all your Site files into a single, functional website. By building your Site in CloudCannon, you can make the most of features such as:

- [The Visual Editor](/documentation/user-articles/what-is-the-visual-editor/)
- Preview screenshots for pages in your [Collection](/documentation/user-articles/what-is-a-collection/) browser
- The [Testing Domain](/documentation/user-articles/what-is-a-testing-domain/)
- Hosting your Site on a [Custom Domain](/documentation/developer-articles/what-is-a-custom-domain/)

## What happens during a build?

CloudCannon uses a CI/CD (Continuous Integration/Continuous Delivery) system. Every time you trigger a build of your Site, CloudCannon will:

1. Download your files onto our server.
2. Run your selected install commands (e.g., `npm install`, `bundle install`).
3. Run your selected build commands (e.g., `npm run build`).
4. Index your output files.
5. Upload your output files to CloudCannon to generate previews (i.e., the test domain, visual editor, and in-app screenshots) and deliver them to your live domain (if you are [hosting with CloudCannon](/documentation/developer-articles/configure-cloudcannon-dns/)).

Additionally, you can [configure build hooks](/documentation/developer-articles/extending-your-build-process-with-hooks/) to run extra commands during your Site build. Build hooks are useful for downloading external data, running test commands, and more.

CloudCannon runs your build commands using `bash` in an isolated environment powered by `Ubuntu`. In addition to bash, CloudCannon includes several other programs and libraries your Site may need, such as Deno, Go, Node.js, and Ruby. You can [pin a version of these dependencies](/documentation/developer-articles/pin-your-dependency-version/) to maintain consistency between builds.

> For more information about CloudCannon's build environment, please contact our [support team](/support/).

## Starting a build

> **Permissions required**
> 
> Members of the Owners, Developers, or Technical Editors [Default Permission Groups](/documentation/user-articles/what-are-default-permission-groups/), or [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) with the `site:build` (or, more specifically, `site:build:trigger`) permission, can trigger a *Site* build.

Setting up your first Site build requires some configuration. For more information, please read our documentation on [configuring your first build](/documentation/developer-articles/configure-your-first-build/). Once you have completed your first build you can trigger subsequent builds at any time.

You can start a build by:

- Committing edits to your Git repository after [editing your files](/documentation/user-articles/edit-your-files/) in CloudCannon or locally
- Updating your build configuration, such as your [SSG](/documentation/developer-articles/select-your-ssg/), [command line options](/documentation/developer-articles/configure-your-command-line-options/), [caching options](/documentation/developer-articles/configure-caching-between-builds/), or [unlocking builds on your Site](/documentation/developer-articles/lock-builds-for-your-site/).
- Clicking the *Rebuild* button on the *Summary* tab of your *Site Dashboard*.
- Configuring [manual build scheduling](/documentation/developer-articles/scheduling-your-builds-manually/) or [automatic build scheduling](/documentation/developer-articles/scheduling-your-next-build-automatically/).
- Using the CloudCannon API.

> **This feature is available through a private Beta.**
> 
> The CloudCannon API is currently available through a private Beta. Want to chat about whether this feature is right for you? Our support team is always [happy to hear from you](mailto:success@cloudcannon.com?subject=A%20question%20about%20the%20CloudCannon%20API).

You can prevent a Site from building by [locking builds](/documentation/developer-articles/lock-builds-for-your-site/).

## Reading your build output logs

CloudCannon produces a log every time it runs a build. You can use your build log to follow CloudCannon's build process and diagnose your build if CloudCannon runs into an error.

While CloudCannon is building your Site, you can read the build output files by clicking on the *View Output* button in the notification at the bottom right of the app. This will open the build terminal.

![A screenshot of the Content Editor with the Building notification in the bottom right shows a button labeled View Output.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Building-Toast-Notification.webp)

![A screenshot of the Content Editor with the Build Terminal modal open shows the progress of the current Site build.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Build-Terminal-Modal.webp)

The build terminal has three tools: the *Copy Output* button and the checkboxes for *Scroll to bottom* and *Show timing*. The *Copy Output* button lets you copy your build log as plain text. The status of the *Scroll to bottom* and *Show timing* checkboxes will persist between builds. These checkboxes control whether the terminal displays the beginning or the end of the log by default and whether event times are logged, respectively.

You can view all your build logs on the *Builds* tab of your *Site Dashboard*.

![A screenshot of the Site Dashboard Builds tab shows that the first build of a Site is running.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Dashboard-Builds-Tab.webp)

## Caching between builds

To improve the speed of your builds, CloudCannon attempts to send consecutive builds from a single Site to the same server. You can configure file caching so that CloudCannon only uses server time for files updated between builds. This allows you to skip expensive and repetitive operations.

Caching is great for minimizing the effect of build steps that are typically slow, such as image optimization, installing dependencies, and external data fetching. For more information, please read our documentation on [configuring caching between builds](/documentation/developer-articles/configure-caching-between-builds/).


---

---
title: What is a Snippet?
description: Learn how Snippets can improve your editing experience in CloudCannon. A Snippet is a component that complements your Markdown content.
url: https://cloudcannon.com/documentation/developer-articles/what-is-a-snippet/
content_type: developer article
last_modified: 2026-03-29
---

A Snippet is a predefined component that complements your Markdown content. Snippets are great for building an interactive page editing experience without touching the underlying code.

The name “Snippet” comes from “a snippet of source code” in your rich text content. However, Snippets in CloudCannon are not limited to just code. Snippets can accomplish many jobs. One might be a wrapper to contain shortcodes or templating language, while another might be a markup heading.

Snippets excel at providing a way to:

- Represent and create any HTML or Markdown structures in your rich text editor that you cannot add using the *WYSIWYG toolbar.*
- Edit the value of any HTML parameters in a component using a GUI (rather than directly interfacing with the code).

Although Snippets can accomplish a variety of tasks, all Snippets consist of three parts:

- Code in the Source Editor
- A preview block in the rich text editor
- A *Data panel* for editing the values of your Snippet

![A screenshot of the Content Editor shows a blog post with a YouTube Snippet in the rich text content and the Snippet data panel open for editing.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-YouTube-Snippet-Edit-Panel.webp)

You can configure as many snippets as you need, creating a library of components for you and your team. A video snippet might utilize a Hugo shortcode to embed a YouTube video and allow you to add a video ID, title, class, and autoplay status. A callout snippet might highlight a section of text as a warning or as useful information depending on a select input in the Data Panel.

Snippets are most useful in the [Content Editor](/documentation/user-articles/what-is-the-content-editor/) and in [rich text inputs](/documentation/developer-articles/configure-your-rich-text-editors/), although they can appear in the [Visual](/documentation/user-articles/what-is-the-visual-editor/) and [Data Editors](/documentation/user-articles/what-is-the-data-editor/).

> We recommend using Snippets to create custom styles in your Markdown rather than [adding custom markup](/documentation/developer-articles/best-practices-for-rich-text/).

Once you have configured your Snippets, your team members can easily add them to any Markdown content by clicking the *Insert snippet* button in the *WYSIWYG toolbar* and selecting a Snippet from the searchable pop-up modal.

![A closeup of the WYSIWYG toolbar in the Content Editor shows the Insert Snippet button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Snippet-Toolbar.webp)

![A screenshot of the Snippets pop-up modal in the Content Editor shows a selection of Snippets available to insert into rich text.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Insert-Snippet-Modal.webp)

Snippets appear as inline or paragraph-level blocks in your rich text editor. Inline snippets are useful when you do not want to disrupt the surrounding text. Block snippets create clear sections in your Markdown files. By default, snippets will adapt to where they are inserted in the rich text editor: they will appear inline if inserted within a line of text, or as a block if inserted on their own line. You can configure this behavior to control whether a snippet always appears as inline or block.

![A screenshot of the Content Editor shows a blog post with an inline Param Snippet within a paragraph of text and the Snippet data panel open for editing.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Inline-Snippet-Edit-Panel.webp)

By clicking on the Snippet you can open the Snippet *Data panel*, which allows you to change the parameters of the Snippet. The *Data panel* provides an easy-to-use interface so non-technical content creators never need to interact with your code.

> You can insert snippets in any rich text editor. This includes the Content Editor and rich text inputs. As snippets can contain rich text inputs, you can even insert a snippet inside of a snippet!

## Snippet types

In CloudCannon, you can choose between Snippet templates and custom Snippets.

- **Snippet templates** — A predefined set of Snippets.
- **Custom Snippet** — A Snippet you create by configuring CloudCannon's underlying snippet parser.

Most sites can use Snippet templates. Snippet templates require little to no configuration. Some SSGs provide libraries of Snippets (also called shortcodes). Other Snippet templates, like MDX components, can be used for a variety of SSGs.

CloudCannon supports the following Snippet templates:

- [Docusaurus Components](/documentation/developer-articles/snippets-using-docusaurus-components)
- [Eleventy Shortcodes](/documentation/developer-articles/snippets-using-eleventy-shortcodes/)
- [Hugo Shortcodes](/documentation/developer-articles/snippets-using-hugo-shortcodes/)
- [MDX Components](/documentation/developer-articles/snippets-using-mdx-components/)
- [Python Markdown](/documentation/developer-articles/snippets-using-python-markdown/)

Custom Snippets are useful if you want to create something more complicated than templates allow or if no Snippet library is available for your SSG. Configuring custom Snippets is more complicated than using Snippet templates and is not necessary for most sites. However, it does provide more flexibility.

To create a custom Snippet, get in touch with our [support team](/support/).

## Enabling the Snippet button in the WYSIWYG toolbar

By default, CloudCannon will show the *Insert snippet* button in the *WYSIWYG toolbar* if you have at least one Snippet. The *WYSIWYG toolbar* appears in the [Content Editor](/documentation/user-articles/what-is-the-content-editor/) and in [rich text inputs](/documentation/user-articles/what-is-a-rich-text-input/).

If you have already [customized which options are available](/documentation/developer-articles/configure-your-rich-text-editors/) in your *WYSIWYG toolbar* using the `_editables` key in your [CloudCannon configuration file](/documentation/developer-articles/create-your-cloudcannon-configuration-file/), please ensure that `snippet: true` is included.

File: `cloudcannon.config.yml`

```YAML

_editables:
  content:
    # include all other toolbar keys here
    snippet: true

```

For more information, read our documentation on [configuring your rich text editors](/documentation/developer-articles/configure-your-rich-text-editors/).


---

---
title: What is a structure?
description: Learn about structures in CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/what-is-a-structure/
content_type: developer article
last_modified: 2026-03-29
---

A structure is a predefined, custom template that determines what should populate an [Array](/documentation/user-articles/what-is-an-array-input/) or [object input](/documentation/user-articles/what-is-an-object-input/). With the click of a button, you can easily add fields to an array or object from your list of predefined structures.

Structures are excellent for creating items you want to repeat across your site. An image gallery structure might contain fields for an image, an author, and a caption. A testimonial structure might contain fields for a quote and an author. An array using page-building components might reference several structures for common content blocks, such as a hero image, call to action, or video block.

Once you have defined your structures, your team members can easily add, remove, reorder, and update structure content using the [Data Editor](/documentation/user-articles/what-is-the-data-editor/) or the sidebar of the [Visual](/documentation/user-articles/what-is-the-visual-editor/) or [Content Editor](/documentation/user-articles/what-is-the-content-editor/).

![The sidebar of the Content Editor shows an array with structure options configured.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Array-Input-Structure-Preview.webp)

For more information, including a list of all keys available for structure configuration, please read our [structures](/documentation/developer-reference/configuration-file/types/_structures/) reference documentation.

## Structures and arrays

Structures and arrays go hand-in-hand. The [Array input](/documentation/user-articles/what-is-an-array-input/) contains an ordered list of related items, while a structure is a template that determines what data CloudCannon should add to new array items. By creating structures, you can define different objects that your team members can add to arrays within your site.

When you first connect your site files and make them editable in the Data Editor, CloudCannon will automatically detect arrays in your front matter and data files.

You can add new items to your arrays without the need for configuration. Clicking the *+ Add* button for an array will clone the last array item and clear the data from the new item to create a blank array object. This behavior is convenient if you have simple arrays, or do not want to configure structures.

The default array behavior may not be right for you if:

- Your array does not contain at least one object.
- You want to have different object types in your array.

Because the default behavior clones existing array items, CloudCannon will prevent you from removing the last item from an array if you do not have a structure configured. Additionally, cloning existing items does not allow for variation of object types. You can add different objects to the array manually using the [Source Editor](/documentation/user-articles/what-is-the-source-editor/). However, this can become inefficient to maintain.

You can overcome these limitations by configuring data structures to add to your arrays.

> Alternatively, configure inline [Array inputs](/documentation/user-articles/what-is-an-array-input/) to set which input is used for array items. Inline array inputs also allow an array to be empty.

## Structures and objects

Structures also work for individual objects. The [object input](/documentation/user-articles/what-is-an-object-input/) can contain a maximum of one value. After you reference a structure key from an object input, team members can select which structure they want to add to that object. Once a value is selected, you cannot add more until the value is replaced or deleted.


---

---
title: What is an output file?
description: Learn about the output files your SSG creates and how CloudCannon uses them in the app.
url: https://cloudcannon.com/documentation/developer-articles/what-is-an-output-file/
content_type: developer article
last_modified: 2026-03-29
---

When you [build](/documentation/articles/what-is-a-site-build/) your *Site*, CloudCannon will run the build command appropriate for your Static Site Generator (SSG). Your SSG will build your source files into your output files. These output files are what your website visitors see on the Internet, with each file served on a unique output URL.

You can view your output files after each successful build using your [Testing Domain](/documentation/articles/what-is-a-testing-domain/), or [Custom Domain](/documentation/articles/what-is-a-custom-domain/) if you have one configured.

## How does CloudCannon use your output files?

CloudCannon uses your *Site's* output files in two places within the app: as the interactive webpage preview in the *Visual Editor* and as the webpage screenshots on *File Cards* in the *Collection Browser*.

![A screenshot of the Visual Editor shows yellow Editable Regions boxes around the title and author fields on the webpage.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Visual-Editor-Frontmatter-Text-Editable-Regions.webp)

![A screenshot of the Collection browser shows previews of several blog files, sort and view dropdowns, the collection filter, and the + Add button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser.webp)

To open the correct output file in the *Visual Editor* and show the correct screenshot on a *File Card*, CloudCannon needs to match the output files to the source files. However, most modern websites do not have a one-to-one relationship between source files and output files. For example, the output file for your "Home" page will be `index.html`, but the content for this file could be stored across multiple source files (e.g., one for navigation, another for the footer, and a third for page content).

Once your SSG has built your *Site*, CloudCannon automatically matches output files with their corresponding source files by determining the likely output URL for each file.

If CloudCannon did not determine the correct output URL for your source files, you may notice the wrong webpage screenshot in the gallery section of your *File Cards* (or no screenshot), or that the *Visual Editor* opens to an incorrect webpage. You can fix this issue by [updating the output URL](/documentation/articles/update-the-output-url-for-a-webpage-preview/) CloudCannon uses to match an output file to a source file.

If you don't want a *Collection* to use the *Visual Editor* or see screenshots in the *Collection Browser*, or if CloudCannon has incorrectly determined an output URL for a non-output *Collection*, you can [disable output URL matching for a Collection](/documentation/articles/disable-webpage-previews-for-a-collection/).


---

---
title: What is an SSL certificate?
description: Learn about SSL certificates and how they can protect user data on your website.
url: https://cloudcannon.com/documentation/developer-articles/what-is-an-ssl-certificate/
content_type: developer article
last_modified: 2026-04-11
---

> Managing your SSL certificate on CloudCannon requires you to host your Site through CloudCannon. If you are hosting your Site through an external service, please review their documentation on SSL certification.

An SSL certificate (or a TLS certificate) is a periodically regenerated digital certificate that supports your website's authenticity and enables encryption for greater security between your web server and the visitor's browser. SSL certification is important to:

- Prevent others from intercepting the information passing between the server and the browser.
- Help users distinguish between the real version of your website and any fake versions created by other people.
- Verify ownership of a website.

We recommend all websites edited on CloudCannon use an SSL certificate.

## HTTP vs HTTPS

HTTP, or the HyperText Transfer Protocol, is the primary method used by the internet to transfer information between a browser and a web server. The acronym HTTP appears at the beginning of a website's URL.

Websites with a valid SSL certificate use HTTPS instead, where the "S" stands for Secure. This means it is very easy to visually determine if a website is using a secure protocol.

![A diagram of a URL shows labels for protocol, subdomain, domain, top-level domain, subdirectory, slug, and path.](assets/diagrams/CloudCannon-Documentation-URL-Structure-Diagram.png)

Most browsers will automatically warn users before they attempt to visit an unsecure website (i.e., HTTP instead of HTTPS). Depending on your browser, this can take the form of a white warning page where the user must explicitly choose to continue to the unsecure website.

Warnings about unsecure websites can lead to a higher user bounce rate (where users immediately "bounce" off your website before seeing any of your content). This might be because users are security conscious or because they lose interest due to an inefficient experience.

You can avoid these issues by adding an SSL certificate to your Site to enable HTTPS.

## How do SSL certificates work?

SSL certificates contain the following details about your Site:

- **Domain Name** — The address used to access a website (e.g., [cloudcannon.com](https://cloudcannon.com/)).
- **Certificate expiration date** — The date a certificate expires. This is normally a year after it was generated.
- **Public key** — A string used to encrypt data, protecting communication channels from unauthorized access. Data can only be decrypted with the corresponding Private key.
- **Certificate Chain** — A sequence of certificates that links the SSL certificate for your Site to a trusted certificate authority, providing legitimacy to your SSL certificate.

SSL certificates also come with a private key, which is not shared with the user's browser.

- **Private key** — A string used to decrypt data.

> Your private key should only be provided to your DNS provider. Do not write down your Private key in a publicly accessible or unsecure place. If you think the security of your Private key has been compromized, please generate a new SSL certificate.

When a browser attempts to connect to your website, it uses a process called a *TLS handshake*. This process validates the identity of the web server, the domain of your website, and prevents unauthorized access to the data passing between the user and your website.

In simple terms, the *TLS handshake* includes the following steps:

1. The user's browser contacts the web server hosting your website, specifying what version of TLS the browser is using and a random string called a "Client Random".
2. The web server replies to the browser with the SSL certificate and a random string called a "Server Random".
3. The browser will verify the SSL certificate with the certificate authority that issued it, confirming the authenticity of the web server and the domain.
4. The browser contacts the web server again with a random string encrypted with the Public key from the SSL certificate.
5. The web server uses the corresponding Private key to decrypt the message.
6. If the web server and the user's browser agree on the strings for Client Random, Server Random, and the decrypted message, then the web server will allow the browser to access the website in an encrypted session.

This process only takes milliseconds to complete, so it will not affect the user's experience on your website.

Depending on your browser, a padlock icon will appear near your URL once you add an SSL certificate to your website. You can click on this icon to review the publicly available certificate information.

## TLS Version

To configure an SSL certificate for your Site on CloudCannon, you must specify the minimum TLS version.

- **Minimum TLS Version** — The minimum version of TLS that a user's browser must have to be allowed to access your Site.

A higher TLS version is a stronger cryptographic standard, including fixes for known vulnerabilities in previous versions. On CloudCannon, the minimum TLS version you can use for your Site is 1.2, however 1.3 is available if you require it.

## Which SSL certificate is right for your domain?

On CloudCannon, any Site with a [Custom Domain](/documentation/developer-articles/what-is-a-custom-domain/) can use an [auto-generated SSL certificate](/documentation/developer-articles/add-an-auto-generated-ssl-certificate/) or a [custom SSL certificate](/documentation/developer-articles/add-a-custom-ssl-certificate/). Auto-generated SSL certificates can be either wildcard or single-domain certificates.

### Auto-generated SSL certificates

CloudCannon provides a free auto-generated SSL certificate by default for all Sites. An autogenerated SSL certificate can be a wildcard certificate or a single-domain certificate.

- **Wildcard SSL certificate** — A certificate that protects a single domain and all its subdomains (e.g., example.com and its subdomains blog.example.com, support.example.com, app.example.com etc.).
- **Single-domain SSL certificate** — A certificate that protects a single domain. This is useful if you only have one CloudCannon Site which is hosted on a subdomain.

CloudCannon offers auto-generated SSL certificates through ZeroSSL and Cloudflare, and will automatically renew your certificate each year so you Site is never unsecure.

A wildcard SSL certificate may be right for you if:

- You host multiple Sites on CloudCannon using a base domain and subdomains.
- You are using [CloudCannon DNS](/documentation/developer-articles/configure-cloudcannon-dns/).

A single-domain SSL certificate may be right for you if:

- You only host Sites on CloudCannon on subdomains.
- You are using [CloudCannon DNS](/documentation/developer-articles/configure-cloudcannon-dns/).

If you select an auto-generated SSL certificate for your Site hosted on CloudCannon, there are a few limitations you should consider.

- If you are using an [external DNS provider](/documentation/developer-articles/configure-external-dns/), some additional configuration is required. For more information, please read our documentation on [adding TXT DNS records](/documentation/developer-articles/add-an-auto-generated-ssl-certificate/#add-txt-dns-records).

For more information, please read our documentation on adding an auto-generated SSL certificate.

### Custom SSL certificates

You can purchase a custom SSL certificate from a trusted third-party service and add your certificate details to CloudCannon.

- **Custom SSL certificate** — A certificate you have generated using a trusted third-party service (e.g., GoDaddy, Google, AWS, Cloudflare). Most web hosting services also provide the option to generate custom SSL certificates.

A custom SSL certificate may be right for you if:

- You already have an SSL certificate purchased through a third-party provider.
- Your company's security policies require you to have an SSL certificate from an internally approved authority.

For more information, please read our documentation on [adding a custom SSL certificate](/documentation/developer-articles/add-a-custom-ssl-certificate/).


---

---
title: What is authentication?
description: Learn about authentication in CloudCannon and how you can use it to control visitor access to your website.
url: https://cloudcannon.com/documentation/developer-articles/what-is-authentication/
content_type: developer article
last_modified: 2026-03-29
---

Authentication is the process of verifying a user's identity. When you host your Site on CloudCannon, you can enable an authentication method to control who is allowed to see the live content of your website.

CloudCannon supports three authentication methods: [password authentication](/documentation/developer-articles/enable-password-authentication/), [user account authentication](/documentation/developer-articles/enable-user-account-authentication/), and [SAML authentication](/documentation/developer-articles/enable-saml-authentication/).

- **Password Authentication** — Users must enter a Site password you configure to see your content.
- **User Account Authentication** — If you have invited a user to your Site, they must enter their email address and personal password to see your content.
- **SAML Authentication** — Users must log in through a third-party application (e.g., Google, OneLogin, etc.) to see your content.

> You must [host your Site on CloudCannon](/documentation/user-articles/what-is-web-hosting/#hosting-on-cloud-cannon) to use any of these authentication methods.

You can update the authentication method for your site on the *Authentication* page under *Site Settings*.

![A screenshot of the Authentication page under Site Settings shows that no authentication method has been selected for this site.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Authentication-None.webp)

## Why enable authentication?

Authentication works well for Sites where you want to segregate what content your visitors have access to.

For example, if your Site is for internal company use only, you may want users to log in before they can see your website's content. Or, if your Site has a "Member's Only" section but still maintains public pages, you can authenticate a user's identity to access that section.

By default, CloudCannon's authentication methods affect every page on your Site. However, you can require authentication for a specific subset of pages using [authenticated routes](/documentation/developer-articles/configure-authenticated-routes/) or by hosting your Site on a [subpath](/documentation/developer-articles/add-a-custom-domain-to-your-site/).

## Machine users

In some cases, you may want a trusted third-party application to access your Site. This could be a machine user or script that uses resources from your Site to accomplish a task. Machine users can bypass authentication by providing the correct [bearer token](/documentation/developer-articles/generate-a-bearer-token/) when they request your webpage.


---

---
title: What is Configuration Mode?
description: Learn about Configuration Mode, which allows you to add content to your CloudCannon Configuration File.
url: https://cloudcannon.com/documentation/developer-articles/what-is-configuration-mode/
content_type: developer article
last_modified: 2026-03-20
---

*Configuration Mode* is a tool for updating the configuration of your *Site*. The *Configuration Mode switch* on the right of your *Site Header* allows you to toggle *Configuration Mode* on and off.

![A screenshot of the Site Header tools shows the Avatar List, Configuration Mode toggle, and the Save button with one unsaved change.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Header-Tools-Post-Build.webp)

When *Configuration Mode* is on, CloudCannon will display *Edit configuration* buttons next to each element of the app you can configure. These *Edit configuration* buttons are all in purple, making them easy to find and visually distinct from other UI elements.

![A screenshot of the Collection Browser shows several UI elements highlighted in Configuration Mode purple.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-Configuration-Mode-On.webp)

Clicking on one of the *Edit configuration* buttons will open a modal or data panel with fields for configuring the UI element. You will be able to see any visual changes in CloudCannon in real time, and all your changes will be added to your [CloudCannon Configuration File](/documentation/developer-articles/what-is-the-cloudcannon-configuration-file).

When *Configuration Mode* is off, CloudCannon hides all the *Edit configuration* buttons, creating an uncluttered interface for content creators. We recommend spending most of your time with *Configuration Mode* off for a better editing experience, but you can always turn it on to make a quick change your *Site* configuration.

> **Who can use*****Configuration Mode*****?**
> 
> Turning on *Configuration Mode* only affects the way your Site looks for you; the purple *Edit configuration* buttons do not appear for other users of your *Site*.
> 
> You can restrict the capacity to use *Configuration Mode* to specific team members using permissions. We recommend you check out this guide after you have finished *Getting Started*.


---

---
title: What is DNS?
description: Learn about DNS and how the user's browser gets the correct IP address for a website.
url: https://cloudcannon.com/documentation/developer-articles/what-is-dns/
content_type: developer article
last_modified: 2026-04-11
---

The Domain Name System (DNS) allows your computer to translate a domain name into an IP address. Domain names are easier for users to remember and recognize than IP addresses (e.g., 192.168.1.1 in IPv4, or 2400:cb00:2048:1::c629:d7a2 in IPv6).

- **Domain Name** — The unique address to access a website (e.g., [cloudcannon.com](https://cloudcannon.com/)).
- **Internet Protocol (IP) address** — A unique string used to identify a device connected to the internet (e.g., a user's computer or phone or the web server hosting your website).

When a user enters a domain name into their Internet browser or clicks a link to access a website, the domain name must be translated (or resolved) to a machine-friendly IP address in a process called *DNS lookup*.

## How does DNS lookup work?

The *DNS lookup* process involves several servers, each contributing to translating the domain name.

- **DNS Resolver** — The server responsible for translating a domain name into an IP address. This server is maintained by the user's Internet service provider. Also known as a recursive resolver or a DNS recursor.
- **Root Nameserver** — The first server in a DNS lookup. This server is an index for TLD Nameservers.
- **TLD Nameserver** — The server responsible for a specific TLD in a URL (i.e., .com, .net, .org, etc.). This server is an index for all Authoritative Nameservers with a given TLD.
- **Authoritative Nameserver** — The server responsible for maintaining the DNS records for a given domain. Often just called "the nameserver".
- **Web Server** — The server responsible for hosting your website content.

![A diagram of the DNS lookup process, where the DNS Resolver contacts various servers for the matching IP address for a given domain name.](assets/diagrams/CloudCannon-Documentation-DNS-Lookup-Diagram.png)

In simple terms, the *DNS lookup* includes the following steps:

1. The user's browser provides the domain name of the website they want to access (e.g., cloudcannon.com) to the DNS Resolver.
2. The DNS Resolver contacts the Root Nameserver and requests the list of TLD nameservers that manage the TLD (e.g., .com, .org) for a given domain.
3. The Root Nameserver replies to the DNS Resolver.
4. The DNS Resolver contacts a Top Level Domain (TLD) nameserver for the domain name and requests the Authoritative Nameserver that manages the domain name (e.g., cloudcannon.com).
5. The TLD Nameserver replies to the DNS Resolver.
6. The DNS Resolver contacts the Authoritative Nameserver and requests the IP address that matches the domain name.
7. The Authoritative Nameserver replies to the DNS Resolver.
8. The DNS Resolver provides the correct IP address for the domain name to the user's browser.
9. The user's browser contacts the Web Server for the domain name using the IP address and requests the website content.
10. The Web Server delivers the website content to the user's browser.

This process only takes milliseconds to complete, so it will not affect the user's experience on your website.

In many cases, the user's browser does not have to complete a *DNS lookup* at all, especially if the user is trying to visit a website they have been to before. After the browser has received the correct IP address for a domain name at least once, it caches that information for a period of time. If a user tries to access that domain while the IP address is cached, the browser can skip the *DNS lookup* process.

## What is a nameserver?

There are many nameservers involved in the *DNS Lookup* process; however, the word "Nameserver" typically refers to the authoritative nameserver, which manages all the DNS records for a particular Domain Name.

- **Nameserver** — Stores DNS records for a given Domain Name.

Almost all domains rely on multiple nameservers for redundancy, a primary and a secondary server. That means if one nameserver goes down, the other can still answer DNS queries.

All nameservers store identical DNS records for a Domain Name. Updating the DNS records for the primary nameserver will trigger an update in the secondary server.

## What are DNS records?

DNS records are instructions for a Domain Name managed by an authoritative nameserver. A DNS provider will allow you to access and edit these records.

- **DNS record** — A record of important information, which might include a domain's IP address, email routing, owner validation, and more.
- **DNS Provider** — A service that assigns IP addresses to domain names and manages DNS records.

Each DNS record has a Time-To-Live (TTL) value, which indicates how often a DNS server should refresh a record to check for updates from the domain owner.

![A screenshot of the DNS tab on the Domain page shows a list of DNS records including A, CNAME, MX, and TXT records.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Domain-DNS-Tab.webp)

CloudCannon DNS supports the following DNS record types: *A*, *AAAA*, *CNAME*, *MX*, *SPF*, *SRV*, and *TXT*.

- **Address (A) Record** — Specifies the IP address for a given Domain Name in IPv4 format (e.g., 93.184.216.34). This record allows you to access a website if you only know the Domain Name or block mail from a specific source.
- **Address (AAAA) Record** — Specifies the IP address for a given Domain Name in IPv6 format (e.g., 3001:0db7:3c5d:0024:0000:0000:1a2f:3c1b). IPv6 is a newer format of IPv4, offering a longer string and more string combinations to increase the number of unique IP addresses available.
- **Canonical Name (CNAME) Record** — Specifies the canonical Domain Name for an alias domain. Often used for subdomains (e.g., users looking for the IP address for www.example.com will be redirected to example.com) or for hosting platforms.
- **Email Exchange (MX) Record** — Specifies where emails for a given Domain Name should be routed.
- **Sender Policy Framework (SPF) Record** — Specifies which servers are authorized to send emails from a given Domain Name.
- **Service (SRV) Record** — Specifies the host and port number for services the need to connect to a specific port.
- **Text (TXT) Record** — Can store any text string but is commonly used to verify ownership of a Domain Name.

Other record types include:

- **Nameserver (NS) Record** — Specifies which nameserver is authoritative for a given Domain Name.

Instead of configuring NS records in CloudCannon, you update your nameservers with your Domain Registrar. For more information, please read our documentation on [configuring CloudCannon DNS](/documentation/developer-articles/configure-cloudcannon-dns/).

## Which DNS provider is right for your Site?

On CloudCannon, any [Custom Domain](/documentation/developer-articles/what-is-a-custom-domain/)  added to your [Organization](/documentation/user-articles/what-is-an-organization/) can use [CloudCannon DNS](/documentation/developer-articles/configure-cloudcannon-dns/) or an [external DNS](/documentation/developer-articles/configure-external-dns/).

### CloudCannon DNS

CloudCannon offers free DNS services by default through Cloudflare.

- **CloudCannon DNS** — Manage your DNS records through CloudCannon (recommended).

CloudCannon DNS may also be right for you if:

- You want to use an [auto-generated SSL certificate](/documentation/developer-articles/add-an-auto-generated-ssl-certificate/).
- You want to manage all your domain settings in the same place you edit your content.

For more information, please read our documentation on [configuring CloudCannon DNS](/documentation/developer-articles/configure-cloudcannon-dns/).

### External DNS

You can also use an external DNS provider for your Sites on CloudCannon.

- **External DNS** — Manage your DNS records through a trusted third-party service (e.g., Cloudflare).

An external DNS provider may be right for you if:

- You have existing DNS infrastructure with a trusted third-party provider.
- You want to use a [custom SSL certificate](/documentation/developer-articles/add-a-custom-ssl-certificate/).

If you select an external DNS provider for your Site hosted on CloudCannon, there are a few limitations you should consider.

- If you are using an [auto-generated SSL certificate](/documentation/developer-articles/add-an-auto-generated-ssl-certificate/), some additional configuration is required. For more information, please read our documentation on [adding TXT DNS records](/documentation/developer-articles/add-an-auto-generated-ssl-certificate/#add-txt-dns-records).
- If you use Cloudflare as your DNS provider and have the Cloudflare Proxy feature enabled, some additional configuration is required. For more information, please read our documentation on [configuring Cloudflare Proxy](/documentation/developer-articles/configure-external-dns/#configure-cloudflare-proxy).

For more information, please read our documentation on [configuring external DNS](/documentation/developer-articles/configure-external-dns/).


---

---
title: What is Headless Mode?
description: Learn what Headless Mode is and why you might enable it for your Site on CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/what-is-headless-mode/
content_type: developer article
last_modified: 2026-02-10
---

> Headless Mode is only available for Sites using Unified Configuration. For more information, please read our [Unified Configuration migration guide](/documentation/developer-guides/unified-configuration-migration-guide/).

Building your Site in CloudCannon is optional. If you do not want to build your Site, you can [enable Headless Mode](/documentation/developer-articles/enable-headless-mode/). Headless Mode disables building and hosting for your Site on CloudCannon.

A "headless" website is one where the frontend and backend are separated. In Headless Mode, CloudCannon still manages your content, but it doesn't affect any frontend activities, like building or hosting.

Headless Mode is useful if you want to host a website with server-side rendering (SSR), or a fully hosted API, using a third-party service while still using CloudCannon as your primary **CMS**.

Headless Mode may not be right for you if:

- You want to use the [Visual Editor](/documentation/user-articles/what-is-the-visual-editor/) to edit your content in CloudCannon.
- You want to see preview screenshots of your Site on file [cards](/documentation/developer-articles/configure-your-card-previews/) in the [Collection](/documentation/user-articles/what-is-a-collection/) browsers.
- You want to use a CloudCannon [Testing Domain](/documentation/user-articles/what-is-a-testing-domain/).


---

---
title: What is routing?
description: Learn about routing and how you can implement it for your website.
url: https://cloudcannon.com/documentation/developer-articles/what-is-routing/
content_type: developer article
last_modified: 2026-04-11
---

In web development, routing is the process that determines what content a visitor to your Site should see when they enter a URL in their Internet browser or change pages by clicking an internal link on your Site.

By default, when visitors enter a URL or click on a link, they will see the content for the file with a file name that matches the URL. In most cases, default routing will deliver the correct content to your user. However, you should employ custom routing in the following situations:

- You have updated the name of a page.
- You have updated your site architecture, specifically the subdirectories in your URL.
- You have deleted a page from your website.
- You want visitors to see a helpful, branded 404 page when they enter an incorrect URL.

On CloudCannon, you can:

- Use [custom routing](/documentation/developer-articles/configure-custom-routing/) to redirect old page URLs or configure extra headers on a route.
- Send visitors to a [404 page](/documentation/developer-articles/configure-a-404-page/) when they enter an incorrect URL.
- Remove the [URL extension](/documentation/developer-articles/configure-extensionless-urls/) to create a cleaner-looking URL.
- Use [geolocation](/documentation/developer-articles/configure-geolocation/) to detect which country your visitors are from.

For help setting up routing on your Site, please contact our friendly [support team](/support/).


---

---
title: What is Site mounting?
description: Learn how to add Site Mounting with CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/what-is-site-mounting/
content_type: developer article
last_modified: 2026-04-11
---

Site Mounting makes one site dependent on one or more other CloudCannon sites. Files from a remote site will be accessible to the local site at build time, and any updates to the remote site will trigger a build of the local site.

- **Local Site** — The recipient of files from another site.
- **Remote Site(s)** — The donor site.
- **Remote artifact** — This determines which files are mounted and which events trigger new builds. You can set this to either *Source files* or *Build output* (available on [Team and Enterprise plans](/pricing/)).
- **Remote path** — This determines the path/folder mounted to this site from the remote site. Leave this blank to mount the entire site's files.
- **Local path** — This determines where CloudCannon will mount the remote files. This cannot be left blank.

You can have several remote sites mounted to one local site at a time. You can also mount one site to several other sites to create a content lake or common component hub. The number of connections per site and total number of mounted sites per Organization depends on your CloudCannon Plan.

- **Standard** — 4 site mounts.
- **Team** — 50 site mounts and 5 mounts per site.
- **Enterprise** — 500 site mounts and unlimited mounts per site.

> CloudCannon will prompt you to reduce your total site mountings before you can alter your pricing plan to one with a lower mounting limit.

Site Mounting is an alternative to relying on Git submodules, build hooks, or custom APIs to manage your site dependencies. You can use Site Mounting to:

- Share components across multiple sites from a single source.
- Aggregate content from multiple sites into a single content lake.
- Set up a pre-generated headless API without GraphQL.

If you are on our [Team or Enterprise plan](/pricing/), Site Mounting also unlocks the ability to mount the build output of a site in addition to its source files.


---

---
title: What is SSO/SAML?
description: Learn about Single Sign-On and Security Assertion Markup Languages, and how they can benefit your enterprise.
url: https://cloudcannon.com/documentation/developer-articles/what-is-sso-saml/
content_type: developer article
last_modified: 2026-04-11
---

> **This feature is available on our [Enterprise plan](/pricing/).**
> 
> Want to chat about whether this feature is right for you? Our support team is always [happy to hear from you](mailto:success@cloudcannon.com?subject=A%20question%20about%20SSO%2FSAML).

CloudCannon supports Single Sign-On (SSO) using a Security Assertion Markup Language (SAML) for customers on our [Enterprise plan](/pricing/). SSO/SAML provides a way to authenticate your team through an external application and communicate that authentication to CloudCannon.

- **User** — The team member who wants to access CloudCannon.
- **Identity Provider** — The cloud software that will authenticate the user’s identity. An Identity Provider could be an internal software or an external service, like Google. A member of your Organization already has a login for this software.
- **Service Provider** — The cloud application a user wants to log in to (i.e., CloudCannon).

With SSO/SAML, rather than logging in to CloudCannon directly, CloudCannon will authenticate the user’s identity using their Identity Provider software. While the user is logged in to their Identity Provider, they do not need to enter their CloudCannon password to log in. Instead, they can click a button, and CloudCannon will confirm their identity with their Identity Provider.

When you have a large team, managing their access can be tricky. SSO can benefit your enterprise in several ways. With SSO, you can:

- Reduce the number of password resets due to forgotten passwords.
- Improve the user experience with seamless access to many applications.
- Revoke access in a single location and know you have removed access to multiple applications.

SSO is also required for some security and compliance policies, as it reduces password-related vulnerabilities and puts authentication in the hands of a single Identity Provider rather than many applications.


---

---
title: What is the CloudCannon Configuration File?
description: Learn about the CloudCannon Configuration File.
url: https://cloudcannon.com/documentation/developer-articles/what-is-the-cloudcannon-configuration-file/
content_type: developer article
last_modified: 2026-03-29
---

> 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](https://non-unified.cloudcannon.com/documentation/developer-articles/create-a-global-configuration-file/).

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](/documentation/user-articles/what-is-a-team-member/).

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](/documentation/developer-articles/create-your-cloudcannon-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.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Dashboard-Create-Config-File-Task.webp)

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](/documentation/developer-articles/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](/documentation/developer-articles/what-is-configuration-mode/) in general or the [Source Editor](/documentation/user-articles/what-is-the-data-editor/).

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

File: `cloudcannon.config.yml`

```YAML

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

```

## Splitting your configuration

Rather than have a single *CloudCannon Configuration File*, you can split your configuration across multiple files. With a split *Configuration File*, you can organize your configuration more effectively, especially for larger sites or when working with shared configurations.

For more information, please read our documentation on [why splitting your Configuration File](/documentation/developer-articles/why-split-your-configuration-file/) might be right for your *Site*.

## 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](/documentation/developer-articles/using-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](/documentation/user-articles/what-is-a-collection/) are configured relative to your *Source Folder*. This is useful if you have multiple websites nested in a single repository.


---

---
title: What is the Site Dashboard README?
description: Learn about the Site Dashboard README and how it helps your team access important project information in CloudCannon.
url: https://cloudcannon.com/documentation/developer-articles/what-is-the-site-dashboard-readme/
content_type: developer article
last_modified: 2026-03-29
---

You can add more context and instructions to your *Site* by adding a the `.cloudcannon/README.md` **Markdown** file to your *Site*. When CloudCannon detects this file, it will render the contents on the *Summary* tab of your **Site Dashboard**.

![A screenshot of the Site Dashboard shows custom Markdown content at the top of the Summary tab.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Dashboard-README-Config-Off.webp)

## Why add a README to your *Site Dashboard*?

The *Summary* tab of your *Site Dashboard* is a hub for information about your *Site*. It is the first page you see when you open your *Site*, and summarizes useful information such as *Recent Activity*, *Syncs*, *Builds*, and *Usage*. This make it an excellent page to add more information for your *Site* users.

A *Site Dashboard* README gives your team a single place to find essential project information without leaving CloudCannon. Instead of relying on external documents, emails, or team knowledge, you can put everything your team needs right where they work. You can use it to provide onboarding notes, project documentation, editing guidelines, or links to external resources for your team members. This is especially valuable for onboarding. When a new team member opens a *Site* for the first time, the README is the first thing they see on the *Summary* tab, giving them immediate context about the project and how to contribute.

You can include any information that helps your team work more effectively, such as:

- Onboarding notes for new team members
- Editing guidelines and content conventions (e.g., required front matter fields, recommended image dimensions)
- Links to external resources like design systems, brand guides, or project management boards
- Build or deployment notes relevant to the *Site*
- Contact information for the project owner or technical lead

Because the README is stored in your Git repository alongside your *Site* files, you can easily maintain versions of the file that are up to date with the rest of your project.

For instructions on how to create and edit your *Site* README, please read [add a Site Dashboard README](/documentation/developer-articles/add-a-site-dashboard-readme/).

## Supported formatting

The *Site Dashboard* README supports a wide range of Markdown formatting:

- Headings
- Bold, italic, strikethrough, subscript, superscript, and underline
- Links
- Blockquotes
- Bulleted and numbered lists
- Inline code
- Fenced code blocks with syntax highlighting
- Horizontal rules
- Tables

### Headings

CloudCannon automatically adjusts heading levels in your README to fit within the *Site Dashboard* layout. Your heading hierarchy is preserved, but levels are shifted so they appear as sub-headings within the dashboard. You can write headings naturally starting from `#` without worrying about the dashboard context.

For example, if your README contains `#`, `##`, and `###` headings, CloudCannon shifts them to render as smaller headings that sit beneath the dashboard page headings.

### Code blocks

Fenced code blocks in your README render with syntax highlighting using CloudCannon's styled code block component. Specify a language after the opening backticks for language-specific highlighting.

For example, the following Markdown in your README:

File: `.cloudcannon/README.md`

```Markdown
## Heading

Description:

&#96;&#96;&#96;yaml
title: My Site
description: A great site
&#96;&#96;&#96;
```

This renders on the *Site Dashboard* with a styled code block that includes syntax highlighting, line numbers, and a copy button.

### CloudCannon links

You can add links to CloudCannon pages using the [CloudCannon link protocol](/documentation/developer-articles/cloudcannon-protocol/). This allows you to link directly to a page on CloudCannon, such as a file or *Collection* on your *Site*, or to relevant pages outside your *Site*, such as the *Custom Domain* or *Project Browser*.

For example:

File: `.cloudcannon/README.md`

```Markdown
## Quick links

* [Edit the home page](cloudcannon:collections/pages/index.md)
* [View all blog posts](cloudcannon:collections/posts)
* [Site Settings](cloudcannon:settings)
```


---

---
title: What is Visual Editing?
description: Learn about Visual Editing in CloudCannon, including how you can edit inline on a preview of you live website.
url: https://cloudcannon.com/documentation/developer-articles/what-is-visual-editing/
content_type: developer article
last_modified: 2026-03-29
---

Visual editing is a user-friendly way of updating your website files, allowing you to change your text, images, and arrays on a preview of your output webpage. The benefits of visual editing include providing a more intuitive experience (you can navigate around your website preview using links/buttons, as you would on the live version) and helping you make editing decisions in context with surrounding page elements.

In CloudCannon, you can use the [Visual Editor](/documentation/user-articles/what-is-the-visual-editor/) to visually edit any file that outputs to an HTML webpage at [build time](/documentation/developer-articles/what-is-a-site-build/).

## Generating the preview of your webpage

When you open a file, the Visual Editor displays a preview of your webpage, along with a sidebar on the left. But, where does CloudCannon get the preview?

CloudCannon generates a preview of all your webpages whenever you build your *Site*, allowing you to see the most up-to-date version of your website every time you use the Visual Editor.

A "build" is when CloudCannon converts all your *Site* files into a single, functional website. Building on CloudCannon is optional, but is required for specific features, such as the Visual Editor, preview screenshots for output files in your *Collection Browser*, and the Testing Domain and Custom Domain.

CloudCannon uses a CI/CD (Continuous Integration/Continuous Delivery) system. Every time you trigger a build of your Site, CloudCannon will:

1. Download your files onto our server.
2. Run your selected install commands (e.g., `npm install`, `bundle install`).
3. Run your selected build commands (e.g., `npm run build`).
4. Index your output files.
5. Upload your output files to CloudCannon to generate previews in the Visual Editor, Testing Domain, and *Collection Browser* screenshots, and deliver them to your live Custom Domain (if you are hosting with CloudCannon).

For more information about Site builds, please read our documentation on [builds](/documentation/developer-articles/what-is-a-site-build/) in general, [configuring your first site build](/documentation/developer-articles/configure-your-first-build/), or consider following our [Set up Visual Editing](/documentation/developer-guides/set-up-visual-editing/) guide.

## Editable regions, data panels, and the sidebar

There are several ways to edit your files in the Visual Editor: inline using editable regions on the preview of your webpage, with data panels for data that is not visible on the webpage, or using Inputs in the sidebar.

You can define which content you want your team to be able to edit inline by adding *Editable Regions* to your files. In the Visual Editor, *Editable Regions* are signified by a yellow box around a piece of content. If you have several *Editable Regions* near each other on your page, CloudCannon will show you the boundary of your region by turning the border green when you click or hover it.

Clicking into an *Editable Region* will have a different result depending on the type of content it contains. CloudCannon will show a WYSIWYG toolbar for rich text, open a data panel for images, and provide tools for editing array items.

[Video: The Visual Editor with editable regions](https://player.vimeo.com/progressive_redirect/playback/1124969057/rendition/1080p/file.mp4?loc=external&signature=18a05ed71665768fa94851c72a31cf574e4079284b8ce0579885d8f3b47c4a8d)

Data panels enable you to edit data that is not visible on your page, and therefore cannot be edited in-line. A good example of this is the path, alt text, or title of an image. You can move these data panels around your screen to ensure they don't cover the content you need.

![A screenshot of the Visual Editor shows a yellow Editable Region box around the image and the Edit Image Data Panel.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Visual-Editor-Frontmatter-Image-Editable-Region.webp)

Finally, the sidebar of the Visual Editor provides [Inputs](/documentation/user-articles/what-are-inputs/) for editing any structured data keys related to your webpage. You can open and close the sidebar as you need, giving you the option to see more of your webpage preview.

When you change the value on an Input in the sidebar, the preview of your webpage in the Visual Editor will immediately update to match the new value. The same will happen if you update the content of an *Editable Region* connected to a structured data key in your sidebar.

If you have not configured your Inputs, CloudCannon will attempt to determine the correct editing interface for your data using the Input value and key name.

![A screenshot of the Visual Editor shows a yellow Editable Region box around the Call to Action component on the blog page.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Visual-Editor-Component-Editable-Region.webp)


---

---
title: Why split your Configuration File?
description: Learn about splitting your CloudCannon configuration across several files, including why split configuration might work for you.
url: https://cloudcannon.com/documentation/developer-articles/why-split-your-configuration-file/
content_type: developer article
last_modified: 2026-02-10
---

Rather than have a single [CloudCannon Configuration File](/documentation/developer-articles/what-is-the-cloudcannon-configuration-file/), you can split your configuration across multiple files. With a split *Configuration File*, you can organize your configuration more effectively, especially for larger sites or when working with shared configurations.

You can split the following configuration into dedicated *Configuration Files*:

- [Collections](/documentation/user-articles/what-is-a-collection/) (`_collection_config`)
- [Schemas](/documentation/developer-articles/what-is-a-schema/) (`collections_config.*.schemas`)
- [Inputs](/documentation/user-articles/what-are-inputs/) (`_inputs`
- [Structures](/documentation/developer-articles/what-is-a-structure/) and Structure values (`_structures`, `_structures.*.values.value`)
- [Snippets](/documentation/developer-articles/what-is-a-snippet/) (`_snippets`, `_snippets_imports`)
- [Rich Text](/documentation/developer-articles/what-are-rich-text-editors/) (`_editables`)

There are several reasons why splitting your CloudCannon configuration across multiple files might be right for your *Site*:

- Splitting your configuration across multiple files allows you to keep related configurations in dedicated files (e.g., Input configuration in one file and Schema configuration in another). When updating your *Site,* you can navigate directly to the file you need, without going through a single long *Configuration File*.
- Collaborating with your team is easier with split *Configuration Files*, as you can work on different parts of your *Site* configuration simultaneously.
- You can use [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/) to only allow your team members to edit specific *Site* configuration.
- Split *Configuration Files* also allow you to reduce configuration redundancy. For example, rather than defining a common Input under several *Collections*, you can reference a single *Inputs* *Configuration File* from each *Collection*.

For more information, please read our documentation on [best practices for splitting your configuration](/documentation/developer-articles/best-practice-for-splitting-your-configuration-file/), [defining the same key in multiple Configuration Files](/documentation/developer-articles/defining-the-same-key-in-multiple-configuration-files/), and [split your Configuration File](/documentation/developer-articles/split-your-configuration-file/), and our [Configuration File](/documentation/developer-reference/configuration-file/) reference documentation.

## How does splitting your *Configuration File* work?

When you split your *Site* configuration across multiple *Configuration Files*, CloudCannon still requires one main *Configuration File* (i.e., `cloudcannon.config.yml`). Your main *Configuration File* will point to other *Configuration Files* on your *Site* using `*_from_glob` keys.

File: `cloudcannon.config.yml`

```YAML

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

```

Each *Configuration File* can reference any other *Configuration File* (as long as they all ultimately connect back to your main *Configuration File*), allowing you to organize your content to the level you require.

File: `/.cloudcannon/collections/posts.cloudcannon.collections.yml`

```YAML

path: content/posts
icon: event
schemas_from_glob:
  - '/.cloudcannon/schemas/*.cloudcannon.schemas.yml'
  - '!/.cloudcannon/schemas/pages.cloudcannon.schemas.yml'
_inputs_from_glob:
  - '/.cloudcannon/inputs/seo.cloudcannon.inputs.yml'
  - '/.cloudcannon/inputs/blog-details.cloudcannon.inputs.yml'
_inputs:
  authors:
    type: multiselect
    options:
      values: collections.authors

```

Whenever you load your *Site* or update a *Configuration File*, CloudCannon will merge your configuration and apply it to your *Site*.

## Limitations

There are a few reasons that split *Configuration Files* may not be right for your *Site.*

1. Currently, you can only split your *Configuration File* for *Sites* using [Unified Configuration](/documentation/developer-guides/unified-configuration-migration-guide/).
2. You cannot use `*_from_glob` keys in the front matter of content files.
3. While you can split out several sections of your *Configuration File*, the equivalent `*_from_glob` key for `_select_data` is intentionally not supported. Please use `data_config` instead.

If you have any questions about configuring your *Site* on CloudCannon, don't hesitate to contact our friendly [support team](/support/).


---

---
title: UI adjustments
description: This release added minor UI adjustments for icons and margins in the app and the Open Documentation link to the App Sidebar.
url: https://cloudcannon.com/documentation/changelog/2026/04/16/ui-adjustments/
content_type: changelog
last_modified: 2026-04-16
---

This release added minor UI adjustments for icons and margins in the app and the *Open Documentation* link to the *App Sidebar*.

It also addressed several issues, including those affecting *Repository* lists in Bitbucket *Sites* and billing warnings when accepting a *Site Transfer*.

## Features & Improvements

- Added minor UI adjustments to icon and margin sizes in the app.
- Added the *Open Documentation* link to the *App Sidebar*, which opens https://cloudcannon.com/documentation/ in a new tab.

## Fixes

- Fixed an issue where Bitbucket *Sites* could not load the list of available *Repositories*.
- Fixed an issue where, in some cases, CloudCannon would incorrectly warn you about an increase in billing when accepting a *Site Transfer*.
- Updated dependencies to patch security vulnerabilities.


---

---
title: General fixes
description: This release added better messaging for automatic emails.
url: https://cloudcannon.com/documentation/changelog/2026/04/10/general-fixes/
content_type: changelog
last_modified: 2026-04-10
---

This release added better messaging for automatic emails.

It also addressed several issues, including those affecting the *Repository* select field, links in the *Content Editor*, and *Data Panels*.

## Features & Improvements

- Better messaging for the automatic Build Failure and Sync Failure emails.

## Fixes

- Fixed an issue where the *Repository* select field did not update after you changed the *Git Provider* in a *Project*.
- Fixed an issue where, in some cases, you could not edit links in the *Content Editor*.
- Fixed an issue where, in some cases, a *Data Panel* could open underneath its parent *Data Panel*.


---

---
title: General fixes
description: This release addressed several issues, including those affecting SSL Settings, Azure DAMs, and the Publishing page.
url: https://cloudcannon.com/documentation/changelog/2026/04/09/general-fixes/
content_type: changelog
last_modified: 2026-04-09
---

This release addressed several issues, including those affecting SSL Settings, Azure DAMs, and the *Publishing* page.

## Fixes

- Fixed an issue where, in some cases, CloudCannon did not display the correct *SSL Settings* modal.
- Fixed an issue where, in some cases, CloudCannon did not display the correct error message in the *Configure SSL* modal when SSL setup failed.
- Fixed an issue where uploads to Azure DAMs failed when your Azure account did not have `x-ms-useragent` in the *AllowedHeaders*.
- Fixed various rendering issues on the *Publishing* page.


---

---
title: Introduction
description: Learn how to edit and update your website using CloudCannon.
url: https://cloudcannon.com/documentation/user-guides/editing-in-cloudcannon/
content_type: user guide
last_modified: 2026-04-16
---

Welcome to the Editing in CloudCannon guide!

This guide is perfect for anyone new to CloudCannon who wants to learn how to edit and update their website content. We'll walk you through everything step by step, assuming no prior knowledge.

CloudCannon is a tool that makes it easy to edit your website content, even if you've never worked with websites before. CloudCannon is like a word processor for your website: you can update text, add images, create new pages, and make changes without needing to know how to code.

In this guide, we'll cover how to:

- Find your files using the *Collection Browser* and the *File Browser*
- Use CloudCannon's *Editing Interfaces* to update your content
- Use file actions to add, delete, and organize your content files
- Work together with your team members on the same files
- Save your changes and see them live on your website
- Publish your changes if your *Site* uses a branching workflow

Before we begin, this guide assumes that you already have a *Site* set up in CloudCannon and that you have permission to edit that *Site* (i.e., you are a member of the *Editors* *Permission Group* or higher). If you haven't created a *Site* yet or don't know what CloudCannon permissions you have, check out our [Getting Started with CloudCannon](/documentation/developer-guides/getting-started-with-cloudcannon/) guide, or ask your developer to get started.


---

---
title: Saving your changes
description: Learn how to review and save your changes, and see them live on your website.
url: https://cloudcannon.com/documentation/user-guides/editing-in-cloudcannon/saving-your-changes/
content_type: user guide
last_modified: 2026-04-16
---

Once you are happy with the changes you have made to your files, you can save them so they appear on on the Internet. Saving your changes in CloudCannon is straightforward, but it's helpful to understand how the process works.

## The Save button

As you make changes, you'll notice a red notification appear on the *Save* button in the top right of your *Editing Interface* and *Site Header*. The *Save* button notification shows you how many files have unsaved changes.

![A screenshot of the Save Button in the Site Header shows a notification of unsaved changes.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Save-Button-Unsaved-Changes-Notification.webp)

Don't worry about saving after every single change. CloudCannon remembers all your edits, so you can make multiple changes across multiple files and save them all at once when you're ready.

## Why save your changes?

When you edit files in CloudCannon, your changes are stored temporarily until you save them. This means you can:

- Make multiple changes across different files
- Take breaks without losing your work, including closing the CloudCannon tab in your Internet browser
- Review all your changes before saving
- Work with your team on the same editing session

However, your changes won't appear on your live website until you save them. Saving your changes does two important things:

1. It creates a permanent record of your changes in your website's files (your developer can undo these changes, if necessary)
2. It triggers CloudCannon to rebuild your website, making your changes visible on your *Testing Domain* (your free preview URL) and any *Custom Domain* connected to your site

> It's important to save your changes regularly, as unsaved changes can prevent other updates to your site. We recommend saving after every editing session.

## How to save your changes

Once you are finished making changes to your *Site* content, click the *Save* button in the top right of your *Editing Interface* or *Site Header*. A red notification on the *Save* button will show you how many files have unsaved changes.

CloudCannon will open the *Review changes* modal, which shows you all the files with unsaved changes, organized into two sections: *My changes* and *Other changes*. These sections help you identify which files you contributed to during the editing sessions, and which files only have unsaved changes from other team members.

![A screenshot of the Review changes modal shows all files with unsaved changes, organized into sections.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Save-Changes-Modal-Multiple-Contributors.webp)

Review the list of files. Each file is represented by a *File Card* with the file name, *Collection*, which team members contributed to changes (shown as avatars), when the file was last updated, and a badge showing the type of change (*New*, *Edited*, or *Deleted*).

Select the files you want to save using the checkboxes in the top left of each *File Card*. By default, any files you contributed to will be selected. You can select or deselect individual files, or use the checkboxes under each section heading to select all files in that section.

Sometimes, your file might require you to fill in some information before you can save them (for example, if you did not add a file name). Also, if your developer has added validation rules to an Input in a file, you will need to make sure those Inputs have valid values before you can save. An example of Input validation might be that a Date field requires you to enter a publishing date on a blog, or a list of relevant links can only have a maximum of three items.

![A screenshot of the Save Changes modal shows a file with an input validation issue (it has no title).](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Save-Changes-Modal-Input-Validation.webp)

Some *Sites* have *Commit Messages* configured. A *Commit Message* is a note that CloudCannon will attach to the record of changes to your *Site*. You should use it to describe what you have changed, and why, for your team (or your future self). For example, "Updated the About page with new team member information" or "Added three new blog posts about new product features."

![A screenshot of the Save Changes modal shows a Commit Message with fields for ticket number and subject.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Save-Changes-Modal-Commit-Message.webp)

Once you're happy with the files you have selected, have filled in all the fields required by your developer, and added any *Commit Messages*, click the *Save selected* button.

CloudCannon will update your *Site* using your changes, remove the *New*, *Edited*, and *Deleted* badges from your *File Cards*, add a permanent record of your changes in your website's files, and make your changes live on your *Testing Domain* (your free preview URL) and any *Custom Domain* connected to your site.

The save process usually takes just a few moments, but it may take longer for larger sites or when many files have changed. You can then continue editing while your *Site* is saving, or take a break knowing your changes are safe.

## What if you want to undo a saved change?

If you accidentally save a change you didn't mean to, or change your mind, you can always undo that change by re-editing your files and saving again. However, if you need to return to a version of your files that was several changes ago, or undo a large change that would be difficult to do manually, talk to your developer. Because CloudCannon has a permanent record of all your changes, your developer will be able to help you restore a previous version.

## View your changes live on the Internet

Once you save your changes, CloudCannon will rebuild your *Site* and update the content live on the Internet. You can see your live website using your *Testing Domain* or *Custom Domain*.

A *Testing Domain* is a free preview website that CloudCannon gives to every *Site*. Each *Testing Domain* uses a randomly generated adjective and noun separated by a hyphen (e.g., grey-grouse.cloudvent.net or brave-submarine.cloudvent.net). A *Custom Domain* is a custom website URL chosen by your developer (e.g., cloudcannon.com). Your *Custom Domain* may also be the URL your visitors or customers use to see your content on the Internet.

You can open your *Testing Domain* or *Custom Domain* in a new tab by clicking the URL on the right of your *Site Header*. CloudCannon will open your live website in a new tab.

![A screenshot of the Testing Domain in the Site Header.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Header-Tools-Post-Build.webp)

If your developer has set up a publishing workflow for your *Site*, the *Testing Domain* allows you to see your changes live on the Internet without affecting your public website. We'll cover what you need to know about publishing workflows in the next step of this guide.


---

---
title: Using file actions
description: Learn how to add, delete, duplicate, and rename files on your website.
url: https://cloudcannon.com/documentation/user-guides/editing-in-cloudcannon/using-file-actions/
content_type: user guide
last_modified: 2026-04-16
---

Sometimes you will need to do more than edit the content of your files. You might want to add a new file, delete a file you no longer need, or make a copy of an existing file. You can use the tools in the *Context Menu* to perform these file actions. You can find the *Context Menu* in the top right of a *File Card* in your *Collection Browser*, or in the top right of the *Editing Interface Header*.

## Adding new files

You might want to add a new file when you're creating a new blog post, adding a new page to your website, or uploading an image or document. There are several ways to add new files to your website in CloudCannon.

### Add a file to a Collection

The easiest way to add a new file is from the *Collection Browser*.

Navigate to the *Collection* to which you want to add the file and click the *+ Add* button in the top right of the *Collection Browser*. CloudCannon will open a dropdown menu with the options to add files or *Create a new folder*.

![A screenshot of the Collection Browser shows the Add dropdown with template options.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-Controls-Add-Menu-Dropdown.webp)

When you create a new file in the *Collection Browser*, CloudCannon will either copy the format of an existing file in your *Collection* or use a predefined template called a *Schema*. The default file format will often share the name of the *Collection* (e.g., the Blog *Collection* will have the *+ Add Blog* option), but each *Schema* will have a different name. If you would like to add, remove, or edit your *Schemas*, please speak with your developer.

Clicking on an *+ Add* option from this dropdown will create a new file, which CloudCannon will immediately open in an *Editing Interface*, ready for you to edit your content.

### Duplicate an existing file

If you want to create a new file that's similar to an existing one, you can duplicate it. Navigate to the file you want to duplicate using the *Collection Browser* or *File Browser* and open the *Context Menu* by clicking on the six-dot icon in the top right of the *File Card*. The *Duplicate* file action will be an option in the *Context Menu*.

![A screenshot of the Collection Browser shows the Context Menu is open for a file.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-Edited-File-Context-Menu.webp)

You can also find the *Duplicate* option in any *Editing Interface* by clicking on the three-dot icon in the *Editing Interface Header* and opening the *Context Menu*.

![A screenshot of the Content Editor shows the Context Menu is open for a file.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Edited-File-Context-Menu.webp)

When you select the *Duplicate* option from the *Context Menu*, CloudCannon will create a copy of the file with "-copy" added to the filename and open it in an *Editing Interface*. We recommend changing the name of the file before saving it to your *Site*.

### Upload a file

If you have files on your computer that you want to upload to your website, you can upload them using CloudCannon.

Navigate to the location to which you want to upload the file using the *File Browser* and click the *+ Add* button in the top right. Select the *Upload files* or *Upload a folder* option from the dropdown menu.

![A screenshot of the File Browser shows the Add dropdown with template options.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-File-Browser-Controls-Add-Menu-Dropdown.webp)

Next, select the file or folder from your computer. CloudCannon will ask you to review the files in a confirmation modal before you upload them to your *Site*.

CloudCannon will upload your files to the location you selected. You can also drag and drop files directly into the *File Browser* to upload them.

## Deleting files

You might want to delete a file when you no longer need it, such as removing an old blog post or an outdated page. When you delete a file in CloudCannon, it doesn't happen immediately. Instead, CloudCannon marks the file for deletion, which gives you a chance to change your mind before you save the changes to your *Site*. We'll cover saving your changes more [later in this guide](/documentation/user-guides/editing-in-cloudcannon/saving-your-changes).

### Marking a file for deletion

To delete a file, navigate to the file you want to delete using the *Collection Browser* or *File Browser* and open the *Context Menu* by clicking on the six-dot icon in the top right of the *File Card*.

Select the *Delete* option from the *Context Menu*. CloudCannon will mark the file for deletion the next time you save your changes.

![A screenshot of the Collection Browser shows the Context Menu is open for a file.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-Edited-File-Context-Menu.webp)

You can also mark a file for deletion from any *Editing Interface*. Open the *Context Menu* by clicking the three dots icon in the top right of the *Editing Interface Header*, then select the *Delete* option from the dropdown menu.

### Restoring a deleted file

If you have marked a file for deletion, you can restore it at any time before you save your changes.

Navigate to the file with the *Deleted* badge and open the *Context Menu* by clicking the six-dot icon in the top right of the *File Card*. Select the *Restore file* option from the *Context Menu*.

![A screenshot of the Collection Browser shows the Context Menu is open for a deleted file.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-Deleted-File-Context-Menu.webp)

You can also restore a file from any *Editing Interface*. Open the *Context Menu* by clicking the three dots icon in the top right of the *Editing Interface Header*, then select the *Restore file* option from the dropdown menu.

You can also click the *Restore file* button in the banner at the bottom of the *Editing Interface*.

![A screenshot of the Content Editor shows the Context Menu is open for a file.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-Deleted-File-Context-Menu.webp)

The *Deleted* badge will be removed, and the file will be restored.

### Files with unsaved changes

If a file has unsaved changes, you will need to discard those changes before you can mark it for deletion. This protects your work from being accidentally lost.

To discard unsaved changes, open the *Context Menu* for the file using the *Collection Browser* or an *Editing Interface*. Select the *Discard unsaved changes*. CloudCannon will ask you to review the action in a confirmation modal before you discard those changes from your *Site*.

![A screenshot of the Collection Browser shows the Context Menu is open for a file.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-Edited-File-Context-Menu.webp)

You can also discard unsaved changes from any *Editing Interface*. Open the *Context Menu* by clicking the three dots icon in the top right of the *Editing Interface Header*, then select the *Discard unsaved changes* option from the dropdown menu.

> Discarding unsaved changes will destroy new files and content.

After discarding the changes, you will be able to delete the file using the option in the *Context Menu*.

## Rename a file

You might want to rename a file to better reflect its content, fix a typo in the filename, or organize your files more effectively.

To rename a file, navigate to the file you want to rename using the *Collection Browser* or *File Browser* and open the *Context Menu* by clicking on the six dot icon in the top right of the *File Card*.

Select the *Rename* option from the *Context Menu*. CloudCannon will open a pop-up window where you can edit the filename.

![A screenshot of the Collection Browser shows the Rename file pop up.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-Rename-File-Popup.webp)

Enter the new filename and click *Confirm* to save your changes. The file will appear in your *Collection Browser* or *File Browser* with both the old and new filenames until you save your changes. The file with the new name will have a *New* badge, and the file with the old name will have a *Deleted* badge.

You can also rename a file from any *Editing Interface*. Open the *Context Menu* by clicking the three dots icon in the top right of the *Editing Interface Header*, then select the *Rename* option from the dropdown menu.

## Understanding file badges

CloudCannon uses badges on *File Cards* to help you keep track of which files have unsaved changes. These badges appear in your *Collection Browser* and *File Browser* to give you a quick visual indicator of each file's status.

![A screenshot of the Collection Browser shows file cards with different badges (New, Edited, Deleted).](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-File-Card-Badges.webp)

The *New* badge appears on files that you've created but haven't saved yet. This includes files you've added to a *Collection* using the *+ Add* button, duplicated, uploaded, and renamed (the file with the new name will show a *New* badge).

The *Edited* badge appears on existing files that you've modified but haven't saved yet. This includes any changes you make to the file's content, whether you're editing text, images, structured data, or any other content.

The *Deleted* badge appears on files that you've marked for deletion but haven't saved yet. This includes files you've deleted using the *Context Menu* and files you've renamed (the file with the old name will show a *Deleted* badge).

We'll cover how to save your changes [later in this guide](/documentation/user-guides/editing-in-cloudcannon/saving-your-changes).

In the next step of this guide, we'll learn about editing sessions and how to collaborate with your team members.


---

---
title: Editing sessions and collaboration
description: Learn how to edit your files in CloudCannon, make changes, and work collaboratively with your team.
url: https://cloudcannon.com/documentation/user-guides/editing-in-cloudcannon/editing-sessions-and-collaboration/
content_type: user guide
last_modified: 2026-04-16
---

Now that you know how to find your files and edit them, let's look at how editing sessions work and how you can collaborate with your team members.

## Editing sessions

In CloudCannon, all your changes happen within an "editing session." An editing session starts when you or someone on your team makes the first change to any file, and it continues until someone clicks the *Save* button.

During each editing session, you can:

- Edit as many files as you want
- Switch between different *Editing Interfaces*
- Have multiple team members contribute to various files
- Take breaks, refresh your page, or close your browser — CloudCannon will remember all your unsaved changes

## Collaborating with team members

CloudCannon makes it easy to collaborate with your team. When someone opens a file, you'll see their avatar appear in the *Editing Interface Header* and over *File Cards* in the *Collection Browser*.

![A screenshot of the Editing Interface shows avatars of team members viewing or editing the file.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Header-Tools-New-Config.webp)

One person can edit a file at a time, while others can view the changes in real time. This means you can see what your teammate is editing as they make changes, which is great for reviewing content together or learning how to use CloudCannon.

If you are viewing a file while someone in your team is editing, CloudCannon will disable any Inputs in the *Editing Interface* while you're viewing. This means you can see the changes your team member is making, but you can't make edits simultaneously.

You will also see a banner at the bottom of the *Editing Interface* showing who is currently editing the file, and a *Switch to editing* button. If you want to take over editing, you can click this button to switch from viewing to editing mode.

Collaboration is especially useful when:

- You want to review changes before they're saved
- Multiple people are working on different files at the same time
- You're learning how to use CloudCannon and want to watch someone else edit

In the next step of this guide, we'll cover how to save your changes and see them live on your website.


---

---
title: Using CloudCannon's Editing Interfaces
description: "Learn about CloudCannon's Editing Interfaces: the Visual Editor, Content Editor, Data Editor, and Source Editor."
url: https://cloudcannon.com/documentation/user-guides/editing-in-cloudcannon/using-cloudcannons-editing-interfaces/
content_type: user guide
last_modified: 2026-04-16
---

CloudCannon provides four different *Editing Interfaces*, each designed for editing different types of content. Understanding these interfaces will help you choose the best one for what you're trying to do.

When you click on a file in a *Collection Browser* or the *File Browser*, CloudCannon will open that file in one of CloudCannon's *Editing Interfaces*. Which *Editing Interface* CloudCannon will open by default depends on your file type and how your *Site* is configured.

![A screenshot of a blog file open in the Content Editor.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor.webp)

## The *Editing Interface Header*

At the top of every *Editing Interface*, you'll find the *Editing Interface Header*, which provides helpful information and tools.

![A screenshot of the Editing Interface Header shows tools including Return to Site, File details, Update status, Avatars, Interface buttons, Context Menu, and Save button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Editing-Interface-Header.webp)

From left to right, this includes:

- The *Return to Site* button — Returns you to the *Collection Browser* or *File Browser* where you opened the file.
- Your *File details* — The name and Output URL (if applicable) of the file you are editing.
- The *Update status* indicator — This shows you when CloudCannon last recorded an update to your file.
- The *Avatars* List — This displays the avatars of any team members who have this file open. One avatar is highlighted to show who is currently editing the file.
- The *Interface* buttons — These allow you to switch between CloudCannon's four *Editing Interfaces*: the *Visual Editor*, *Content Editor*, *Data Editor*, and *Source Editor*. You'll see between two and four options depending on your file type and *Site* configuration.
- The *Context Menu* — Clicking on the three dots icon will show you several file actions like duplicating, renaming, deleting, and more.
- The *Save* button — This opens the *Save changes* modal, allowing you to review all your unsaved changes before saving them to your website.

On smaller screen sizes, some of these tools will collapse into the *Context Menu* to save space.

> **The *Configuration Mode* switch**
> 
> ![A screenshot of the Editing Interface Header shows all tools including Return to Site, File details, Update status, Avatars, Interface buttons, Context Menu, and Save button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Header-Tools-New-Config.webp)
> 
> The [Configuration Mode switch](/documentation/developer-articles/what-is-configuration-mode/) may also appear in your *Editing Interface Header* if you are a member of the Developer or Owner permission groups. This switch allows you to configure the editing experience for your Site, but it won't be visible to all users.

## The *Visual Editor*

The *Visual Editor* is the most intuitive way to edit your website. It allows you to edit your content directly on an interactive preview of your webpage. When you edit using the *Visual Editor*, you can see exactly what your visitors will see when they visit a webpage, and make editing decisions about your content in context. You can also navigate between pages by clicking links, just like on your live website.

The *Visual Editor* works best for files that output to a webpage. If your file doesn't create a webpage (like a data file), the *Visual Editor* won't be available for that file.

[Video: The Visual Editor with editable regions](https://player.vimeo.com/progressive_redirect/playback/1124969057/rendition/1080p/file.mp4?loc=external&signature=18a05ed71665768fa94851c72a31cf574e4079284b8ce0579885d8f3b47c4a8d)

In the *Visual Editor*, content that you can edit is marked with yellow boxes called *Editable Regions*. These yellow boxes show you exactly which parts of your webpage you can edit. When you hover over or click on an *Editable Region*, the border will turn green to help you see the boundaries of that region.

Clicking into an *Editable Region* will do different things depending on what type of content it contains:

- For text content, you can type directly on the page to edit the text. If it is rich text (as opposed to plain text), CloudCannon will also give you a formatting toolbar with options like bold, italic, headings, and lists.
- For image content, CloudCannon will open a Data Panel with options to replace the image or edit its properties like alt text and title.
- For arrays or lists, you'll see tools to add, remove, or reorder items.

You can also use the sidebar in the *Visual Editor* to edit file information (also called structured data or front matter), which is the details about your file that don't appear in the main content. This could be your file title, a date, tags, or other information for your content. Each piece of file information has an Input field in your sidebar. To edit this information, use the fields, buttons, and sliders in each Input. If you would like to add, remove, or change the Inputs in the sidebar, please talk to your developer.

![A screenshot of the Visual Editor displays a webpage preview on the right and a sidebar with input fields on the left.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Visual-Editor-Component-Editable-Region.webp)

The *Visual Editor* does require some configuration, and may not be available for all file types. If you have any questions about using the *Visual Editor* for a specific file, talk to your developer or the friendly CloudCannon [support team](/support/).

## The *Content Editor*

The *Content Editor* is a rich text editor that's perfect for editing content-heavy files like blog posts, articles, or documentation. It provides a clean, distraction-free interface that focuses on your content.

![A screenshot of a blog file open in the Content Editor.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor.webp)

You can type directly into the editor. At the top of the *Content Editor* you will see the text formatting toolbar (also called a WYSIWYG toolbar, which stands for "What-You-See-Is-What-You-Get"). This toolbar might include adding images, links, or Snippets, changing the alignment of your text, or simple tools such as bolding, italicizing, or underlining text.

![A screenshot of the WYSIWYG toolbar in the Content Editor.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Content-Editor-WYSIWYG-Toolbar.webp)

To use these tools, click to place your cursor in the content area of the editor (or, in some cases, highlight your existing text) and then click the icon for the tool you want to use. The number of tools available in your WYSIWYG toolbar will depend on how your *Site* is configured.

> *Snippets* are pre-built content blocks that you can add to your content with just a click. They are reusable templates for common content types like testimonials, call-to-action sections, or product cards. Your developer sets up *Snippets* for your *Site*, so if you don't see any *Snippets* available or want to add new ones, talk to your developer.

Just like the *Visual Editor*, you can use Inputs in the *Content Editor* sidebar to edit file information (like title, date, and tags).

## The *Data Editor*

The *Data Editor* is a simple interface for managing organized information. It's perfect for editing files that contain data like your website navigation menus, staff profiles, product details, or file information. The *Data Editor* also appears as the sidebar in the *Visual Editor* and *Content Editor*, where it helps you manage the file information associated with your content files.

![A screenshot of the Data Editor shows organized information fields in a simple list.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Data-Editor.webp)

The *Data Editor* uses Inputs for each piece of information. To edit your information, use the fields, buttons, and sliders in each Input. If you would like to add, remove, or change the Inputs, please talk to your developer.

## The *Source Editor*

The *Source Editor* is an in-browser code editor that's great for making minor changes to the source code of your files. It displays the raw content of text-based files with automatic syntax highlighting based on the file extension. You can edit the content directly by typing, just like you would in any code editor.

![A screenshot of the Source Editor shows the CloudCannon Configuration File in plain text with syntax highlighting.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Source-Editor.webp)

The *Source Editor* is useful when you need to make small code changes or when you're comfortable working with raw file content. This *Editing Interface* is available to users in Technical Editor [default Permission Group](/documentation/user-articles/what-are-default-permission-groups/) or higher. If you don't see the *Source Editor* as an option, you may not have the required permissions.

## Which interface should you use?

The best interface depends on what you're trying to do:

- Use the *Visual Editor* when you want to see your changes in context and edit directly on a preview of your webpage. This is great for seeing how your content will look to visitors.
- Use the *Content Editor* when you're working with longer written content like blog posts or articles and want a focused, distraction-free editing experience.
- Use the *Data Editor* when you're working with organized information files or need to update file details and settings. This is perfect for editing lists, menus, or product information.
- Use the *Source Editor* when you need to make small code changes or edit the raw content of your files. This interface is only available to users with higher permission levels.

> Some interfaces may not be available depending on your *Site's* configuration or your permissions. If you don't see an interface you expect, talk to your developer.

Don't worry if you're not sure which interface to use; you can always switch between them. CloudCannon will remember your changes no matter which interface you use.

## What if you make a mistake?

If you make a change you don't want to keep, don't worry. CloudCannon makes it easy to undo your changes:

- **Undo a single change:** If you just made a change and want to undo it, you can use your browser's undo function (usually Ctrl+Z or Cmd+Z on Mac).
- **Discard all changes to a file:** If you want to discard all unsaved changes to a specific file, you can use the *Context Menu* (the three dots icon) in the *Editing Interface Header* and select *Discard unsaved changes*. This will revert the file back to its last saved state.
- **Wait until you save:** Remember, your changes aren't saved until you click the *Save* button, so you can always close the file and come back to it later without saving.

In the next step of this guide, we'll learn how to add, delete, rename, and duplicate files with file actions.


---

---
title: More resources
description: Explore additional resources to help you continue learning about editing in CloudCannon.
url: https://cloudcannon.com/documentation/user-guides/editing-in-cloudcannon/more-resources/
content_type: user guide
last_modified: 2026-04-16
---

Congratulations! 🎉 You have finished the *Editing in CloudCannon* guide.

By following each step in this guide so far, you have all the skills you need to edit files, save your changes, and publish them to your live website.

## User articles

You can find more resources about the topics we covered in this guide under the [User Articles](/documentation/user-articles/) section of our documentation. Here are some specific articles you may find helpful:

### Core concepts

- [What is a Collection?](/documentation/user-articles/what-is-a-collection/) — Learn more about how *Collections* organize your content
- [What is the Site Navigation?](/documentation/user-articles/what-is-the-site-navigation/) — Understand all the features available in your *Site Navigation*
- [What is a Testing Domain?](/documentation/user-articles/what-is-a-testing-domain/) — Learn more about your free preview URL

### Editing interfaces

- [What is the Visual Editor?](/documentation/user-articles/what-is-the-visual-editor/) — Detailed guide to the *Visual Editor* and its features
- [What is the Content Editor?](/documentation/user-articles/what-is-the-content-editor/) — Learn more about the *Content Editor* and its formatting tools
- [What is the Data Editor?](/documentation/user-articles/what-is-the-data-editor/) — Understand how to edit organized information and file details
- [What is the Source Editor?](/documentation/user-articles/what-is-the-source-editor/) — For users who need to edit code (requires higher permissions)

### File management

- [Add a file](/documentation/user-articles/add-a-file/) — Comprehensive guide to adding files with multiple methods
- [Delete a file](/documentation/user-articles/delete-a-file/) — Detailed explanation of the deletion workflow
- [Edit your files](/documentation/user-articles/edit-your-files/) — Comprehensive guide to editing in CloudCannon
- [Save your changes](/documentation/user-articles/save-your-changes/) — Detailed article on the saving process

## Next steps

Now that you know how to edit in CloudCannon, you can start editing your website content, explore different *Editing Interfaces* to find which one works best for you, collaborate with your team members on files, and save (or publish) your changes.

If you need help or have questions:

- Refer back to this guide or any of the articles linked above
- Contact your developer if you have questions about your site's configuration
- Reach out to the friendly CloudCannon [support team](/support/) for assistance
- Check out the [CloudCannon Community](https://community.cloudcannon.com/)

You're all set! Happy editing!


---

---
title: Finding your files
description: Learn how to navigate the Collection Browser and File Browser to find the files you want to edit.
url: https://cloudcannon.com/documentation/user-guides/editing-in-cloudcannon/finding-your-files/
content_type: user guide
last_modified: 2026-04-16
---

CloudCannon provides two ways to browse the files on your *Site*: the *Collection Browser* and the *File Browser*. The *Collection Browser* is available to all users, while the *File Browser* is available to users with [Technical Editors](/documentation/user-articles/what-are-default-permission-groups/) permission levels and higher.

## The *Collection Browser*

*Collections* are groups of related files that have a similar format, making it easy to find and organize your content. For example, you might have a *Collection* for your blog posts, another for your webpages (e.g., Home, About, or Contact), and another for your product information.

Your *Collections* appear in the *Site Navigation* on the left side of your screen. Each *Collection* has a name and an icon to help you identify it quickly.

![A screenshot of the Site Navigation shows links to the Collections on this Site, organized into groups.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Navigation-Collections.webp)

When you click on a *Collection*, CloudCannon opens the *Collection Browser*. At the top of the *Collection Browser*, you'll see the *Collection Header* with the collection name and any description or documentation link that's been configured.

![A screenshot of the Collection Browser shows several file cards with previews of each file.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser.webp)

Below the *Collection Header*, you'll find the *Collection Browser Controls* with several tools to help you find and manage your files.

The *Sort* menu lets you change how your files are organized in the *Collection Browser*. You can sort alphabetically, by date created, by date modified, or by file size.

![A screenshot of the Collection Browser shows the Sort menu options.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-Controls-Sort-Dropdown.webp)

The *View* menu lets you switch between different *File Card* types: *List* view, *Card* view, or *Gallery* view.

![A screenshot of the Collection Browser shows the View menu options.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-Controls-View-Dropdown.webp)

![A screenshot of the Collection Browser shows files in the Card view.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-View-Card.webp)

The *Filter* text field lets you search for specific files by typing part of the file name.

![A screenshot of the Collection Browser shows that files are filtered by the term in the Filter text field.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-Controls-Filtered-Files.webp)

The *+ Add* button lets you create new files or folders in the *Collection*. We'll discuss this further [later in the guide](/documentation/user-guides/editing-in-cloudcannon/using-file-actions/).

![A screenshot of the Collection Browser shows the Add dropdown with template options.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-Controls-Add-Menu-Dropdown.webp)

The main area of your *Collection Browser* shows you all the files in that *Collection*, with each file displayed as a *File Card*. *File Cards* show you helpful information like your file title, an image preview (if available), and when the file was last updated.

Clicking on a *File Card* will open that file in one of CloudCannon's four *Editing Interfaces*. Clicking on the six dots in the top right of a *File Card* will open the *Context Menu*, containing several file actions. We'll cover file actions [later in this guide](/documentation/user-guides/editing-in-cloudcannon/using-file-actions/).

![A screenshot of the Collection Browser shows file cards with an open Context Menu.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-Edited-File-Context-Menu.webp)

## The *File Browser*

Unlike *Collections*, which group similar files together, the *File Browser* shows you all the folders and files in your *Site* in a folder structure, similar to how files are organized on a computer.

You can access the *File Browser* by clicking *File Browser* in your *Site Navigation* under the *Developer* heading.

![A screenshot of the Site Navigation shows links to the File Browser and Site Settings.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Navigation-Developer.webp)

The *File Browser* is not visible to everyone. If you don't see the *File Browser* in your *Site Navigation*, you may not have the required permissions. Please contact your developer if you need access to the *File Browser*.

The *File Browser* also displays your files as *File Cards*, and you can use the *Sort* menu, *View* menu, and *Filter* text field to find the files you need.

![A screenshot of the File Browser shows several folders and files organized in folders.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-File-Browser.webp)

One key difference is that the *File Browser* shows every file on your website, including files that might not be part of any *Collection* and technical files that control how your website looks and works (rather than the content).

## Which browser should you use?

Both the *Collection Browser* and the *File Browser* are useful, and you'll likely use both depending on what you're trying to do.

- Use the *Collection Browser* when you want to work with a specific type of content, like all your blog posts or all your pages. *Collections* make it easy to see related files together and are perfect for most content editing tasks.
- Use the *File Browser* when you need to find a specific file by its location in your website's folder structure, or when you're working with files that aren't part of a *Collection* (like technical files).

In the next step of this guide, we'll learn about CloudCannon's *Editing Interfaces* and how to use them to update your content.


---

---
title: Publishing your changes
description: Learn how to publish your changes to your live website when your site uses a branching workflow.
url: https://cloudcannon.com/documentation/user-guides/editing-in-cloudcannon/publishing-your-changes/
content_type: user guide
last_modified: 2026-04-16
---

> This step of the guide is optional.

Publishing workflows are an optional feature on CloudCannon. You can tell if your *Site* uses a publishing workflow by looking for the *Publishing* link in your *Site Navigation* on the left side of your screen. If you don't see a *Publishing* link, your *Site* doesn't use a publishing workflow, and you can skip this page of the guide.

![A screenshot of the Site Navigation shows links to the Dashboard, Publishing, and Inbox pages.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Navigation-Dashboard-Publishing-Inbox.webp)

## What is a Publishing workflow?

Publishing workflows allow everyone on your team to work on their own copy of your website while protecting your public website from unreviewed content changes.

By setting up a Publishing workflow, you can:

- Make changes to your content on a copy of your *Site* and see what the changes look like on the Internet without impacting your public website.
- When you are ready, publish those changes to your public website, or ask for a review from a team member before publishing.

Because everyone can have their own copy of your *Site* in CloudCannon, you can work on different projects simultaneously (or you can have different *Sites* for different projects).

### Where does CloudCannon publish your changes?

When you publish your changes, CloudCannon sends them to your *Publish Branch*. A *Publish Branch* is a copy of your website chosen by your developer. This could be:

- Your live public website
- A staging website where someone reviews changes made by multiple team members before making them public
- Another branch that other team members are also publishing to

### When do you need to publish vs just save?

Understanding the difference between saving and publishing will help you know who can see your changes.

When you save your changes, CloudCannon will:

- Creates a permanent record of your changes in your website's files (your developer can undo these changes, if necessary)
- Makes your changes visible on your *Testing Domain* (anyone with this URL will see them)

When you publish your changes, CloudCannon will:

- Move your saved changes to your *Publish Branch*
- If your *Publish Branch* is  your public website, all your visitors will see your changes

## How to publish your changes

Before you can publish your changes, you must first save them. If you have unsaved changes, save them first using [the previous step](/documentation/user-guides/editing-in-cloudcannon/saving-your-changes/) of this guide.

Click the *Publishing* link in your *Site Navigation*. CloudCannon will open the *Publishing* page, which has three tabs: *Summary*, *Changes*, and *Commits*.

- The *Summary* tab gives you an overview of your publishing setup and buttons to publish your changes.
- The *Changes* and *Commits* tabs let you see all saved changes on your *Site*, organized by file or by editing session.

![A screenshot of the Publishing Info Box on the Publishing Page shows the status, number of commits, and Git provider.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Publishing-Page-Publishing-Info-Box.webp)

The *Summary* tab will always have an information box in the center that explains where CloudCannon will publish your changes. This information is mostly relevant to developers, but here is a quick overview:

- **Status message:** You'll see either "No changes available to publish" or "Changes available to publish" at the top of the box. If you see "No changes available to publish", you need to save your changes first before you can publish.
- **Commit summary:** The subtitle shows how many times you saved your editing session (called "commits") and the name of the *Publish Branch* CLoudCannon will publish to.
- **Compare link:** The "Compare changes on [Git provider]" link takes you to a detailed view of your changes. You may not have access to this because it requires access to your Git provider (a separate software your developer uses to manage your website's files).

Outside of the information box, the *Publishing* page will look slightly different depending on which *Publishing Mode* your developer configured for your *Site*: *Merge Immediately* or *Pull Request*.

### Merge Immediately

*Merge Immediately* is a *Publishing Mode* that lets you publish your changes to your *Publish Branch* immediately, without needing approval from another team member. This is great for small teams or for publishing changes quickly.

If your *Site* uses the *Merge Immediately* mode, the *Summary* tab will have a *Publish* button.

![A screenshot of the Publishing Page shows the Publish button for immediately publishing changes to the Publish Branch.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Publishing-Page-Merge-Immediately.webp)

When you are ready, click the *Publish* button. CloudCannon will immediately publish your changes to your *Publish Branch*. Your changes will then be visible on your public website (or staging website, depending on what your *Publish Branch* is connected to).

### Pull Request

*Pull Request* is a *Publishing Mode* that lets you submit your changes for review before publishing to your *Publish Branch*. This is good for larger teams or when you need content oversight to ensure quality or compliance.

If your *Site* uses the *Pull Request* mode, the *Summary* tab will include a *Create Pull Request* button and a few text fields for your request details.

![A screenshot of the Publishing Page shows fields for Title and Body, and the Create Pull Request Button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Publishing-Page-Create-Pull-Request.webp)

By default, CloudCannon will have a *Title* and a *Body* text field. Fill in these fields with information for the team member who will review your changes. This could be something like:

**Title:** Added new blog

**Body:** Wrote a new blog concerning our latest feature and updated other blog articles with crosslinks to the new blog.

> Your developer may have set up custom fields for your *Pull Request* instead of the standard *Title* and *Body*. You should still fill these in before publishing.
> 
> ![A screenshot of the Publishing Page shows fields for Title and Body, and the Create Pull Request Button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Publishing-Page-Create-Pull-Request-with-Template.webp)

When you are ready, click the *Create Pull Request* button. CloudCannon will send your *Pull Request* to your developer for review.

Once your developer has reviewed and approved your *Pull Request*, click the *Publish Pull Request* button. CloudCannon will publish your changes to your *Publish Branch*. Alternatively, if you change your mind about publishing your changes, you can click the *Close Pull Request* button to cancel the request.

## What's next?

Once you've published your changes, CloudCannon will rebuild your *Publish Branch* with your changes (this is often your public website). The rebuild process usually takes just a few minutes.

You can continue to make more changes while you wait for someone to approve your *Pull Request*, or create a new *Site* to work on another part of your content.

> Your developer may have configured CloudCannon to delete your *Site* once you publish your changes (i.e., click the *Publish and delete* or *Publish Pull Request* button).
> 
> Don't worry! This is part of the *Publishing* workflow. You can easily create a new copy of your *Site* for your next round of changes.

And that's it! You're ready to start editing your website content in CloudCannon. In the next step, we'll share some additional resources to help you continue learning.


---

---
title: User Guides
url: https://cloudcannon.com/documentation/user-guides/
content_type: user guide
last_modified: 2026-04-16
---




---

---
title: Developer Guides
url: https://cloudcannon.com/documentation/developer-guides/
content_type: developer guide
last_modified: 2026-04-16
---




---

---
title: Introduction
description: Learn about the advantages of a staging-production workflow and how to set it up in CloudCannon.
url: https://cloudcannon.com/documentation/developer-guides/staging-workflow-guide/
content_type: developer guide
last_modified: 2026-04-16
---

> **Note:** publishing workflows in CloudCannon are only available on the [Standard plan](/pricing/) and above.

One of the advantages of using CloudCannon is being able to leverage workflows from Git when maintaining and updating your site. This guide will talk about the benefits of a staging workflow, then explore how to set this up in CloudCannon.

You can see [a list of supported Git providers here](/documentation/developer-articles/introduction-to-syncing/#supported-git-providers).

## What is a staging workflow

In a staging workflow, you'll keep two Git branches to serve as **production** and **staging** environments.

- The `production` branch is what you'll show to your end users (visitors to your site). You won't ever edit this branch directly.
- The `staging` branch is where you make all your edits. When your changes are ready, you use Git to merge into the `production` branch.

## Benefits of a staging workflow

One of the most obvious advantages of this workflow is that it allows you to work on the site without your end users seeing any unfinished changes.

You can also set protections on your `production` Git branch to ensure it isn't merged to without appropriate quality assurance. You might require Pull Requests to be issued to your branch, and those Pull Requests might require a suite of automated tests to pass and/or approval from another team member before merging is possible.

Another benefit is that you can tailor each environment according to its use. If your production site has a long postbuild step for compressing images or translating content in another language, you can use environment variables to only run this step on the `production` branch.

File: `.cloudcannon/postbuild`

```sh
if [[ $RUN_POSTBUILD == "true" ]];
then
    npm run postbuild
fi
```


---

---
title: Configuring the production branch
description: Configure your production environment in CloudCannon.
url: https://cloudcannon.com/documentation/developer-guides/staging-workflow-guide/production-branch/
content_type: developer guide
last_modified: 2026-04-16
---

To get the most out of the staging/production workflow, you'll want to configure your `production` branch carefully.

## Prevent direct editing

In this workflow, your `production` branch can only be edited by merging from another branch.

If the `production` branch is edited directly, this could cause merge conflicts which can be difficult for non-technical team members to debug and fix.

To prevent editing of your site in CloudCannon, navigate to your site dashboard, then click *Settings*. In the *Details* section, check **Editing Locked** and click the **Update Site** button.

![A screenshot of the Details page under Site Settings shows the Editing Locked toggle switched on.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Details-Editing-Locked.webp)

You might also want to set up protections on the branch from your Git provider. This will prevent developers on your team from committing directly to the branch. You can even ensure that certain quality assurance measures are met before changes can be merged in (for example, requiring approval from 2 team members, or requiring automated tests to pass).

Read more about the options available from your provider in the links below:

- [Managing protected branches in GitHub](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches)
- [Using branch permissions in Bitbucket](https://confluence.atlassian.com/bitbucketserver/using-branch-permissions-776639807.html)
- [Protected branches in GitLab](https://docs.gitlab.com/ee/user/project/protected_branches.html)

## Make this site user facing

The `production` branch is what you show to your end-users. You might do this by [adding a Custom Domain in CloudCannon](/documentation/developer-articles/what-is-a-custom-domain/) or [outputting the built files to another Git branch to be hosted elsewhere](/documentation/developer-articles/output-a-built-site-from-cloudcannon-to-an-external-provider/).

## Next steps

You have now ensured that your live site can only be altered by merging changes from another branch, adhering to any protections you might have configured.

In the next step, we'll look at setting up a staging site where you can make these changes, preview your work, and publish to the production environment through CloudCannon.


---

---
title: Connecting CloudCannon and Git
description: Connect your Git repository to CloudCannon.
url: https://cloudcannon.com/documentation/developer-guides/staging-workflow-guide/connecting-cloudcannon-and-git/
content_type: developer guide
last_modified: 2026-04-16
---

If you already have a CloudCannon site connected to Git that you want to use as your user-facing site, you can skip ahead to the next step.

## Create a production branch

If you haven't already, create a branch and push it to your Git provider. The name of this branch can be anything, but we've called it `production` to keep things clear.

```sh
git checkout -b production
git push -u origin production
```

Now we'll connect our `production` Git branch to a site on CloudCannon.

## Sync Git with CloudCannon

Navigate to *Sites* in the sidebar. Click the **Add new site** button, and choose **Build with your own files** in the menu that appears.

![A screenshot of the Create a Site page shows the File source, Repository, Branch, and Site name fields completed.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Create-a-Site-Page-Complete.webp)

Choose your Git provider in the **File source** dropdown, and click the **Authenticate** button to begin connecting your Git provider to CloudCannon.

Once you've authenticated with Git, add a name for the site and click **Sync Files**.

This will pull your files from Git. You'll then be asked for the build settings for your site. [See more information about build settings](/documentation/developer-articles/introduction-to-building/) if you are not yet familiar with these options.


---

---
title: Multiple staging branches with projects
description: Use CloudCannon Projects to enable advanced publishing workflows.
url: https://cloudcannon.com/documentation/developer-guides/staging-workflow-guide/creating-a-project/
content_type: developer guide
last_modified: 2026-04-16
---

> **This feature is available on our Team and Enterprise plans.**
> 
> The advanced publishing workflow described on this page is only available on the [Team plan](/pricing/).

In some cases, a single staging environment might not be enough. If your team is working on multiple long-running projects at once, you might often find yourself in situations where finished changes are blocked by unrelated, unfinished changes on the same `staging` branch. Ideally you would publish these changes independently, but the `staging` branch can only be merged as a whole.

One solution to this problem is to create a new branch for each separate piece of work. This means you can merge each branch when it is ready, without being blocked by other pieces of work. This is a workflow that can be achieved in CloudCannon with [Projects](/documentation/developer-articles/create-a-project/).

In this guide, we'll extend our existing workflow so that your team can branch off, and merge back into, your `staging` branch. The production environment will still only be changed when merging from `staging` to `production`, which means you have one last chance to review all your changes together before they go out live. If this is too much administrative overhead for your team, it's just as easy to have multiple branches that merge straight into `production`, or any other workflow you can imagine with Git branches.

## Setting up a Project

Navigate to *Projects* in the sidebar, and click **Create your first project** (or **Create project** if this isn't your first).

Enter a descriptive name for your project, and select the Git repository you have already connected.

You will be asked to specify the **Main Branch** for the project. This determines where to branch off from when creating new sites. If you've been following along with this guide, this should be `staging`.

The Preview Details menu allows you to configure the appearance of the Project overview in CloudCannon. You don't need to touch this for now.

![A screenshot of the Create a Project page shows fields for Git Provider, Repository, Main Branch, and other settings.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Create-a-Project-Page.webp)

Click **Create Project** to finish creating the project.

## Creating branch sites

Click **Add new site** in the *Sites* section of the Project settings. This will create a new Git branch, branching from `staging`, and immediately connect it to a new site on CloudCannon with all the same build settings as your staging site. This new site will be automatically configured to publish back into the `staging` branch.

![A screenshot of the Project page shows the Sites list with a Create a Site button and one connected Site.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Project-Sites-Browser.webp)

This enables a workflow where members of your team can easily:

1. Create a branch site;
2. Make changes and preview them on a testing domain;
3. When ready, merge those changes into the `staging` branch;
4. When everything on the staging branch is ready to go, merge into `production`.

The immediate benefit of this workflow is that the `staging` branch will rarely have any unfinished changes, so you can merge from `staging` to `production` quite freely.

To prevent your organization becoming cluttered with sites representing finished and published changes, branch sites will automatically have the **Delete this site after publish** option turned on. You can toggle this in the site settings, under *Publishing*.

![A screenshot of the Publishing page under Site Settings shows the Publish Branch, Publishing Method, and post-publishing behavior options.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Publishing-Settings.webp)


---

---
title: Configuring the staging branch
description: Create a staging environment and publishing workflow in CloudCannon.
url: https://cloudcannon.com/documentation/developer-guides/staging-workflow-guide/staging-branch/
content_type: developer guide
last_modified: 2026-04-16
---

The `staging` branch is where you can make edits and preview your changes before they go live.

## Creating a staging site

You'll need to create a new branch from `production`, push it to your Git provider, and connect it to a new CloudCannon site.

You can do this all at once in CloudCannon, through the site creation menu!

- Navigate to *Sites* in the sidebar.
- Click the **Add new site** button, and choose **Build with your own files** in the menu that appears.

![The Create a Site page with the Create a new branch option selected, branching from main.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Create-a-Site-New-Branch.webp)

- Select your Git repo and choose **Create a new branch**. Select `production` as your source branch, and choose a name for your new branch (in this guide, we'll call it `staging`).
- Continue through the steps of syncing and building the new site.

## Set up publishing

"Publishing" is the term CloudCannon uses for merging one branch into another. For more details, read [our documentation on publishing](/documentation/developer-articles/connect-a-publish-branch/).

Navigate to your new staging site, and open the Site Settings. You'll see a section called "Publishing".

![The Publishing settings page in CloudCannon, showing the publish branch and merge mode options.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Publishing-Settings.webp)

Here, you can choose a branch to merge into. Select the `production` branch.

You will also need to choose a Publish Mode. This simply means deciding whether you want to merge directly from CloudCannon, or to create a Pull Request before each merge.

Either way, you will see a new **Publish** button appears in the site sidebar, underneath the **Save** button. Click this button to review your pending changes and merge them into production.

### Merging via Pull Request

> **Note:** GitLab uses the terminology *Merge Request* for this action; these will display as *Pull Requests* in CloudCannon.

If you have selected *Pull Request* as your Publish Mode, you will be able to issue pull requests from CloudCannon. Enter a title and description and click **Create Pull Request**. You can see a list of the pending commits on the right.

![The Publishing page with fields to create a Pull Request](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Publishing-Page-Create-Pull-Request.webp)

Pending pull requests will be listed in this menu. You can click **Merge** to merge the branch, or **Close** to close the pull request. If you have set any branch protection rules with your Git provider which would be violated by this merge, the merge will fail and the pull request will stay open.

![The Publishing page showing an open Pull Request with the option to merge](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Publishing-Page-Open-Pull-Request.webp)

### Merging directly

If you want to be able to merge staging into production directly from CloudCannon, select **Merge** as the Publish Mode. In this case, the Publish menu will simply show a **Merge** button, with no intermediate steps.

## What's next?

You now have a staging/production workflow! You can preview your in-progress changes on the [Testing Domain](/documentation/user-articles/what-is-a-testing-domain/) for your staging site, and merge them into your user-facing production site only once you are ready.

The next step of the guide will explore ways to extend this workflow for more use cases. This is optional and may be useful depending on your particular project.


---

---
title: Introduction
description: Learn how to create a Site on CloudCannon and set up WYSIWYG editing for your website files.
url: https://cloudcannon.com/documentation/developer-guides/getting-started-with-cloudcannon/
content_type: developer guide
last_modified: 2026-04-16
---

Welcome to the Getting Started with CloudCannon guide!

This guide is an excellent starting point for developers new to CloudCannon. We recommend that you complete this guide first, as other developer guides on the CloudCannon Documentation website may rely on the steps outlined here.

CloudCannon is a Git-based Content Management System designed to help teams (or individuals) manage their website content and code. Developers can commit changes to a Git repository that syncs to CloudCannon. At the same time, CloudCannon provides an interface that allows non-technical team members to effortlessly update the content stored in your Git repository, without needing to know anything about Git, Markdown, or HTML. All your files are stored safely and securely in your Git repository — no vendor lock-in.

In this guide, we'll cover how to create an account, add your files to a *Site*, and set yourself up for success on CloudCannon with a *Configuration File* and *Collections*. By the end of this guide, you will have set up a basic *Site* in CloudCannon with WYSIWYG editing, ready for you to manage your content.

Before we begin, this guide assumes you already have a website and your files are uploaded to a Git repository. Although you can [upload files directly](https://cloudcannon.com/documentation/developer-articles/create-a-site-with-direct-upload/) from your local storage, we highly recommend using a Git repository.


---

---
title: Create a Site
description: Learn about Sites on CloudCannon and how to create your first Site.
url: https://cloudcannon.com/documentation/developer-guides/getting-started-with-cloudcannon/create-a-site/
content_type: developer guide
last_modified: 2026-04-16
---

A *Site* is where you see, edit, and review all your website files. *Sites* are core to your CloudCannon experience and are where you and your content teams will spend the majority of your time.

The features of a *Site* are likely why you are looking for a CMS in the first place. *Sites* allow you to:

- See all your files in user-friendly editing interfaces, without the need to know Markdown, HTML, or Git.
- Organize files to create a more intuitive experience for your content creators.
- Create review processes for saving changes to your content.
- Track the who, when, and why for each change to your website.

In this step of the guide, we'll create your first *Site* by syncing your website files to CloudCannon from your Git repository and point out important UI during a tour of your new *Site*.

## Using a Git provider

When you create a *Site*, CloudCannon first needs to sync your website files from their current location. This could be your local computer storage, or a Git repository maintained using one of CloudCannon's supported Git providers: [GitHub](https://cloudcannon.com/documentation/developer-articles/connecting-a-github-repository-as-your-source/), [GitLab](https://cloudcannon.com/documentation/developer-articles/connecting-a-gitlab-respository-as-your-source/), or [Bitbucket](https://cloudcannon.com/documentation/developer-articles/connecting-a-bitbucket-respository-as-your-source/).

> We highly recommend using a Git provider for better security, version control, and collaboration.

This guide will cover how to create a *Site* from files stored in a Git repository.

## Create your first *Site*

Let's walk through how to authenticate your Git provider, select a repository and branch, name your *Site*, and sync your files. If you already have at least one *Site* on CloudCannon and are using this guide to create another, most of the instructions will be the same; however, some pages or UI may look different.

In the previous step of this guide, we introduced you to your *Organization Home* page and its two *Cards* for getting started. To create a *Site* from your own files, click the *Add your own files to CloudCannon* card.

![A screenshot of the Add your own files to CloudCannon card from the Organization Home page.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Organization-Home-Add-Your-Files-Card.webp)

CloudCannon will open the *Create a Site* page.

Here, you can use the *File source* dropdown to select your Git provider.

![A screenshot of the Create a Site page shows a dropdown to select your File Source from a Git repository, local storage, or a template.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Create-a-Site-Source-Dropdown.webp)

> If you already have one or more *Sites* associated with your *Organization*, the *Try our demo Site* or *Add your own files to CloudCannon* options will not appear on your *Organization Home* page. Instead, click the *Sites* button in the *App Sidebar* to open the *Sites Browser*. You can add a new Site to CloudCannon using the *+ Create a Site* button at the top right of the *Sites Browser*.
> 
> ![A screenshot of the Sites Browsers shows one Site and the + Create a Site button in the top right.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Sites-Browser-One-Site.webp)

### Authenticate your Git provider

For CloudCannon to sync your files, you must give it permission to access your Git provider. You can see which Git providers are authenticated by a green shield icon next to the option in the *File source* dropdown.

![A screenshot of the list of Git providers shows the green shield icon indicating that Git Hub is authenticated through CloudCannon.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Create-a-Site-Authenticated-GitHub.webp)

When you select an unauthenticated Git provider using the *File source* dropdown, CloudCannon will show you the *Authenticate* button.

Click this button and CloudCannon will forward you to your Git provider login screen. Follow your Git provider's instructions to authenticate access, then return to the *Create a Site* page on CloudCannon.

![A screenshot of the Create a Site page shows an Authenticate button to approve CloudCannon's access to GitHub.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Create-a-Site-Authenticate-GitHub.webp)

You only need to authenticate your Git provider once; CloudCannon will remember it for all other *Sites* you create.

### Select your repository and branch

Once you have selected an authenticated Git provider using the *File source* dropdown, the *Create a Site* page will show a *Repository* dropdown and *Branch Setup* section. The *Repository* dropdown will list all the available repositories from your authenticated Git provider account.

Select the correct repository from the list. You can type in the *Repository* text field to filter your options, if necessary.

![A screenshot of the Create a Site page shows the Repository dropdown with several options.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Create-a-Site-Repository-Dropdown.webp)

As a Git-based CMS, CloudCannon uses branching for better security and version control, as well as to enable your team to work on updates in parallel. Each *Site* on CloudCannon is connected to a branch of your Git repository.

Use the *Branch setup* radio buttons to select either *Use an existing branch* or *Create a new branch*. You will most likely want to use an existing branch, but if you want to try CloudCannon without impacting your existing work, you can create a new one.

If you select *Use an existing branch*, use the *Branch* dropdown to select a branch from your repository.

![A screenshot of the Create a Site page shows the Use an existing branch radio button and the Branch dropdown.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Create-a-Site-Existing-Branch-Dropdown.webp)

If you select *Create a new branch*, use the *Source branch* dropdown to select which branch from your repository to copy and enter a name for your new branch in the *New branch name* text field.

![A screenshot of the Create a Site page shows the Create a new branch radio button, Source branch, and New branch name fields.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Create-a-Site-New-Branch.webp)

### Name your Site

The *Site name* text field determines the name for your *Site* in CloudCannon. This won't affect your repository or branch in your Git provider.

CloudCannon will automatically populate this field with the name of your repository, but you can choose any name for your *Site*. We recommend choosing a simple name that provides information about the purpose of the Site (e.g., "CloudCannon Marketing Website", "Production: CloudCannon Documentation", "Staging: CloudCannon Documentation").

Use the *Site name* field to add a name for your *Site*.

![A screenshot of the Create a Site page shows all fields are complete.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Create-a-Site-Page-Complete.webp)

Click the *Create Site and start syncing* button at the bottom of the page.

### CloudCannon will sync your files

CloudCannon will begin syncing your files from your Git provider and open your *Site Dashboard*.

On your *Site Dashboard*, you'll see another in-app guide: *Getting Started with Editing*. This guide focuses on setting up the basics of your *Site.*

![A screenshot of the Site Dashboard shows the Getting Started with Editing guide with a task to Add your Files.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Dashboard-Add-Your-Files-Task.webp)

The first task in the *Getting Started with Editing* in-app guide is to *Add your files*. As CloudCannon is already syncing your files from your Git repository, you should see an in progress message under this step. This process is usually quick, but it may take a few minutes for larger repositories.

Once CloudCannon has finished syncing, you can click the *Next* button.

![A screenshot of the Add your Files task from the Getting Started with Editing in-app guide shows the Next button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Add-Your-Files-Task.webp)

In the next step of this guide, we'll look at your new *Site* and introduce you to some important UI.


---

---
title: Tour your Site
description: Take a guided tour around the new Site you have made in CloudCannon.
url: https://cloudcannon.com/documentation/developer-guides/getting-started-with-cloudcannon/tour-your-site/
content_type: developer guide
last_modified: 2026-04-16
---

The next task in the *Getting Started with Editing* in-app guide is *Tour your new Site*, which points out important UI on your new *Site*. If you would rather continue configuring CloudCannon, feel free to skip this task.

Click the *Start your tour* button and let CloudCannon show you around.

![A screenshot of the Site Dashboard shows the Getting Started in-app guide with a task to Tour your new Site.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Tour-Site-Task.webp)

## General *Site* UI

At the top of your *Site* is the *Site Header*, and on the left is the *Site Navigation* and *App Sidebar*.

![A screenshot of the Site Header shows the Site details and tools.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Header-No-Build.webp)

The *Site Header* displays key information about your *Site* in the top left, such as your *Site* icon, name, and branch, and important tools in the top right, such as the *Avatars* of all the team members viewing a *Site* and the *Save* button. More tools will appear in your *Site Header* as you set up your *Site*.

![A screenshot of the Site Navigation shows links to important Site pages, including Dashboard, Collections, and Site Settings. ](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Navigation-Onboarding.webp)

The *Site Navigation* lists important pages on your *Site*, such as your *Site Dashboard*, *Collections*, *File Browser*, and *Site Settings*. More links can appear in your *Site Navigation* depending on the CloudCannon features you configure (e.g., *Publishing* or *Inbox*).

![A screenshot of the App Sidebar shows buttons for important sections in your Organization, including Sites, Domains, and Settings.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-App-Sidebar.webp)

Finally, we introduced the *App Sidebar* in a [previous step of this guide](/documentation/developer-guides/getting-started-with-cloudcannon/your-organization-on-cloudcannon/) (the blue navigation bar on the far left). If you ever navigate away from your *Site* and need to find it again, you can click the *Sites* button in your *App sidebar* and use the *Sites Browser* to find it again.

## The *Site Dashboard*

The majority of your screen is taken up by your current *Site* page: in this case, the *Site Dashboard*. Your *Site Dashboard* is the homepage for your *Site*.

![A screenshot of the Site Dashboard shows the Getting Started in-app guide with a task to Tour your new Site.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Dashboard-Tour-Site-Task.webp)

The *Site Dashboard* is the first link in your *Site Navigation*. Next to this link are the *Status* indicator and the *Guide progress* indicator, which show the status of your most recent sync or build, and how far you have progressed through your active in-app guide.

![A screenshot of the Dashboard link in the Site Navigation, with the Status indicator and Guide progress indicator.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Navigation-Dashboard-Onboarding.webp)

The *Site Dashboard* is broken down into several tabs, including *Summary*, *Activity*, *Syncs*, and *Guides*.

![A screenshot of the Site Dashboard tabs on a new Site shows the Summary, Activity, Syncs, and Guides tabs.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-New-Site-Dashboard-Tabs.webp)

> Depending on how you configure your *Site*, additional tabs, such as *Builds* and *Build Deploys*, can appear on your *Site Dashboard*.

On the *Summary* tab of your *Site Dashboard*, CloudCannon will display summary information about your *Site*. For new *Sites*, CloudCannon has the *Getting Started with Editing* in-app guide in the center, with suggested tasks for configuring your *Site*. Underneath the in-app guide is a list of your recent activity. On the right, the *Summary* tab also gives a preview of your most recent sync.

![A screenshot of the Activity tab on the Site Dashboard shows two activity item.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-New-Site-Dashboard-Activity-Tab.webp)

On the *Activity* tab of your *Site Dashboard*, CloudCannon will show you a list of recent activity on your *Site* in reverse chronological order. This list refreshes every time you sync your *Site* or update your *Site Settings*. This list includes:

- Every change made to your files from within CloudCannon or your Git provider (including the author, date, time, and commit message, if applicable).
- When your *Site* has Syncing or Output errors.
- Any changes made to your *Site Settings*, or *Branch* and *Publish Branch* settings.

![A screenshot of the Syncs tab on the Site Dashboard shows one Sync log.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-New-Site-Dashboard-Syncs-Tab.webp)

On the *Syncs* tab of your *Site Dashboard*, CloudCannon will show you a list of syncing logs for your *Site* in reverse chronological order.

![A screenshot of the Guides tab on the Site Dashboard shows one active guide and several other available guides.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-New-Site-Dashboard-Guides-Tab.webp)

On the *Guides* tab of your *Site Dashboard*, CloudCannon will show you a list of in-app guides. You can see the number of available guides in a notification by the name of the tab.

Right now, we are working through *Getting Started with Editing*. There are several other guides you can follow to configure other features in CloudCannon after you have finished *Getting Started with Editing*.

## The *Collection Browser*

When you selected your *Collections* in the [previous step of this guide](/documentation/developer-guides/getting-started-with-cloudcannon/create-your-cloudcannon-configuration-file/), CloudCannon added them to your *Site Navigation*. Click on one to open your *Collection Browser.*

The *Collection Browser* allows you to browse, sort, and filter your *Collection* files, add new ones, and perform file actions like cloning or deleting. Each *Collection Browser* shows all the files in a single *Collection*, with each file represented by a customizable *File Card*.

![A screenshot of the Collection Browser shows several tools for browsing, sorting, and filtering your Collection files.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-View-Gallery-No-Build.webp)

At the top of your *Collection Browser*, underneath your *Site Header*, is the *Collection Header*. This section contains important identifying information about your *Collection*, such as the *Name*, and *Documentation Link* or *Description* (if configured).

Under the *Collection Header* are the *Collection Browser Controls*: the *Sort* *menu*, *View* *menu*, *Filter* text field, and the *+ Add menu*.

![A screenshot of the + Add menu in the Collection Browser shows a dropdown with options to add a new file or folder.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-Controls-Add-Menu-Dropdown-No-Build.webp)

The *Sort* *menu* lets you change how CloudCannon sorts your files in the *Collection Browser* (e.g., alphabetically by file path, numerically by file size, by date and time of file creation, or by date and time of last modification).

The *View* *menu* allows you to change how your files appear in the *Collection Browser*. You can switch between three view options: *List*, *Card*, and *Gallery*. By default, your *Collection Browser* uses the *Gallery* view. The gallery section of the *Card* can display an image from within the file or a preview screenshot of the webpage.

> The gallery section of your *File* *Card* can also display a "No preview available" or "Failed to load image" warning.
> 
> "No preview available" indicates that the preview screenshot has not been configured. This will be the case for *Sites* that have not been built. We'll cover screenshots more in the [Set up Visual Editing](/documentation/developer-guides/set-up-visual-editing/) guide.
> 
> "Failed to load image" indicates that an error has occurred, and CloudCannon could not load the preview screenshot. Refreshing your browser may fix this.

The *Filter* text field allows you to filter your *Collection* files to show file paths that match a given string.

The *+ Add* button allows you to add new files and folders to a Collection, which you can save back to your Git repository.

## Using *Configuration Mode*

CloudCannon allows you to customize almost everything about your *Site* to create the best editing experience for your team. Turn on *Configuration Mode* to configure your *Site* using the switch on the right of the *Site Header*.

![A screenshot of the Site Header tools shows the Avatar List, Configuration Mode toggle, and the Save button with one unsaved change.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Header-Tools-New-Config.webp)

When *Configuration Mode* is on, CloudCannon displays purple *Edit Configuration* buttons throughout the app. Each of these buttons allows you to configure a different UI element.

Let's take a look at the *Collection Browser*. Using *Configuration Mode*, you can update the name, icon, and description, the default file sorting, the appearance of your *File Cards*, and more.

![A screenshot of the Collection Browser shows several UI elements highlighted in Configuration Mode purple.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-Configuration-Mode-On.webp)

You can also change your *Collections*. If you decide you want to add or remove a *Collection* from CloudCannon, you can return to the *Edit Collections* modal by clicking the *Edit Collections* button in the *Site Navigation*.

![A screenshot of the Site Navigation shows that several Collections are now present.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Navigation-New-Collections.webp)

Go ahead and try configuring your *Collection*, or open a *Collection* file in an *Editing Interface* by clicking on the *File Card*. When you are ready, we'll cover saving your *Configuration File* back to your *Git Repository* in the next step of this guide.


---

---
title: More resources
description: Learn about other guides for setting up optional configuration in CloudCannon.
url: https://cloudcannon.com/documentation/developer-guides/getting-started-with-cloudcannon/more-resources/
content_type: developer guide
last_modified: 2026-04-16
---

Congratulations! 🎉

By following each step in this guide so far, you have set up basic WYSIWYG editing for your *Site* on CloudCannon. But there's a lot more to CloudCannon that we haven't covered yet. Check out the sections below for more resources to help you on your CloudCannon journey.

Thanks for finishing the *Getting Started with CloudCannon* guide! If you have any questions, please reach out to our friendly [support team](/support/) or check out the [CloudCannon Community](https://community.cloudcannon.com/). We're always here to help.

## User guides

Now that you have basic WYSIWYG editing set up on your *Site*, you can start using CloudCannon to manage your content. Here are a few guides to help you and your team learn important skills for working in CloudCannon.

- [Editing in CloudCannon](/documentation/user-guides/editing-in-cloudcannon/)— Learn how to edit your files in CloudCannon's Content, Data, or Source Editors and save those changes back to your *Git Repository*.

## Developer guides

There are so many more features you can configure in CloudCannon. While technically optional, we highly recommend reading through these other guides to figure out which configuration you need.

You can complete these guides in any order, but here's the order we suggest:

- [Set up Visual Editing](/documentation/developer-guides/set-up-visual-editing/) — Learn how to enable the Visual Editor by adding *Editable Regions* to your files, as well as configure builds for preview screenshots in your *Collection browsers*.

Most of these guides have in-app counterparts. You can find a complete list of guides that configure your *Site* (rather than your *Organization*) under the *Guides* tab on your *Dashboard*. You can also see your current in-app guide on the *Summary* tab by marking it as active.

![A screenshot of the Guides tab on the Site Dashboard shows one active guide and several other available guides.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Dashboard-Guides-Tab-Visual-Editing.webp)


---

---
title: Create an account
description: Learn how to create an account on CloudCannon.
url: https://cloudcannon.com/documentation/developer-guides/getting-started-with-cloudcannon/create-an-account/
content_type: developer guide
last_modified: 2026-04-16
---

Let's create an account on CloudCannon. If you already have a CloudCannon account, you can skip this step of the guide.

Open the [CloudCannon app](https://app.cloudcannon.com/register) using your Internet browser. You can create an account using your email, or your GitHub, Bitbucket, or GitLab account. In this guide, we will create an account using our email.

Click on the *Sign up with email* button.

![A screenshot of the Register page shows the options to sign up with GitHub, Bitbucket, GitLab, or email.](assets/onboarding_screenshots/CloudCannon-Documentation-Create-Account-Login-Page.png)

Enter your email in the *Email address* field and click *Send Code*.

![A screenshot of the Signup page shows a field to enter the email address you want to associate with your CloudCannon account.](assets/onboarding_screenshots/CloudCannon-Documentation-Create-Account-Enter-Email.png)

To validate your email address, CloudCannon will send a six-digit confirmation code to the email you provided. This validation email should arrive in your inbox quickly and will expire after 10 minutes.

Enter the code in the *Confirmation Code* field and click *Continue*.

![A screenshot of the Signup page shows a field for your Confirmation Code to validate your email address.](assets/onboarding_screenshots/CloudCannon-Documentation-Create-Account-Verify-Email.png)

Once you have validated your email address, you can finish adding your account details, such as your first name, last name, and an account password, and whether you are a developer or a content editor.

Your password must be at least nine characters long.

> Do not share your CloudCannon password with anyone. CloudCannon employees will never ask you for your password.

Click *Create my account* to finish creating your account.

![A screenshot of the Signup page shows fields for your first name, last name, password, and role.](assets/onboarding_screenshots/CloudCannon-Documentation-Create-Account-Details.png)

Congratulations, you have created your CloudCannon account! In the next step of this guide, we'll cover what an *Organization* is and how to navigate the *App Sidebar*.


---

---
title: Your Organization on CloudCannon
description: Learn about Organizations on CloudCannon and familiarize yourself with the App Sidebar.
url: https://cloudcannon.com/documentation/developer-guides/getting-started-with-cloudcannon/your-organization-on-cloudcannon/
content_type: developer guide
last_modified: 2026-04-16
---

After you create your account, CloudCannon will automatically make you a default *Organization* and deliver you to your *Organization Home* page.

## What is an *Organization*?

An **Organization** is the highest level of content management on CloudCannon, containing all your websites, team members, and resources. Once you create your first *Site*, the *Organization Home* page will display summary information about all of these things but, for now, you'll only see two *Cards*. You can navigate back to your *Organization Home* page at any time by clicking the *Home* icon in the *App Sidebar*.

![A screenshot of the Organization Home page shows Setting up your Organization in-app guide with a task to complete a Welcome Tour.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Organization-Home-No-Sites.webp)

*Organizations* are also the billing unit in CloudCannon; each *Organization* has it's own subscription at one of CloudCannon's [pricing tiers](/pricing/). As a new account, your *Organization* will be on a *Free Trial*, so you have time to explore CloudCannon and decide what tier is right for your team.

You can also join other people's *Organizations* by invitation, which will allow you to manage their content.

## General *Organization* UI

Let's take a look at some of the UI for your *Organization*.

On the left is the *App Sidebar*. This contains several tools for managing your *Organization* and *Account*. At the top are links to your *Home*, *Sites*, *Projects*, *Domains*, and *Org Settings* pages. We'll cover each of these in greater detail later, or in other guides relevant to those sections. For now, it's important to note the link to the *Home* page at the top of the *App Sidebar*. If you get stuck, return to this page for more guidance.

![A screenshot of the Organization Navigation in your App Sidebar shows links to the Home, Sites, Projects, Domains, and Org Settings pages.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-App-Sidebar-Organization-Navigation.webp)

At the bottom of the *App Sidebar* is the *Updates* button and your *Account Menu*. Clicking on the *Updates* button will open the *App Updates* modal with a list of CloudCannon's most recent changelogs.

Clicking on your *Avatar* and *Name* will open the *Account Menu*. Here you can find a link to your *Account Settings*, message our friendly [support team](/support/), and log out of CloudCannon with the *Log Out* button, as well as navigate to other *Organizations* (if you are a member of multiple Orgs).

![A screenshot of the footer of the App Sidebar shows links for the Updates modal and the Account Menu.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-App-Sidebar-Account-Menu.webp)

## Should I use a template or my own files?

Your *Organization Home* page presents two options for creating your first *Site*: *Try our demo Site* or *Add your own files to CloudCannon*.

To help you experience all of CloudCannon's features without needing to set up anything yourself, we've made the Jetstream template: a fully configured Astro website with visual editing, blogging, page building, and hosting.

![A screenshot of the Site Dashboard Summary tab shows recent Site activity and information.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Dashboard-Summary-Tab.webp)

However, we highly recommend using your own files in CloudCannon.

Don't worry about choosing the "wrong" option here — you can always come back to your *Organization Home* page and try the other option later, and you can create as many *Sites* as you need.

In the next step of this guide, we'll create a *Site* by connecting a Git repository and syncing your files to CloudCannon.


---

---
title: Create your CloudCannon Configuration File
description: Learn about the CloudCannon Configuration File, including what it does and how to make one.
url: https://cloudcannon.com/documentation/developer-guides/getting-started-with-cloudcannon/create-your-cloudcannon-configuration-file/
content_type: developer guide
last_modified: 2026-04-16
---

The next task in the *Getting Started with Editing* in-app guide is to *Create your CloudCannon Configuration File*.

![A screenshot of the Site Dashboard shows the Getting Started in-app guide with a task to create your CloudCannon Configuration File.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Dashboard-Create-Config-File-Task.webp)

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

As we go through the later steps of this guide, we'll add more to our *Configuration File*. Let's create one.

Click the *+ Create my Configuration File* button in your in-app guide under the *Create your CloudCannon Configuration File* task. CloudCannon will open the *Create my Configuration File* modal.

![A screenshot of the Create your CloudCannon Configuration File task from the Getting Started in-app guide shows the Create my Configuration File button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Create-Config-File-Task.webp)

The *CloudCannon Configuration File* is stored at the root of your website directory by default and can be YAML or JSON. When you answer the questions in this modal, CloudCannon will create the `/cloudcannon.config.yml` file in the root of your repository.

> **A quick note about Documentation...**
> 
> CloudCannon links to helpful documentation in multiple places throughout the App. When you see the question mark symbol next to a link, or on its own next to a title, clicking on it will open the relevant page on the CloudCannon Documentation website in a modal.
> 
> ![A screenshot of an in-app documentation link.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Create-A-Site-Page-Docs-Link.webp)

## Select your *Static Site Generator*

![A screenshot of the Create my Configuration File modal shows a dropdown for selecting your SSG and a checkbox for Use a custom source.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Dashboard-Create-Config-File-Modal.webp)

To start with, CloudCannon needs to know which **Static Site Generator** your *Site* uses. An SSG is a tool for generating a static HTML website from your files. CloudCannon supports various SSGs, from Astro, Eleventy, and Hugo to Jekyll, MkDocs, and Lume. You can choose whichever SSG is appropriate for your website files.

CloudCannon will use the information found in your files to suggest an *SSG*. You can click on the *Use* button under the right side of the *Static Site Generator* dropdown to populate it with CloudCannon's suggestion, or select an option from the list of CloudCannon's supported *SSGs*.

At the bottom of the *Create my Configuration File* modal is the *Preview* button. Clicking this button will show you a preview of the initial content of your *CloudCannon Configuration File*.

![A screenshot of the Create my Configuration File modal shows the initial content CloudCannon will add to your Configuration File.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Create-Config-File-Modal-Code.webp)

## Select your *Source Folder* (optional)

![A screenshot of the Create my Configuration File modal shows a checkbox for Use a custom source and a text field for Source Folder.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Create-Config-File-Modal-Custom-Source.webp)

CloudCannon needs to know the base path for your SSG source files relative to the root of your directory, called the *Source Folder*. Most websites use the root of their repository as the *Source Folder*.

However, if your source is nested in your repository (such as if you have a mono-repo), you should check the *Use a custom source* box and enter the file path in the *Source Folder* text field.

## Select your *Collections*

Click the *Next* button on the bottom right of the *Create my Configuration File* modal.

![A screenshot of the Create my Configuration File modal shows a tree structure of potential Collections detected in your files.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Create-Config-File-Modal-Add-First-Collections.webp)

On the next page of the modal, CloudCannon asks you to select your *Collections*. A **Collection** is a group of files you want to edit in CloudCannon, and will match a folder in your *Git Repository* (e.g., a folder of pages, blog posts, product descriptions, or data files).

Once you select your *Collections,* they will appear in your *Site Navigation* for easy access. On the right of the modal, you can see a preview of the default name and icon CloudCannon will assign to each *Collection* (you can change these later), along with the number of content files each *Collection* will contain.

![A screenshot of a detected Collection in the Create my Configuration File modal.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Create-Config-File-Modal-Detected-Collection.webp)

CloudCannon will automatically detect which folders in your *Git Repository* contain content files and suggest that you turn these into *Collections*. By default, suggested *Collections* are checked in the *Create my Configuration File* modal. Alternatively, you can deselect any folders you don't want to edit in CloudCannon using the checkbox.

> **What happens when you select one** ***Collection*** **nested inside of another?**
> 
> Files can only belong to one *Collection* at a time. If you select two *Collections*, one nested inside another, the files will appear in the *Collection* with the most specific *Path*.
> 
> Let's walk through an example.
> 
> ![An illustration of a file structure shows a blog folder with two nested files and a nested authors folder, which also has two nested files.](assets/diagrams/CloudCannon-Documentation-Collection-File-Structure.png)
> 
> Assume you have an `authors` folder nested in your `blog` folder (i.e., `/blog/authors/`). The `authors` folder contains non-output data files with profile information about your various blog authors. In addition to the `authors` folder, the `blog` folder also contains all your output blog files. In this case, both the `authors` and `blog` folders could be *Collections*.
> 
> If you only add the "Blog" *Collection* with the path `/blog/`, all your output blog files will belong to this *Collection*, but so will all the data files inside `/blog/authors/`. All these files will appear as a sub-folder in your Blog *Collection Browser*.
> 
> Adding the "Blog" *Collection* and the "Authors" *Collection* will separate these files, keeping your output blog files in one *Collection Browser* and your non-output data files in another.

Like the previous section of the *Create my Configuration File* modal, you can click the *Preview* button in the bottom right to preview the contents you are adding to your *CloudCannon Configuration File*.

Here's an example of what that configuration code might look like for a *Collection*:

File: `cloudcannon.config.yml`

```YAML
```
collections_config___1___:
  news___2___:
    path___3___: /blog/news/
    icon___4___: breaking_news
```

**[1]** All *Collections* are defined under the `collections_config` key in your *CloudCannon Configuration File*.

**[2]** The *Key* for this *Collection* is `news`. All the configuration for this *Collection* is stored nder this *Key*.

**[3]** The *Path* for this *Collection* is `/blog/news/`, telling CloudCannon where to find the *Collection* files in your repository.

**[4]** The *Icon* for this *Collection* is `breaking_news`.
```

When you are happy with your selection, click the *Create my Configuration File* button at the bottom of the modal, and CloudCannon will add `cloudcannon.config.yml` to the root of your repository. Your *Collections* will appear in the *Site Navigation.*

Congratulations! You've made your first change to your website content: adding a file. You might notice that the *Save* button in the top right now has a red "1" notification. This indicates that you have made a change to one file. Don't click the *Save* button just yet—we'll talk about saving changes to your *Site* in the [save your Configuration File](/documentation/developer-guides/getting-started-with-cloudcannon/save-your-configuration-file/) step of this guide.

![A screenshot of the Site Header tools shows the Avatar List, Configuration Mode toggle, and the Save button with one unsaved change.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Header-Tools-New-Config.webp)

You might also notice a new UI element next to the *Save* button. This is the *Configuration Mode switch*. Now that we have a *Configuration File*, we can use *Configuration Mode* to customize our *Site* and store our preferences.

In the next step of this guide, we'll look at your new *Site* and introduce you to some important UI.


---

---
title: Save your Configuration File
description: Learn how to save the changes to your Configuration File back to your Git Repository.
url: https://cloudcannon.com/documentation/developer-guides/getting-started-with-cloudcannon/save-your-configuration-file/
content_type: developer guide
last_modified: 2026-04-16
---

Over the course of this guide, we have added content to the *CloudCannon Configuration File* several times. CloudCannon will live update every time you add the *Configuration File*, but it is still important to save your changes back to your Git repository.

Let's commit the *CloudCannon Configuration File* and your CloudCannon preferences to your *Git Repository*.

The *Save* button is on the right of your *Site Header*, and will show a red notification with the number of files that have unsaved changes. In this case, the *CloudCannon Configuration File* is the only file with unsaved changes.

![A screenshot of the Site Header tools shows the Avatar List, Configuration Mode toggle, and the Save button with one unsaved change.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Header-Tools-New-Config.webp)

Click the *Save* button. CloudCannon will open the *Save changes* modal.

![A screenshot of the Save changes modal shows a list of files with unsaved changes, including details about when it was updated and by whom.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Save-Changes-Modal-New-Config.webp)

The *Save changes* modal allows you to review a summary of all unsaved changes on a *Site*. Each file with unsaved changes is represented by a *File Card*, including the name of the file, the *Collection* it belongs to, when it was last updated and by whom.

When you look at the files in the *Save changes* modal, you can see a three-dot icon at the top right of each *File Card*. This is the file *Context Menu*, containing a set of file actions that may be useful before you save your changes.

Depending on your *Site* configuration, the *Context Menu* will contain different options. For this guide, your *CloudCannon Configuration File* should have the following options:

- *Data Editor* — Open the file in the CloudCannon Data Editor.
- *Source Editor* — Open the file in the CloudCannon Source Editor.
- *View diff* — Review unsaved changes for a file in text format, with deleted content highlighted in red and new content highlighted in green.
- *Discard unsaved changes* — Discard all unsaved changes to a file.

![A screenshot of the Save Changes modal shows unsaved changes from multiple people and an open Context Menu with file actions.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Dashboard-Save-Changes-Modal-New-Config-Context-Menu.webp)

At the top left of each file Card is a checkbox, which controls whether the *Save* button will save changes to that file back to your Git repository. If you don't want to affect a particular file, you can untick the checkbox.

Click the *Save selected* button. CloudCannon will commit the changes to the selected files to your Git repository.

> We recommend saving the changes to your Site often, as this keeps your Git repository up to date.

And that's it! Your *Site* is all set up for WYSIWYG editing. In the next step of this guide, we'll direct you to resources for further configuration or user guides on how to edit your files in CloudCannon.


---

---
title: Introduction
description: Learn how to connect Hugo Modules to your CloudCannon site.
url: https://cloudcannon.com/documentation/developer-guides/hugo-modules/
content_type: developer guide
last_modified: 2026-04-16
---

Welcome to the [Hugo Modules](https://gohugo.io/hugo-modules/) guide. If you want to use themes and components from other repositories on your site, you are in the right place! To configure CloudCannon so that your Hugo modules install correctly, you must customize how CloudCannon loads your modules into your build.

This guide assumes you already have a Hugo site on CloudCannon and are using GitHub as your module repository.

Hugo Modules can use public or private repositories.

For a public repository, you won't require any configuration in CloudCannon to build successfully. However, you might want to improve your experience by using CloudCannon's [Site Mounting](/documentation/developer-articles/what-is-site-mounting/) feature. With Site Mounting, a new build of your site is triggered every time the Hugo Module is updated.

For a private repository, you must give CloudCannon permission to access the repository at build time. There are two approaches for connecting a private repository.

If you have a simple module setup, such as a theme module containing layouts and components, you can emulate Hugo Modules using [Site Mounting](/documentation/developer-articles/what-is-site-mounting/) instead. With Site Mounting, your sites can benefit from CloudCannon's authenticated connection with your git provider, and you can trigger a build of your site every time the Hugo module is updated.

If you have a more complex setup, such as if your module has nested modules, replicating this with Site Mounting can become more difficult. In this case, we recommend using a GitHub access token to give your build permission to download your modules.

This guide will cover how to set up your site using Site Mounting in CloudCannon or a GitHub access token.


---

---
title: Emulate Hugo Modules with Site Mounting
description: Learn how to use CloudCannon's Site Mounting feature to emulate Hugo Modules.
url: https://cloudcannon.com/documentation/developer-guides/hugo-modules/modules-with-site-mounting/
content_type: developer guide
last_modified: 2026-04-16
---

With CloudCannon's [Site Mounting](/documentation/developer-articles/what-is-site-mounting/) feature, you can make one site dependent on one or more other CloudCannon sites. Files from a remote site are accessible to the local site at build time. For Hugo sites, you can use Site Mounting to emulate [Hugo Modules](https://gohugo.io/hugo-modules/).

Site Mounting may be preferable to Hugo Modules, especially if your site would benefit from the ability to:

- Trigger an automatic build whenever your modules are updated.
- Access your private module repository without the need to generate an authentication token.

In Site Mounting, CloudCannon refers to the donor site as the *Remote Site* and the site that receives files as the *Local Site*. In this example, the remote site will contain your modules. The local site is your main site.

> This setup requires that you own your site repository and the repositories for your modules. These repositories should be in the same GitHub organization. If you use a public repository owned by someone else, you must fork it into your GitHub organization.

## Disable the default Hugo Module import

To emulate Hugo Modules with Site Mounting, you must disable the default Hugo Module behavior in CloudCannon. The simplest method of disabling this behavior is to create a second Hugo configuration file for use in CloudCannon, which does not contain your module import.

Your configuration file will look something like this:

File: `hugo.cloudcannon.toml`

```toml
baseURL = 'https://example.com/'

# ... all other config

# module.imports commented out or removed
# [[module.imports]]
# path = 'github.com/my/module'

```

> If your site uses a [configuration directory](https://gohugo.io/getting-started/configuration/) for Hugo, another option is to add a `cloudcannon` environment.

## Turn your Hugo Module repository into a CloudCannon site

Site Mounting works between two CloudCannon sites. Add a new site to your CloudCannon account and connect it to your module repository.

The build settings for this site do not matter, as we will only mount the source files to our local site.

On the *Build Site* page, select Static from the SSG dropdown menu. This will allow your build to succeed without configuring a build command.

![A screenshot of the Build Site page with the SSG Static selected from the dropdown menu.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Build-Site-Static.webp)

By default, these files are accessible on this site's [Testing Domain](/documentation/user-articles/what-is-a-testing-domain/). To prevent access to the testing domain, switch the module site to [password authentication](/documentation/developer-articles/enable-password-authentication/) and do not set a password.

## Mount the module site to your main site

Open your main site in CloudCannon. To configure your Site Mounting settings, navigate to the *Site Mountings* page under *Site Settings*, then *Builds*.

![A screenshot of the CloudCannon app shows the Site Mountings page, with a section to add a mounted site to the local site.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Site-Mountings.webp)

In the *Remote site* field, select the CloudCannon site that contains your module files.

Leave the *Remote artifact* field set to "Source files".

Enter the paths you want your module to mount for your *Remote* and *Local paths*. For example, given the following Hugo configuration:

File: `module/config.yml`

```yaml
module:
  mounts:
    - source: theme/layouts
      target: layouts
```

If your module configuration were the code above, you would enter "theme/layouts" into the *Remote path* field and "layouts" in the *Local path* field.

Once you have completed your configuration, click the *Mount site* button.

## New build of your main site

In your main site on CloudCannon, navigate to the *Status* page. Click the *Rebuild* button. CloudCannon will mount the module content at the your specified path before running your Hugo build command.

Any changes to your module repository will trigger a new build of any site to which the content is mounted. You don't have to worry about keeping your sites up to date.

## Mounting multiple paths

In some cases, you may want to mount your module to multiple paths. For example, given the following Hugo configuration:

File: `module/config.yml`

```yaml
module:
  mounts:
    - source: layouts
      target: layouts
    - source: assets
      target: assets
```

In CloudCannon, you can mount the same remote site multiple times at different paths. Repeat the above steps and specify a different *Remote* and *Local path* to mount it again.

If the paths you want to mount are more complicated or there are many paths, you can mount the entire module to a temporary location and use [CloudCannon's Build Hooks](https://cloudcannon.com/documentation/developer-articles/extending-your-build-process-with-hooks/) to move your module files to the correct location.


---

---
title: Access private modules with an access token
description: Learn how to use GitHub's access tokens to authenticate a private Hugo Modules repository.
url: https://cloudcannon.com/documentation/developer-guides/hugo-modules/modules-with-access-token/
content_type: developer guide
last_modified: 2026-04-16
---

Some Hugo Modules won't be a good fit for [Site Mounting](/documentation/developer-articles/what-is-site-mounting/), particularly if they belong to a different organization in GitHub, or require a complex setup. In this case, we can configure your CloudCannon site to install private Hugo Modules.

Let's enable Hugo Modules with GitHub's access token feature, CloudCannon's environment variables, and [CloudCannon's Build Hooks](https://cloudcannon.com/documentation/developer-articles/extending-your-build-process-with-hooks/) feature.

## Create a GitHub access token

Open GitHub and navigate to your [Fine-grained tokens settings](https://github.com/settings/tokens?type=beta). Click *Generate new token.*

When creating a token, you must select a name, expiry date, and which GitHub organization or user owns the private repository. Under *Repository access*, enable the *Only Select Repositories* option, and select the private repository that contains your Hugo Modules. In the *Repository permissions* field, set *Contents* to "Access: Read-only".

Click the *Generate token* button and copy the token to your clipboard.

## Add the token to CloudCannon

Open your site in CloudCannon and navigate to your *Configuration* under *Site Settings*, then *Builds*. Click on the *Command Line Options* card to expand it.

![A screenshot of the Build Configuration page shows the CLI field to add a GH_TOKEN environment variable.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Build-Configuration-Environment-Variable-GHTOKEN.webp)

Add an environment variable to your site using the key "GH_TOKEN". Paste the GitHub token you generated into the value field. Click the *Update Configuration* button.

## Configure git to use your access token

Next, configure your git command to use this token when downloading your Hugo Modules using [CloudCannon's Build Hooks](https://cloudcannon.com/documentation/developer-articles/extending-your-build-process-with-hooks/).

Create a file inside a .cloudcannon folder in the root of your repository. Name this file "preinstall" and add the following:

File: `.cloudcannon/preinstall`

```bash
git config --global url."https://${GH_TOKEN}:x-oauth-basic@github.com".insteadOf "https://github.com"
```

Do not paste your access token here. Leave the text as `${GH_TOKEN}`.

CloudCannon will use the token from the environment variable set in the previous step. Git will use your access token whenever it interacts with https://github.com. Hugo will use this when downloading your modules.

Once you have committed this file to your repository, CloudCannon will trigger a new build of your site and download your Hugo Modules.


---

---
title: Introduction
description: Learn how to configure SSO/SAML using Okta and CloudCannon.
url: https://cloudcannon.com/documentation/developer-guides/okta-sso-saml/
content_type: developer guide
last_modified: 2026-04-16
---

We know that configuring SSO/SAML can be difficult. Every provider uses different names, finding the right information can be confusing, and it often requires you to go back and forth between software. Don't worry! In this guide, we'll walk you through adding Okta SSO to your CloudCannon Organization.

[Okta](https://www.okta.com/) is a cloud-based identity and access management (IAM) service that allows you to manage how your team members access the software they need.

This guide assumes that:

- You want to use Okta as your SSO Identity Provider.
- You already have Okta and CloudCannon accounts.
- Your Organization is on our [Enterprise plan](/pricing/).
- You are a member of the Owner [Permission Group](/documentation/user-articles/what-are-permission-groups/) for your Organization.

## What is SSO/SAML?

People often use the acronyms SSO and SAML in conjunction. Single Sign-On (SSO) refers to the process that allows a user to access multiple applications with a single set of login credentials. Security Assertion Markup Language (SAML) is the protocol that facilitates SSO, enabling the secure exchange of user information between the Identity Provider and Service Provider applications.

Here are a few terms you should know:

- **User** — The team member who wants to access CloudCannon.
- **Identity Provider** — The software that authenticates the user's identity, in this case, Okta. Members of your Organization must have a login for this software.
- **Service Provider** — The application a user wants to log in to (i.e., CloudCannon).

CloudCannon supports SSO for Organizations on our Enterprise plan. With Okta SSO enabled, your team members will provide their Okta login details rather than logging in to CloudCannon directly. Additionally, your team members do not need to enter their CloudCannon password while logged in to Okta.

After configuring SSO/SAML, CloudCannon will create a custom landing page for your Organization. Team members can click a button, and CloudCannon will confirm their identity with Okta or redirect them to the Okta login page.

## Why use SSO/SAML?

When you have a larger team, managing their access to various software can be tricky. SSO enables you to:

- Reduce the number of password resets due to forgotten passwords.
- Improve the user experience with seamless access to many applications.
- Revoke access in a single location and know you have removed access to multiple applications.

SSO is also required for some security and compliance policies, as it reduces password-related vulnerabilities and puts authentication in the hands of a single Identity Provider rather than many applications.

## How does SSO/SAML work?

The main points of confusion when setting up SSO/SAML between an Identity Provider (e.g., Okta) and a Service Provider (e.g., CloudCannon) are the conflicting terminology used by different software and the back-and-forth nature of the configuration process.

To make it easier, here's a list of the main concepts. In the later steps of this guide, we'll teach you how to find this information in Okta or CloudCannon.

There are three types of URLs we need for SSO configuration.

- **Entity ID** — This is the intended recipient for your SAML assertion: CloudCannon! CloudCannon publishes public information about its SAML configuration on this URL, including the public certificate. The URL must start with https://cloudcannon.com/. Entity ID is also known as the Audience URI, Service Provider Entity ID, or Issuer.
- **Single sign-on** **(SSO) URL** — The Service Provider (i.e., CloudCannon) address to which the Identity Provider (i.e., Okta) will redirect users after they enter their login details. SSO URL is also known as the Assertion Consumer Service URL, Reply URL, or Consume URL.
- **SAML 2.0 Endpoint (HTTP)** — The Okta URL to which CloudCannon will redirect users when they try to log in to CloudCannon.

Additionally, CloudCannon requires the following details to generate a SAML request.

- **Name ID Format** — This determines how the Identity Provider (Okta) identifies a user to the Service Provider (CloudCannon).
- **Authn Context** — This determines how the Service Provider (CloudCannon) expects the Identity Provider (Okta) to authenticate the user.
- **Signing Algorithm** — Select the SHA1 or SHA256 algorithm to encrypt your data. SHA1 uses a 160-bit long key to encrypt data, while SHA256 uses a 256-bit long key.
- **X.509 Certificate** — This determines the format, structure, and content of the public key certificate.

In general, the Single Sign-On process uses the following steps:

1. The user tries to log in to CloudCannon.
2. CloudCannon generates a SAML request.
3. The user's Internet browser redirects them to the SAML 2.0 Endpoint (i.e., Okta), where Okta parses the SAML request.
4. Okta authenticates the user by asking them to enter their Okta username and password. If the user is already logged in to Okta, then it skips this step.
5. The Identity Provider (Okta) generates a SAML response.
6. The user's Internet browser redirects them to the SSO URL (i.e., CloudCannon), where CloudCannon validates the SAML response.
7. If the verification is successful, CloudCannon logs the user in and gives them access to your Organization.

> If you need any assistance setting up SSO/SAML for you Organization, please reach out to our friendly [support team](/support/).

In the next step of this guide, we will cover where to find SSO configuration in CloudCannon and Okta and how to add CloudCannon to Okta as an app integration.


---

---
title: Add XML metadata to CloudCannon
description: Learn how to generate an XML file in Okta and add it to CloudCannon.
url: https://cloudcannon.com/documentation/developer-guides/okta-sso-saml/add-xml-metadata-to-cloudcannon/
content_type: developer guide
last_modified: 2026-04-16
---

In the previous step of this guide, we added CloudCannon as an app integration in Okta. Okta will use the information we provided to generate an XML metadata file with the SAML 2.0 details required by CloudCannon.

In Okta, navigate to the *Application* page for the CloudCannon app integration you created in the previous step of this guide.

Under *Metadata details*, you will find the *Metadata URL*. The *Metadata URL* on the *Single Sign-On* page should look like `https://example.okta.com/app/xxxxx/sso/saml/metadata`, except `example` will be your Okta username, and the `xxxxx` characters will be a unique string.

Click the *Copy* button under your *Metadata URL* and open this URL using another tab in your Internet browser.

![A screenshot of the CloudCannon app integration page on Okta.](/assets/external_screenshots/Okta-App-Sign-On.png)

The *Metadata URL* should show you something like this:

![A screenshot of the XML metadata file open in an Internet browser.](/assets/external_screenshots/Okta-XML-File.png)

This information is the contents of your XML metadata file. Right-click anywhere on the screen and select the *Save as...* option from your Internet browser menu. The name of this option may differ slightly from browser to browser.

Your Internet browser will open your computer's File Browser and give you the option to name your XML file before you save it. We recommend "CloudCannon-Okta-metadata.xml" or something similar so you can easily find this file again.

Save the file to your computer.

In CloudCannon, navigate to the *Single Sign-On* page under *Org Settings*.

To set up SAML 2.0, CloudCannon needs the following details: *SAML 2.0 Endpoint (HTTP)*, *Entity ID (Issuer)*, *Name ID Format*, *Authn Context*, *Signing Algorithm*, and *X.509 Certificate*.

> If you need a reminder on these terms, check out the first page of this guide.

CloudCannon can use the XML metadata file generated by Okta to populate the majority of these fields.

Click the *Fill form using XML Metadata* button, and select the XML metadata file we just downloaded using your computer's File Browser. CloudCannon will update most of the text fields on the *Single Sign-On* page using the contents of this file.

![A screenshot of the CloudCannon Single Sign-On page under Org Settings.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Single-Sign-On.webp)

You may want to customize two fields on the *Single Sign-On* page: *Initial Permission Group* and *Signing Algorithm*.

The *Initial Permission Group* dropdown lists all the [Permission Groups](/documentation/user-articles/what-are-permission-groups/) configured for your Organization. This field controls which Permission Group CloudCannon should add a new user to if they have not logged in to your Organization before. By default, CloudCannon uses the Editors [Default Permission Group](/documentation/user-articles/what-are-default-permission-groups/). We recommend choosing a Permission Group with fewer permissions and moving specific members to a different group if they require more permissions.

The *Signing Algorithm* dropdown has two options: SHA256 and SHA1. By default, CloudCannon uses the SHA256 signing algorithm to encrypt your data. We recommend using the default algorithm unless you know your workflow requires SHA1.

Scroll to the bottom of the page and click *Add Single Sign-On*.

You have successfully configured SSO/SAML with Okta and CloudCannon!

You can share your *Login URL* with your team. To see your login page, click the *View SAML Landing Page* button. Your *Login URL* is at the top of the *Single Sign-On* page under *Org Settings*. It should look like https://app.cloudcannon.com/saml/xxxxx/init, except the x characters will be your unique Organization ID.

CloudCannon will redirect users to your Okta landing page each time they attempt to log in to your Organization.

![A screenshot of the CloudCannon Single Sign-On page under Org Settings.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Single-Sign-On-Complete-Form.webp)

Please refer to the [Okta documentation](https://help.okta.com/en-us/content/index.htm) for assistance managing your Identity Provider.

In the next step of this guide (optional), we will cover managing your SSO settings in CloudCannon. If you need further assistance, our friendly [support team](/support/) is always available to help.


---

---
title: Create an Okta App Integration
description: Learn how to add CloudCannon to Okta as an app integration.
url: https://cloudcannon.com/documentation/developer-guides/okta-sso-saml/create-an-okta-app-integration/
content_type: developer guide
last_modified: 2026-04-16
---

On CloudCannon, navigate to the *Single Sign-On* page under *Org Settings*. We'll need details from this page later, so for now, we'll just leave it open in a tab.

![A screenshot of the CloudCannon Single Sign-On page under Org Settings.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Single-Sign-On.webp)

On Okta, "App Integrations" are configured connections between Okta and external applications that provide a service — in this case, CloudCannon. Once you add CloudCannon as an App Integration, Okta will generate the XML certificate CloudCannon needs for its SAML request.

Open [Okta](https://www.okta.com/) in another tab. Log in and navigate to the *Applications* page under *Applications* in the sidebar.

Click the *Create App Integration* button. Okta will open the *Create a new app integration* modal.

![A screenshot of the Okta Applications page shows the Create App Integration button.](/assets/external_screenshots/Okta-Applications-Page.png)

Under *Sign-in method*, select the *SAML 2.0* option and click the *Next* button. Okta will open the *Create SAML Integration* page.

![A screenshot of the Okta Applications page shows the Create a new app integration modal.](/assets/external_screenshots/Okta-Create-SAML-Sign-In-Method.png)

The first tab on the *Create SAML Integration* page is *General Settings*.

Enter "CloudCannon" in the *App name* text field. You also have the option to upload the [CloudCannon Logo](https://cc-dam.imgix.net/documentation/images/icons/CloudCannon-Logo-Blue.svg). Adding a logo can help you find the CloudCannon app integration in your list of integrations.

Click the *Next* button. Okta will open the *Configure SAML* tab.

![A screenshot of the General Settings tab on the Create SAML Integration page shows fields for app name and logo.](/assets/external_screenshots/Okta-Create-SAML-General-Settings.png)

To set up SAML 2.0, Okta needs the following details from CloudCannon:

- The *Single sign-on URL*, which CloudCannon calls the *SSO URL*.
- The *Audience URI (SP Entity ID)*, which CloudCannon calls the *Entity ID (Issuer)*.

We can copy these details from the *Single Sign-On* page.

![A screenshot of the CloudCannon Single Sign-On page under Org Settings.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Single-Sign-On.webp)

The *SSO URL* on the *Single Sign-On* page should look like `https://app.cloudcannon.com/saml/xxxxx/consume`, except the `x` characters will be your CloudCannon Organization ID. Copy the *SSO URL* from CloudCannon into Okta's *Single sign-on URL* text field. Leave the *Use this for Recipient URL and Destination URL* checkbox ticked.

The Service Provider is CloudCannon, so the Entity ID must always begin with `https://cloudcannon.com/`. If you have multiple SAML connections, you can add a suffix to the *Entity ID (Issuer)*, but you don't need one for most uses. Enter `https://cloudcannon.com/`, followed by the optional suffix, in the *Audience URI (SP Entity ID)* text field.

Finally, we need to select the *Name ID format*, which Okta will use to generate the *Name ID Format* string for CloudCannon. Select the *EmailAddress* option from the *Name ID format* dropdown in Okta.

The rest of the fields on the *Configure SAML* tab are not required for basic SSO/SAML, but you can fill them in now if you need them for your workflow.

Click the *Next* button. Okta will open the *Feedback* tab.

![A screenshot of the General Settings tab on the Create SAML Integration page shows fields for the SSO URL and Entity ID.](/assets/external_screenshots/Okta-Create-SAML-Configure-SAML.png)

We don't need to add any details on the *Feedback* tab, as Okta only uses this information to improve their service rather than to set up an app integration. Click the *Finish* button. Okta will generate an XML metadata file using the information we just provided.

In the next step of this guide, we will cover downloading the XML metadata from Okta and adding it to CloudCannon.


---

---
title: Manage your SSO settings
description: Learn how to manage your SSO settings in CloudCannon.
url: https://cloudcannon.com/documentation/developer-guides/okta-sso-saml/manage-your-sso-settings/
content_type: developer guide
last_modified: 2026-04-16
---

> This step of the guide is optional.

Once you have set up SSO, you can manage your Settings through the *Single Sign-On* page under *Org Settings*.

There are three tabs on the *Single Sign-On* page: *Details*, *Settings*, and *Danger Zone*.

The *Details* tab shows you all the details of your SSO configuration. These details might be important if you need to reconfigure your Identity Provider.

![A screenshot of the Details Tab on the Single Sign-On page shows the details of your SSO configuration.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Single-Sign-On-Details-Tab.webp)

The *Danger Zone* tab has the *Remove SAML Authentication* button. Click this button to remove SSO from your Organization.

If you change your Identity Provider, you will need to remove SSO from your Organization and re-add the details of your new SSO provider.

![A screenshot of the Danger Zone Tab on the Single Sign-On page shows the Remove SAML Authentication button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Single-Sign-On-Danger-Zone-Tab.webp)

The majority of your SSO settings are under the *Settings* tab.

![A screenshot of the Settings Tab on the Single Sign-On page shows the Require Single Sign-On (SSO) for your Organization checkbox.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Org-Settings-Single-Sign-On-Settings-Tab.webp)

You can edit the *Initial Permission Group*, *Authn Context*, *Signing Algorithm*, and *X.509* *Certificate* details here.

You can also require SSO for all team members in your Organization. The *Require Single Sign-On (SSO) for your Organization* checkbox allows you to prevent team members from accessing your Organization if they do not have SSO enabled. This setting allows you to ensure that all team members are following your security guidelines.

To give your team members time to enable SSO, you can also configure a date in the *Require SSO after a specific date* field. After that date, CloudCannon will require SSO to access your Organization.


---

---
title: Introduction
description: Learn about Rosey i18n and how to use it in CloudCannon
url: https://cloudcannon.com/documentation/developer-guides/rosey-migration-guide/
content_type: developer guide
last_modified: 2026-04-16
---

If you’re already using CloudCannon’s i18n feature, you might want to consider moving to Rosey. Rosey is an open-source tool developed by CloudCannon, which does the same job a bit better. In this guide, we’ll first discuss some of the advantages of using Rosey over CloudCannon’s built-in i18n functionality. Then, we’ll look at a step-by-step walkthough you can use to migrate your site.

## Advantages of Rosey

- Rosey is open-source, so if there’s something you don’t like you can create an issue on GitHub or submit a pull request to have it changed. The code is completely public if you want to check out what’s happening under the hood.
- Rosey is extremely performant and can handle large multilingual sites with a marginal impact to your total build time.
- Since Rosey is available as an NPM package, you can develop and test your translated site locally, instead of pushing to CloudCannon to build the site every time you make a change.
- Rosey has a nicer file format than CloudCannon’s i18n, but is also completely backwards-compatible.
- Rosey has a much wider feature set, including:
  
  - A `--wrap` flag, which can ensure that languages with no spaces are appropriately wordwrapped for better readability and accessibility.
  - Tooling to easily check which parts of the site haven’t been translated, or where the translations have become outdated from the original text.
  - Support for translating images, JSON, and HTML attributes like img alt tags and meta descriptions.

## Caveats

One consideration when integrating Rosey with CloudCannon is that it can interfere with the Visual Editor. The Visual Editor needs to know where your site's output files are, and in the workflow described in this guide Rosey moves those files around. For this reason, we recommend using Rosey **only** in conjunction with a staging workflow.

You can read more about the advantages of a staging workflow, and how to set it up in CloudCannon, [in our Staging Workflow Guide](/documentation/developer-guides/staging-workflow-guide/).

> The final step of this guide assumes that you are using a workflow with separate staging and production branches.


---

---
title: Using Rosey on CloudCannon
description: Build a translated site with Rosey on CloudCannon
url: https://cloudcannon.com/documentation/developer-guides/rosey-migration-guide/using-rosey-on-cloudcannon/
content_type: developer guide
last_modified: 2026-04-16
---

Now that you can build your translated site with Rosey locally, we want to get the same build process working on CloudCannon. We'll add a postbuild step using [build hooks](/documentation/developer-articles/extending-your-build-process-with-hooks/).

Recall that using Rosey in our postbuild can cause issues for the Visual Editor. To get around this, we'll only run Rosey on our production site. This works because we don't want to directly edit the production site anyway, and we may not need to see all the translated content on the staging site where we're editing. If you do need to preview translations on your site before they go live, you can create another site connected to the `staging` branch which also runs the postbuild!

Add a `.cloudcannon/postbuild` script to run Rosey after every build on CloudCannon. We'll use an environment variable to tell our script whether to run Rosey or not.

File: `.cloudcannon/postbuild`

```sh
if [[ $TRANSLATE == "true" ]];
then
  echo "Installing Rosey"
  npm install

  echo "Translating site with Rosey"
  # There's a little bit of shuffling around here to ensure the translated site ends up where CloudCannon picks up your site
  mv ./_site ./_untranslated_site                  
  npx rosey@latest build --source _untranslated_site --dest _site
fi
```

It's best to explicitly specify which version of Rosey you want to run, to ensure your CloudCannon build matches your local development environment. Consider adding `rosey` as a dependency in your package.json.

On our production site, we'll add an environment variable `TRANSLATE` with the value `true`. You can do this in the **Command Line Options** menu in the *Configuration* section of your site settings.

Your site should be now translated on CloudCannon! 🎉 If you were previously using CloudCannon i18n, you can switch it off in your build settings.


---

---
title: Migrating to Rosey
description: Convert your translation setup to use Rosey.
url: https://cloudcannon.com/documentation/developer-guides/rosey-migration-guide/migrating-to-rosey/
content_type: developer guide
last_modified: 2026-04-16
---

If you’re starting from scratch, have a look at the [Rosey documentation](https://rosey.app) to get set up, then move on to the next step.

If your site is already setup for i18n on CloudCannon, migrating to Rosey is easy.

## Migrating your site

1. Initialize NPM on your site with `npm init` if you haven’t already
2. Install Rosey with `npm install rosey`
3. Rename your `_locales` directory to `rosey/locales` and convert each file to JSON.
4. Add a `rosey.yml` file with some basic configuration:

File: `rosey.yml`

```yml
source: "path/to/your/built/site" # e.g. _site
tag: "data-i18n" # the attribute you've tagged your translatable elements with
```

5. At this point, you can already start testing locally. Run `npx rosey build --serve` and see your translated site running on a local server.


---

---
title: Introduction
description: Learn about migrating to Unified Configuration and enabling live configuration and data editing in CloudCannon.
url: https://cloudcannon.com/documentation/developer-guides/unified-configuration-migration-guide/
content_type: developer guide
last_modified: 2026-04-16
---

Welcome to the Unified Configuration migration guide! If you want to enable live configuration and data editing or update your existing Site to the Unified Configuration file format, you are in the right place.

Before we start, this guide assumes that you have an existing Site on CloudCannon that does not use the Unified Configuration file format.

In this guide we'll cover:

- What is live configuration and data editing and how do you enable it for your existing Sites?
- What is Unified Configuration and why would you migrate your existing Site to this file format?
- How do you migrate your Site configuration to the Unified Configuration file format?

You may not need to complete every step in this guide but please carefully review each step to see if it is applicable to your Site's configuration.

## What is live configuration and data editing?

Before the October 2024 Live configuration and data editing release, CloudCannon relied on a successful build to show you any updates to your configuration and data files in the app UI. This meant you had to wait for a build to see updates to your collections in the *App Navigation*, inputs in your editing interfaces, the appearance of your files, and more.

The live configuration and data editing feature allows you to see your changes live when you update your CloudCannon configuration files and data files — without the need to build your Site.

This means you can:

- Populate inputs with new Collections files before saving the file.
- Update your Input, Structure, and Schema configuration, and see those changes the next time you open a file in an editing interface.
  
  - (Note: CloudCannon applies a Schema to a file when first opened during an editing session. You will not see live changes from an updated Schema if a file is already open with unsaved changes.)
- See changes quickly when you reconfigure the appearance of your file cards.

Live configuration and data editing provide a better editing experience for your team.

Live configuration and data editing are automatically included for new Sites created with the Unified Configuration file format. For Sites created before September 2024, this feature may not be enabled. We'll cover how to enable this feature for existing Sites in step two of this guide.

> Live configuration editing is unavailable for Sites using a JavaScript CloudCannon configuration file. Please switch to a YAML (recommended) or JSON format to access this feature.

## What is Unified Configuration?

The Unified Configuration file format simplifies Site setup. Sites created using a CloudCannon configuration file in the Unified Configuration file format require less information from you and use the same configuration options regardless of SSG. The Unified Configuration file format also enables you to manage your content in CloudCannon before your first build.

Unified Configuration also allows you to put your Site in Headless Mode, turning off builds and streamlining *Site Settings*. Headless Mode is ideal for Sites built and hosted externally or dynamic Sites that rely on server-side rendering.

These features mainly benefit new Sites (i.e., without a CloudCannon configuration file) and new CloudCannon customers. Additionally, you can benefit from live configuration and data editing on most existing Sites without migrating to the Unified Configuration file format. So why migrate your existing Sites?

If you have an existing Site on CloudCannon, migrating to Unified Configuration is optional, but there are some scenarios in which migration may benefit you.

### CloudCannon Documentation

The CloudCannon Documentation website prioritizes using the most up-to-date instructions and screenshots. If your Site does not use the Unified Configuration file format, some articles on the CloudCannon Documentation website may not match your experience in the app.

If you decide not to migrate to Unified Configuration and need assistance with your Site, our friendly [support team](/support/) is always available to help.

### Improved app loading times

The Unified Configuration file format improves the app's loading time for Sites. CloudCannon will open your Site faster when you click on a Site card on the *Sites* page or the *Sites* tab within a Project.

### Future copies of your Site

The Unified Configuration file format improves your experience when creating new Sites (i.e., not branching from an existing Site). This benefit is not relevant to most existing Sites on CloudCannon, unless you plan to create a new copy of your Site at any point in the future.

Perhaps you want to create a new Site using the file structure of your existing Site, or you maintain website templates for use on CloudCannon. Migrating to Unified Configuration will improve the onboarding experience for your new Site.

### Live configuration editing for Sites with a JavaScript configuration file

CloudCannon supports live configuration editing for Sites with YAML or JSON CloudCannon configuration files. If you want to benefit from this feature on your existing Site, you must switch to a YAML (recommended) or JSON CloudCannon configuration file.

Switching to a YAML or JSON CloudCannon configuration file is the first step of our Unified Configuration migration guide — it's up to you if you want to complete all the steps.

### Moving to Headless Mode

If you want to add dynamic elements to your Site, or decide to host it externally while still using CloudCannon as your primary CMS, you can enable Headless Mode to streamline the CloudCannon interface. Headless Mode is only available for Sites using Unified Configuration.

### Configuration maintenance

CloudCannon will suggest build configuration options for Sites using Unified Configuration, such as potential command line options or environment variable. These suggestions are based on your SSG choice and the content of your files and make it easier to maintain your build configuration.

Additionally, CloudCannon requires less information to build Sites using Unified Configuration. For example, you no longer need to specify build arguments for Sites using Eleventy, Hugo, or Jekyll. If you change your build arguments in the future, there is no risk that CloudCannon will use the incorrect ones.

### Future CloudCannon features

Going forward, CloudCannon will treat Sites that use the Unified Configuration file format as the default. Although we don't have any planned at the moment, future CloudCannon features may require your Site to use the Unified Configuration file format.


---

---
title: Other configuration
description: Learn how to migrate your existing Site to CloudCannon's Unified Configuration file format.
url: https://cloudcannon.com/documentation/developer-guides/unified-configuration-migration-guide/other-configuration/
content_type: developer guide
last_modified: 2026-04-16
---

> You may not need to complete every step in this guide but please carefully review each step to see if it is applicable to your Site's configuration.

## 1. Explicitly configure attributes for file content Editable Regions

CloudCannon no longer automatically applies Editable Regions to file content without an explicit attribute. Previously, CloudCannon would attempt to discover these regions automatically when it encountered a content variable as the only child of an element, for example:

File: `layout.html`

```HTML
<div>{{ content }}</div>
```

This markup detection was fragile in certain circumstances, and couldn't be explicitly toggled on or off.

For sites using Unified Configuration, CloudCannon will no longer discover these regions automatically. Instead, an explicit attribute now exists to add an Editable Region for the content of a file.

The below code shows how to configure the `data-cms-edit="content"` attribute to configure Editable Regions for your content:

File: `layout.html`

```HTML
<div data-cms-edit="content">{{ content }}</div>
```

## 2. Configure _snippets_imports

> This step of the migration guide is only relevant to Sites using Hugo or Jekyll as their SSG.

Add the `_snippets_imports` corresponding to your SSG:

File: `cloudcannon.config.yml`

```YAML

_snippets_imports:
  jekyll: true

```

File: `cloudcannon.config.yml`

```YAML

_snippets_imports:
  hugo:
    exclude:
      - hugo_instagram

```

## 3. Configure path.static

> This step of the migration guide is only relevant to Sites using Hugo as their SSG.

CloudCannon no longer uses build integrations to set `path.static` automatically. Please set the `path.static` key to `static`.

File: `cloudcannon.config.yml`

```YAML

paths:
  static: static
  uploads: static/uploads

```

> To configure `paths.uploads`, you must also have configured `paths.static` first.

## 4. Configure your Markdown engine

> This step of the migration guide is only relevant to Sites using Jekyll or Hugo as their SSG.

CloudCannon supports two Markdown engines: CommonMark and Kramdown. Because most SSGs use CommonMark, CloudCannon assumes you are using this engine by default in the Unified Configuration file format.

Jekyll is on of the few SSGs which use Kramdown by default. If your Site uses Kramdown, you must specify your Markdown engine in your CloudCannon configuration file.

File: `cloudcannon.config.yml`

```YAML

markdown:
  engine: kramdown
  options:
    treat_indentation_as_code: true
    table: true
    attributes: true

```

Previously CloudCannon used your SSG configuration and build to infer which `markdown.options` you would want. With Unified Configuration, this needs to be configured explicitly. Below is a list of suggestions about options that you might want to enable.

- For Hugo sites, check your Hugo config file
  
  - `xhtml` should match `markup.goldmark.renderer.xhtml`.
  - `breaks` should match `markup.goldmark.renderer.hardWraps`.
  - `table` should match `markup.goldmark.extensions.table`.
  - `strikethrough` should match `markup.goldmark.extensions.strikethrough`.
  - `treat_indentation_as_code` should be set to `true`
- For Jekyll sites
  
  - `breaks` should match `kramdown.hard_wrap` from your Jekyll config file
  - `treat_indentation_as_code` should be set to `true`
  - `table` should be set to `true`
  - `attributes` should be set to `true`

## 5. Defunct configuration options

CloudCannon no longer uses some configuration options in the Unified Configuration file format. Although leaving these keys in your Site files will not harm your Site, they also will not function. If you want to maintain a clean configuration file, we recommend removing defunct configuration options.

We recommend deleting the following keys:

1. `paths.data`
2. `paths.collections`
3. `paths.layouts`
4. `paths.includes`


---

---
title: Live Configuration and Data Editing
description: Learn how to enable live configuration and data editing for existing Sites on CloudCannon.
url: https://cloudcannon.com/documentation/developer-guides/unified-configuration-migration-guide/live-configuration-and-data-editing/
content_type: developer guide
last_modified: 2026-04-16
---

You can enable live configuration and data editing on your existing Sites without completing a full migration to Unified Configuration.

To enable live configuration and data editing:

1. Navigate to the *Flags* page under *Site Settings*.
2. Check the *Step 1: Enable live config and data reloading* flag under *Upgrade to Unified Configuration*.
3. Click the *Update* button.

CloudCannon will now load changes to your data and configuration files, including your Inputs, Structures, and Schemas, without the need to save and build your Site.

![A screenshot of the Flags page shows configuration options including the Unified Configuration checkbox.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Flags-Page.webp)

## Why is this feature behind a flag?

CloudCannon resolves live updates to your configuration and data editing on-demand and merges these updates with data from your latest successful build. For example, let's assume you edit a single input in your CloudCannon configuration file. Opening that data file in the Data Editor will show you inputs from various sources: one resolved by CloudCannon in the interface following your update and the rest from your last successful build.

For this reason, you may see issues in CloudCannon if:

- You modify your CloudCannon configuration file or the front matter of your content files during your build.
- Your SSG generates or modifies data during your build.

In these cases, applying your configuration and data changes on-demand may override the modified values from your last successful build. This behavior could impact:

- How CloudCannon displays file cards in your collection browser.
- How Select and Multiselect inputs connected to a collection or data set display labels and save values.
- Any configuration modified in a way that CloudCannon could not merge.

Although we do not expect this issue to affect many existing Sites, we have made this feature opt-in out of an abundance of caution.


---

---
title: Data configuration
description: Learn how to migrate your existing Site to CloudCannon's Unified Configuration file format.
url: https://cloudcannon.com/documentation/developer-guides/unified-configuration-migration-guide/data-configuration/
content_type: developer guide
last_modified: 2026-04-16
---

> You may not need to complete every step in this guide but please carefully review each step to see if it is applicable to your Site's configuration.

## 1. Update the format of your data sets

> This step of the migration guide is only relevant to Sites using Eleventy, Hugo, or Jekyll as their SSG.

CloudCannon no longer exclusively reads data sets at build time. You must update your data configuration to allow CloudCannon to read your data sets at any time.

CloudCannon no longer uses the following data configurations:

File: `cloudcannon.config.yml`

```YAML

data_config: true

```

File: `cloudcannon.config.yml`

```YAML

data_config:
  locations: true

```

File: `cloudcannon.config.yml`

```YAML

data_config:
  locations:
    path: data/locations.yml
    parser: yaml

```

Please update `data_config` to:

File: `cloudcannon.config.yml`

```YAML

data_config:
  locations:
    path: data/locations.yml

```

## 2. Defunct configuration options

CloudCannon no longer uses some configuration options in the Unified Configuration file format. Although leaving these keys in your Site files will not harm your Site, they also will not function. If you want to maintain a clean configuration file, we recommend removing defunct configuration options.

We recommend deleting the following keys:

1. `data_config.*.parser`


---

---
title: Migration preparation and global configuration
description: Learn how to migrate your existing Site to CloudCannon's Unified Configuration file format.
url: https://cloudcannon.com/documentation/developer-guides/unified-configuration-migration-guide/migration-preparation-and-global-configuration/
content_type: developer guide
last_modified: 2026-04-16
---

> Migrating your existing Site is optional. You can use CloudCannon's [live configuration and data editing feature](/documentation/developer-guides/unified-configuration-migration-guide/live-configuration-and-data-editing/) without migrating your Site.

## Migration preparation

We recommend creating a new branch of your Site for this migration to avoid misconfiguration affecting your live Site.

To enable Unified Configuration:

1. Navigate to the *Flags* page under *Site Settings*.
2. Check the *Step 2: Use Unified Configuration* flag under *Upgrade to Unified Configuration*.
3. Click the *Update* button.

CloudCannon now expects your Site to use the Unified Configuration file format.

![A screenshot of the Flags page shows configuration options including the Unified Configuration checkbox.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Flags-Page.webp)

> Checking the *Use Unified Configuration* flag will automatically enable the *Enable live configuration and data reloading* flag.

In the short term, depending on how closely your Site configuration matches the Unified Configuration format, your Site may become misconfigured in CloudCannon. Misconfiguration could look like incorrect collection appearance or nonfunctional data sets in Select and Multiselect inputs. You will resolve this temporary state once you complete this migration guide.

One source of misconfiguration is opening your CloudCannon configuration file in the configuration GUI. As CloudCannon expects your configuration file to be in the Unified Configuration format, opening the file in the configuration GUI will strip content from your file (e.g., defunct keys). We highly recommend completing your migration in CloudCannon's Source Editor or your local development environment without using the configuration GUI.

## Global configuration

> You may not need to complete every step in this guide but please carefully review each step to see if it is applicable to your Site's configuration.

### 1. CloudCannon configuration file type

Your CloudCannon configuration file must be a YAML (recommended) or JSON file rather than JavaScript.

### 2. Explicitly configure source

> This step of the migration guide is only relevant to Sites using Eleventy, Hugo, or Jekyll as their SSG.

CloudCannon no longer detects your source folder at build time. Ensure the `source` key is configured in your CloudCannon configuration file, especially if your Site files are in a subfolder within your repository.

### 3. Update your initial Site settings file

If your Site uses an [initial Site settings file](/documentation/developer-articles/configure-your-initial-site-settings/), you must update the format of the file to use the `build` key instead of the `build_configuration` key. We have also added new configuration options such as `mode` and `manually_configure_urls`.

The below code shows an example `initial-site-settings.json` file:

File: `/.cloudcannon/initial-site-settings.json`

```JSON

{
  "ssg": "hugo",
  "mode": "hosted",
  "build": {
    "install_command": "[ -f package.json ] && npm i",
    "build_command": "hugo -b /",
    "output_path": "public",
    "environment_variables": [
      {
        "key": "HUGO_CACHEDIR",
        "value": "/usr/local/__site/src/.hugo_cache/"
      }
    ],
    "preserved_paths": "resources/,.hugo_cache/",
    "preserve_output": false,
    "include_git": false,
    "manually_configure_urls": false,
    "hugo_version": "0.128.1",
    "ruby_version": "2.7.3",
    "node_version": "18",
    "deno_version": "1.40.2"
  }
}

```

### 4. Add read permissions for your CloudCannon configuration file

If you use [Custom Permission Groups](/documentation/developer-articles/what-are-custom-permission-groups/), you must add the generic permission `site:files:read`, or a file glob to allow read permissions for your CloudCannon configuration file to any Permission Group that needs to see the Collections in your *Site Navigation*.

For more information about adding permissions to a Permission Group, please read our documentation on [editing Custom Permission Groups](/documentation/developer-articles/edit-a-custom-permission-group/).


---

---
title: Input configuration
description: Learn how to migrate your existing Site to CloudCannon's Unified Configuration file format.
url: https://cloudcannon.com/documentation/developer-guides/unified-configuration-migration-guide/input-configuration/
content_type: developer guide
last_modified: 2026-04-16
---

> You may not need to complete every step in this guide but please carefully review each step to see if it is applicable to your Site's configuration.

## 1. Define the values for Select input value_key

Before Unified Configuration, CloudCannon could use build data to populate the [Select and Multiselect input](/documentation/user-articles/what-is-a-select-input/#options) option `value_key` values. As a successful build is no longer required to edit your files, you must define all values for the `value_key` option in the configuration cascade rather than use values generated by a build integration.

For example, `value_key: path` and `value_key: url` will continue to work, however Hugo's `value_key: content_path` and Jekyll's `value_key: id` will not work as CloudCannon generates these values during build time and Unified Configuration Sites no longer use information from build integrations.

> For Jekyll Sites, if you have not configured `value_key`, it is likely set to `id` by default.

## 2. Configure _inputs for Jekyll tags and collections

> This step of the migration guide is only relevant to Sites using Jekyll as their SSG.

CloudCannon no longer uses naming conventions and build integrations to create inputs for tags and collections.

The below code shows how to configure the categories and tags inputs:

File: `cloudcannon.config.yml`

```YAML

_inputs:
     categories:
       type: multiselect
       options:
         values: collections.posts[*].categories
         allow_create: true
     tags:
       type: multiselect
       options:
         values: collections.posts[*].tags
         allow_create: true

```

## 3. Configure tabbed Object inputs

CloudCannon no longer automatically creates tabbed Object inputs. You can configure a tabbed Object input using the new `tabbed` value for the `subtype` key.

![A screenshot of top-level tabbed Object inputs.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Tabbed-Object-Input-First-Tab.webp)

The below code shows how to configure the `subtype` key for Object inputs:

File: `cloudcannon.config.yml`

```YAML

_inputs:
  example:
    type: object
    options:
      subtype: tabbed

```

If you want to configure tabs at the top-level of the Data Editor for multiple Object inputs, you can specify all Object inputs using the `$` key. The below code shows how to configure top-level tabs for the file `tabs.yml`.

File: `cloudcannon.config.yml`

```YAML

file_config:
  - glob: data/tabs.yml
    _inputs:
      $:
        type: object
        options:
          subtype: tabbed

```

## 4. Configure tabbed Structures

CloudCannon no longer automatically creates tabbed Object or Array inputs from Structures with two layers of nested keys under the `values.value` key. You can configure a tabbed Structure using the new `values.tabbed` key with a value of `true`.

The below code shows how to configure the `tabbed` key for Structures:

File: `cloudcannon.config.yml`

```YAML

_structures:
  components:
    values:
      - label: Component
        tabbed: true
        value:
          content:
            title:
            text:
          style:
            color:
            font:

```


---

---
title: Collection configuration
description: Learn how to migrate your existing Site to CloudCannon's Unified Configuration file format.
url: https://cloudcannon.com/documentation/developer-guides/unified-configuration-migration-guide/collection-configuration/
content_type: developer guide
last_modified: 2026-04-16
---

> You may not need to complete every step in this guide but please carefully review each step to see if it is applicable to your Site's configuration.

## 1. Explicitly configure a path for every collection

CloudCannon no longer detects collections during your build step.

Previously, CloudCannon could infer the path for each collection during the Site build step (e.g., Jekyll Sites automatically assume your posts collection is in the `_posts` folder). Additionally, some build integrations could discover collections at build time (e.g., posts, page, and drafts on Jekyll Sites). CloudCannon no longer uses this behavior.

Please ensure that each collection in `collections_config` has the `path` key defined. The below code shows how to configure a path explicitly:

File: `cloudcannon.config.yml`

```YAML

collections_config:
  blog:
    path: content/blog

```

## 2. Replace parse_branch_index with a glob

> This step of the migration guide is only relevant to Sites using Hugo as their SSG.

CloudCannon no longer uses `parse_branch_index: true` to add index files from one collection to a pages collection. Instead, you can define a file glob to exclude your index files from their initial collection.

Most Hugo sites will have a pages collection defined with a path of `content`. Pages excluded from any collections that are subdirectories will be assigned to this pages collection.

By default, all content files within a specific path are included in the associated collection, unless they also fall under a more specific path. CloudCannon now uses files globs to customize which files belong to a collection and are visible in the collection browser. You can add a negative glob to the `collections_config.*.glob` key by prefixing your file name with the `!` character.

The below code shows how to configure the `glob` key to exclude the `_index.md` file for your collection:

File: `cloudcannon.config.yml`

```YAML

collections_config:
  blog:
    path: content/blog
    glob:
      - '!_index.md'

```

The above example ensures that all files within the blog folder are included in the blog collection, with the exception of `_index.md`.

## 3. Replace collection filters with globs

CloudCannon no longer uses the `_unlisted` or `collections_config.*.filter` keys to filter which files to show in a collection browser. All collections now show only collection-like files that explicitly belong to a collection, as per the old `filter.base: strict` configuration (i.e., will not show collection-like files from a different collection that are stored at the same collection path).

CloudCannon now uses file globs to determine which files belong to a collection and are visible in the collection browser. A file glob is a pattern used to identify matching files. The `collections_config.*.glob` key is an Array. Each entry in the array is a pattern that controls which files are visible in CloudCannon's collection browser. The glob pattern is relative to your collection path and can include negative values by adding the `!` character as a prefix.

The below code shows how to configure the `glob` key for your collection:

File: `cloudcannon.config.yml`

```YAML

collections_config:
  blog:
    path: content/blog
    glob:
      - '!**/*.yml'

```

The above example ensures that all YAML files within the blog folder and all subfolders are not included in the blog collection.

## 4. Explicitly configure your data collection

> This step of the migration guide is only relevant to Sites using Eleventy, Hugo, or Jekyll as their SSG.

CloudCannon no longer uses build integrations to set the following keys in `collections_config.data`:

1. `disable_url`
2. `disable_file_actions`
3. `disable_add_folder`
4. `disable_add`

You must explicitly set these keys.

## 5. Configure collection groups

CloudCannon no longer groups collections in your *Site Navigation* by default. If you want to retain your original grouping, add the `collection_groups` key to your CloudCannon configuration file.

The below code shows how to configure the `collection_groups` key:

File: `cloudcannon.config.yml`

```YAML
```

collection_groups:
 - heading: Pages
   collections___1___:
     - pages
     # other output collections here
 - heading: Blogging
   collections:
     - posts
     - drafts
 - heading: Data
   collections___2___:
     - data
     # other non-output collections here

```

**[1]** Add output collections here.

**[2]** Add non-output collections here.
```

## 6. Filter _defaults.md with a glob or schema

If you still use the deprecated  `_defaults.md` file, CloudCannon will no longer filter this file from your collection by default. Please replace these files with the Schema feature, or use a collection glob (i.e., `collections_config.*.glob`) to filter the `_defaults.md` file from your collection browser.

## 7. Defunct configuration options

CloudCannon no longer uses some configuration options in the Unified Configuration file format. Although leaving these keys in your Site files will not harm your Site, they also will not function. If you want to maintain a clean configuration file, we recommend removing defunct configuration options.

We recommend updating the following keys to their new counterparts:

1. `collections_config.*.singular_key`

Please use `_inputs.*.options.values` rather than relying on naming conventions.

2. `collections_config.*.output`

Collections now default to being output if CloudCannon can determine an output URL. If you need to configure `output: false`, please use the `collections_config.*.disable_url` key set to `true`.

We recommend deleting the following keys:

1. `collections_config.*.parser`
2. `collections_config_override`


---

---
title: Build configuration and conclusion
description: Learn how to reconfigure your build commands following a migration to the Unified Configuration file format.
url: https://cloudcannon.com/documentation/developer-guides/unified-configuration-migration-guide/build-configuration-and-conclusion/
content_type: developer guide
last_modified: 2026-04-16
---

Once you have completed the migration checklist, open your Site in CloudCannon and review your configuration. Once you are happy with your changes, you can merge your branch with your main Site branch.

Open your main Site in CloudCannon and check the *Step 2: Use Unified Configuration* flag in your *Site Settings*.

## Build configuration

CloudCannon uses a different build configuration for Sites with the Unified Configuration file format. We recommend reviewing your build configuration to familiarize yourself with the new page layout and see if you can simplify your build commands.

For Eleventy, Hugo, and Jekyll Sites, checking the *Use Unified Configuration* flag in your *Site Settings* will clear all your build commands. For these SSGs, reconfiguring your build commands is essential.

To configure your Site builds:

1. Navigate to the *Build configuration* page under *Site Settings*.
2. Under *Command line options*, enter your *Install Command*, *Build Command*, and *Output Path*. You can click on CloudCannon's suggested values to use them in your configuration.
3. Click the *Update Configuration and Build* button.

> CloudCannon will suggest command line options based on your SSG and the contents of your Site files.

![A screenshot of the Build Configuration page shows blue boxes containing CloudCannon's suggestions for your command line options.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Build-Configuration-Command-Line-Options.webp)

Finally, build your Site to remove any existing build integration output from previous builds. If you updated your build commands, CloudCannon will automatically trigger a build for you.

> Even if you are planning to switch to [Headless Mode](/documentation/developer-articles/what-is-headless-mode/), we recommend completing a final build before you switch.

## URL configuration

For Eleventy, Hugo, and Jekyll Sites, CloudCannon discovers URLs through a different mechanism when building with Unified Configuration.

Previously, CloudCannon would read output URLs from your SSG at build time. Using Unified Configuration, CloudCannon now determines output URLs using heuristics after building your Site.

This won't affect most Sites, however CloudCannon may fail to auto-detect the correct URLs. We recommend checking that the URLs displayed in CloudCannon are correct.

CloudCannon uses URLs when copying the output path of a collection item and when opening the Visual Editor for a file. If you experience any issues with these actions, we recommend [configuring explicit URLs for your collections](/documentation/developer-articles/configure-your-collections/#url).

## Migration conclusion

You have migrated your Site to the Unified Configuration file format!

If you have any questions about this migration guide or need assistance, please contact our friendly [support team](/support/). We're always here to help.


---

---
title: Introduction
description: Learn how to set up Google Authentication for your CloudCannon Sites.
url: https://cloudcannon.com/documentation/developer-guides/google-saml-site-authentication/
content_type: developer guide
last_modified: 2026-04-16
---

At CloudCannon, we use Google Workspace (formerly G Suite) to manage our emails and calendars, as well as collaborate and share files through services like Google Drive. When new team members join, they receive access to our internal documentation and staging websites, hosted through CloudCannon.

These sites are secured with SAML authentication through Google, ensuring only authorized CloudCannon members can access them. When someone on our team leaves (😭), disabling their Google Workspace account automatically revokes their access to the internal websites.

You can use the same setup for your Site!

## What is SAML authentication?

SAML authentication is an excellent way to limit access to your website content to members of your team. SAML (or Security Assertion Markup Language) authentication requires visitors to your Site to log in with a third-party Single Sign-On ([SSO](/documentation/developer-articles/what-is-sso-saml/)) account.

SAML authentication works by allowing CloudCannon to authenticate a user's identity with an Identity Provider software (in this case, Google Workspace) when they try to log in to your website.

Here are some terms you will need to know:

- **User** — The person who wants to access the content on your website.
- **Identity Provider** — The cloud software that will authenticate the user’s identity, in this case Google Workspace. Users must already have a login for this software.
- **Service Provider** — The cloud application a user wants to log in to, in this case your CloudCannon-hosted website.

> CloudCannon also supports SAML authentication for CloudCannon app access. This feature is available on our [Enterprise plan](/pricing/). If this is what you're looking for, please read our documentation on [SSO/SAML](/documentation/developer-articles/what-is-sso-saml/) or reach out to our friendly [support team](/support/).

To configure SAML authentication for your Site, you will need to generate a certificate through Google Workspace.

In this guide, we'll teach you how to create a SAML App in Google Admin Console and configure SAML authentication for a Site hosted through CloudCannon. As a bonus, we'll also teach you how to create authenticated routes if you want some parts of your website to remain publicly available while others require authentication.

This guide assumes you already have a Site hosted on CloudCannon.


---

---
title: Configure SAML authenticated routes
description: Configure authenticated routes to only require authentication on some parts of your website.
url: https://cloudcannon.com/documentation/developer-guides/google-saml-site-authentication/configure-saml-authenticated-routes/
content_type: developer guide
last_modified: 2026-04-16
---

> This step is optional!

If you want some parts of your website to require authentication and other parts to be publicly accessible, CloudCannon allows you to configure authenticated routes. You can control which pages, or groups of pages require authentication.

As we have already set our authentication method to SAML in the previous section of this guide, all the authenticated routes you configure will require visitors to sign in with their Google Workspace credentials.

## Create a list of paths that require authentication

You can specify which URLs on your Site require authentication using the URL path. URL paths are made up of zero or more subdirectories and the slug for the current web page. You can use the wildcard `*` character to specify any number of pages or subdirectories.

![A diagram of a URL shows labels for protocol, subdomain, domain, top-level domain, subdirectory, slug, and path.](assets/diagrams/CloudCannon-Documentation-URL-Structure-Diagram.png)

For this guide, we want to configure authentication for every page in the "Staff" section of our website, and the "Internal Announcements" page. The URLs for these pages are `https://example.com/staff/*` and `https://example.com/internal-announcements.html`.

We only need the path information to create authenticated routes, so we can remove the domain name from the URLs to leave the following:

- `/staff/*`
- `/internal-announcements.html`

Which paths require authentication on your Site? Create a list.

## Configure authenticated routes

In CloudCannon, you can specify authenticated routes in the `auth-routes.txt` file. This file should be in the root directory of your output Site. Where this is in your Site repository will depend on your SSG (e.g., the root of the repository for Jekyll, the static folder for Hugo, etc.).

1. Log in to [CloudCannon](https://app.cloudcannon.com/) and open your Site.
2. Navigate to the root directory of your output Site using the *File browser*.
3. Create a file called `auth-routes.txt`.
4. For each URL you want to authenticate, add the path on a new line of the file.
5. Save the file to your Site.

CloudCannon will now require authentication on the routes specified in the `auth-routes.txt` file.

Here is an example of a basic authenticated routes file:

File: `auth-routes.txt`

```

/staff/*
/internal-announcements.html

```


---

---
title: Create a Google Workspace SAML App
description: Create a custom SAML App in your Google Admin Portal to handle authentication requests from your website.
url: https://cloudcannon.com/documentation/developer-guides/google-saml-site-authentication/create-a-google-workspace-saml-app/
content_type: developer guide
last_modified: 2026-04-16
---

Google Workspace allows you to create a dedicated SAML App to handle authentication. If you want to, you can follow [Google’s instructions](https://support.google.com/a/answer/6087519?hl=en) directly.

> You need to be signed in with a super administrator’s account to complete this section of the guide.

## Create a custom SAML app

1. Log in to the [Google Admin Portal](https://admin.google.com/) using your super administrator account.
2. Under the *Menu*, select *Apps* then *Web and mobile apps*.
3. Click *Add App* and select the *Add custom SAML app* option from the dropdown.
4. On the *App details* page, enter the name of your app. We recommend something memorable, like "[website name] SAML authentication".
5. Click *Continue*.
6. On the *Google Identity Provider details* page, download or copy the following information:
  
  - *IDP metadata*
  - *Certificate*
  - *SSO URL*
7. Click *Continue*.

For this guide, we want our users to be able to log in to our staging website: `staging.example.com`. Replace this example URL with the domain you want to authenticate.

![A screenshot of the Google Workspace Add Custom SAML App page shows the service provider details.](/assets/external_screenshots/CloudCannon-Documentation-Google-Custom-SAML-App.png)

8. On the *Service Provider Details* page, enter the following details:
  
  - `https://staging.example.com/login/consume` in the *ACS URL* text field.
  - `cloudcannon.com/` in the *Entity ID* text field.
  - (Optional.) `https://staging.example.com/` in the *Start URL* field. This URL is where Google will redirect users to once they have logged in.
9. Check the *Signed response* box.
10. In the *Name ID format* dropdown, select the *EMAIL* option.
11. In the *Name ID* dropdown, select the *Basic Information > Primary email* option.
12. Click *Continue*.
13. On the *Attribute mapping* page, click the *Finish* button.

## Turn on the SAML app

1. Under the *Menu*, select *Apps* then *Web and mobile apps*.
2. Select the SAML App you just created, and click *User access*.
3. Click the *On for everyone* option, then *Save*.

Once you’ve saved your settings, it can take a few minutes for your changes to take effect.


---

---
title: Add SAML authentication to your CloudCannon-hosted Site
description: Enter your SAML certificate details in CloudCannon.
url: https://cloudcannon.com/documentation/developer-guides/google-saml-site-authentication/configure-saml-authentication-for-cloudcannon/
content_type: developer guide
last_modified: 2026-04-16
---

Next, we'll enable SAML authentication on your CloudCannon-hosted Site using the details from the previous step.

1. Log in to [CloudCannon](https://app.cloudcannon.com/) and open your Site.
2. Navigate to the *Authentication* page under *Site Settings*.
3. Click on the *Authentication method* dropdown and select the *SAML* option.
4. Click the *Switch to SAML authentication* button to confirm your choice.
5. Enter the SAML certificate details:
  
  - Enter the *SSO URL* in the *SAML 2.0 Endpoint (HTTP)* text field.
  - Leave the *Issuer Suffix* field blank.
  - Enter the IdP certificate in the *X.509 Certificate* text field. Alternatively, you can click the *Fill cert using XML Metadata*  button to upload the certificate.
6. Click the *Update SAML Configuration* button.

![A screenshot of the Authentication page shows fields for SAML 2.0 Endpoint (HTTP), Issuer Suffix , and X.509 Certificate.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Settings-Authentication-SAML-Empty.webp)

CloudCannon will now redirect visitors to your Google Workspace login page.

Congratulations! Your site is now secured with Google authentication. Only members of your Google Workspace organization can access it. Test the setup by visiting your site and attempting to log in.

If you need any help with this setup, please contact our friendly [support team](/support/).

But what if you have a website that needs authentication for some pages (e.g., a Staff Only section) and leaves other pages publicly accessible? In the next step of this guide, we'll show you how to configure authenticated routes for your CloudCannon-hosted website.


---

---
title: Introduction
description: Learn how to set up visual editing for your website on CloudCannon.
url: https://cloudcannon.com/documentation/developer-guides/set-up-visual-editing/
content_type: developer guide
last_modified: 2026-04-16
---

Welcome to CloudCannon's Set up Visual Editing guide!

This guide covers everything you need to configure to edit files with CloudCannon's [Visual Editor](/documentation/user-articles/what-is-the-visual-editor/). Visual editing provides the most intuitive editing experience, allowing you to make changes directly on an interactive preview of your webpage.

[Video: The Visual Editor with editable regions](https://player.vimeo.com/progressive_redirect/playback/1124969057/rendition/1080p/file.mp4?loc=external&signature=18a05ed71665768fa94851c72a31cf574e4079284b8ce0579885d8f3b47c4a8d)

With the Visual Editor, you can update plain text, rich text, and images inline on your page, edit, reorder, and remove array items (including page building), and navigate between your webpages just as you would on your live website. The biggest benefit of visual editing is that what you see in the Visual Editor is exactly what your visitors will see on a webpage. This means you can make decisions about your content in context.

In this guide, we'll cover:

- How the Visual Editor works.
- How to generate the previews of your webpages by building your *Site* through CloudCannon.
- How to check your *Collection* files output to an HTML webpage.
- How to define editable regions on a webpage for your content managers to use in the Visual Editor.

Before we begin, this guide assumes that you have completed the *Getting Started with Editing* in-app guide, know the correct build settings for your *Site*, and are comfortable editing HTML layouts, either in CloudCannon's Source Editor or your local development environment.

This guide has an in-app counterpart, *Set up Visual Editing*, which you can find on the *Guides* tab of your *Site Dashboard*. We recommend you mark the in-app guide as active now, so you can follow configuration prompts in CloudCannon.

![A screenshot of the Guides tab on the Site Dashboard shows that the active in-app guide is Set up Visual Editing.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Dashboard-Guides-Tab-Visual-Editing.webp)

> **Don't have WYSIWYG editing set up yet?**
> 
> If you aren't quite ready to configure Visual Editing, check out our [Getting Started](/documentation/developer-guides/getting-started-with-cloudcannon/) guide!


---

---
title: What is Visual Editing?
description: Learn about Visual Editor, including how CloudCannon generates interactive previews of your webpages and how to use editable regions.
url: https://cloudcannon.com/documentation/developer-guides/set-up-visual-editing/what-is-visual-editing/
content_type: developer guide
last_modified: 2026-04-16
---

Visual editing is a user-friendly way of updating your website files, allowing you to change your text, images, and arrays on a preview of your output webpage. The benefits of visual editing include providing a more intuitive experience (you can navigate around your website preview using links/buttons, as you would on the live version) and helping you make editing decisions in context with surrounding page elements.

In CloudCannon, you can use the [Visual Editor](/documentation/user-articles/what-is-the-visual-editor/) to visually edit any file that outputs to an HTML webpage at build time.

## Generating the preview of your webpage

When you open a file, the Visual Editor displays a preview of your webpage, along with a sidebar on the left. But, where does CloudCannon get the preview?

CloudCannon generates a preview of all your webpages whenever you build your *Site*, allowing you to see the most up-to-date version of your website every time you use the Visual Editor.

A "build" is when CloudCannon converts all your *Site* files into a single, functional website. Building on CloudCannon is optional, but is required for specific features, such as the Visual Editor, preview screenshots for output files in your *Collection Browser*, and the Testing Domain and Custom Domain.

CloudCannon uses a CI/CD (Continuous Integration/Continuous Delivery) system. Every time you trigger a build of your Site, CloudCannon will:

1. Download your files onto our server.
2. Run your selected install commands (e.g., `npm install`, `bundle install`).
3. Run your selected build commands (e.g., `npm run build`).
4. Index your output files.
5. Upload your output files to CloudCannon to generate previews in the Visual Editor, Testing Domain, and *Collection Browser* screenshots, and deliver them to your live Custom Domain (if you are hosting with CloudCannon).

We'll cover builds more in the [next step of this guide](/documentation/developer-guides/set-up-visual-editing/configure-your-build-settings/).

## Editable regions, data panels, and the sidebar

There are several ways to edit your files in the Visual Editor: inline using editable regions on the preview of your webpage, with data panels for data that is not visible on the webpage, or using Inputs in the sidebar.

You can define which content you want your team to be able to edit inline by adding *Editable Regions* to your files. In the Visual Editor, *Editable Regions* are signified by a yellow box around a piece of content. If you have several *Editable Regions* near each other on your page, CloudCannon will show you the boundary of your region by turning the border green when you click or hover it.

Clicking into an *Editable Region* will have a different result depending on the type of content it contains. CloudCannon will show a WYSIWYG toolbar for rich text, open a data panel for images, and provide tools for editing array items.

[Video: The Visual Editor with editable regions](https://player.vimeo.com/progressive_redirect/playback/1124969057/rendition/1080p/file.mp4?loc=external&signature=18a05ed71665768fa94851c72a31cf574e4079284b8ce0579885d8f3b47c4a8d)

Data panels enable you to edit data that is not visible on your page, and therefore cannot be edited in-line. A good example of this is the path, alt text, or title of an image. You can move these data panels around your screen to ensure they don't cover the content you need.

![A screenshot of the Visual Editor shows a yellow Editable Region box around the image and the Edit Image Data Panel.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Visual-Editor-Frontmatter-Image-Editable-Region.webp)

Finally, the sidebar of the Visual Editor provides [Inputs](/documentation/user-articles/what-are-inputs/) for editing any structured data keys related to your webpage. You can open and close the sidebar as you need, giving you the option to see more of your webpage preview.

When you change the value of an Input in the sidebar, the preview of your webpage in the Visual Editor will immediately update to match the new value. The same will happen if you update the content of an *Editable Region* connected to a structured data key in your sidebar.

If you have not configured your Inputs, CloudCannon will attempt to determine the correct editing interface for your data using the Input value and key name.

![A screenshot of the Visual Editor shows a yellow Editable Region box around the Call to Action component on the blog page.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Visual-Editor-Component-Editable-Region.webp)

In the next step of this guide, we'll cover how to configure your build settings and complete your first successful build.


---

---
title: More resources
description: Learn about other guides for setting up optional configuration in CloudCannon.
url: https://cloudcannon.com/documentation/developer-guides/set-up-visual-editing/more-resources/
content_type: developer guide
last_modified: 2026-04-16
---

Congratulations! 🎉

By following each step in this guide so far, you have completed a successful *Site* build on CloudCannon, ensured that your output *Collections* have the correct URL, and learned how to apply *Editable Regions* to your files to enable visual editing.

## User guides

Now that you have set up the Visual Editor for your *Site*, you can start using it to manage your content. Here's a guide to help your team learn important skills for working in CloudCannon's editing interfaces.

- [Editing in CloudCannon](/documentation/user-guides/editing-in-cloudcannon/)— Learn how to edit your files in CloudCannon's Content, Data, or Source Editors and save those changes back to your Git repository.

Thanks for finishing the *Set up Visual Editing* guide! If you have any questions, please reach out to our friendly [support team](/support/) or check out the [CloudCannon Community](https://community.cloudcannon.com/). We're always here to help.


---

---
title: An overview of Editable Regions
description: Learn about the HTML attributes and web components used to define Editable Regions, including best practices for updating your files.
url: https://cloudcannon.com/documentation/developer-guides/set-up-visual-editing/an-overview-of-editable-regions/
content_type: developer guide
last_modified: 2026-04-16
---

*Editable Regions* enable you to define exactly which data should be visually editable. When you update content in an *Editable Region* (or using the data panel or sidebar), CloudCannon will re-render that section of your webpage to keep the preview up to date. It doesn't matter where you store your data; *Editable Regions* work for values in HTML, structured data in front matter or data files, and Markup content.

Defining *Editable Regions* in your files is as simple as adding an HTML attribute to any DOM element (e.g., `<p data-editable="text">`) or inserting a web component in any file in your website that outputs to HTML (e.g., `<editable-text>`). You can make an entire *Collection* of content files visually editable in minutes.

[Video: The Visual Editor with editable regions](https://player.vimeo.com/progressive_redirect/playback/1124969057/rendition/1080p/file.mp4?loc=external&signature=18a05ed71665768fa94851c72a31cf574e4079284b8ce0579885d8f3b47c4a8d)

Let's cover some of the basics of *Editable Regions*, including best practices for adding them to your files.

## Types of *Editable Regions*

There are six types of *Editable Region*, each of which can be defined by an HTML attribute or a web component.

- **Source Editable Regions** — Enable you to edit text values stored in HTML, with plain text or rich text formatting options.
- **Text Editable Regions** — Enable you to edit text values stored in structured data files, front matter, or Markup content, with plain text or rich text formatting options.
- **Image Editable Regions** — Enable you to edit image values stored in structured data files or front matter, including uploading images from your local storage, selecting existing images from your repository or DAM, and managing image details like title or alt text.
- **Array and Array Item Editable Regions** — Enable you to edit array values stored in structured data files or front matter, including adding, removing, and reordering array items. You can also nest Text, Image, Array, and Component *Editable Regions* inside array items to edit array content.
- **Component Editable Regions** — Enable you to edit registered Astro or React components. You can also nest Text, Image, Array, and Component *Editable Regions* inside your components to edit component content.

In this guide, we'll show you how to define each type of *Editable Region* using HTML attributes or web components. For a complete list of HTML attributes, please read our [Editable Regions](/documentation/developer-reference/editable-regions/) reference documentation.

## Best practices for defining *Editable Regions*

To avoid common pitfalls, here is a list of best practices for defining *Editable Regions*. If you have any questions, please don't hesitate to reach out to our friendly [support team](/support/) or start a conversation in the [CloudCannon Community](https://community.cloudcannon.com/).

### Don't change your data structure

When adding *Editable Regions* to your website files, you don't need to change your file structure or data format. *Editable Region* HTML attributes should work seamlessly with your existing layouts and files, and web components should integrate into your files with minimal disruption.

Additionally, you can migrate to visual editing gradually by adding a few *Editable Regions* for key values, then adding more as needed.

### Add *Editable Regions* to HTML and templating files

Depending on your SSG, the format and extension of the files in your website may differ (e.g., Astro uses `.astro` files, Eleventy uses `.liquid` files). As long as they output to an HTML file after a Site build, you can add *Editable Regions* to any file that contains HTML content and templating.

Many websites also have a content *Collection* (e.g., a blog) where each file has front matter and content that populate templating fields in a layout file at build time. You can make the whole *Collection* visually editable by adding *Editable Regions* to the layout file, rather than the content files themselves.

### Start from the root of your file

A key part of defining *Editable Regions* is telling CloudCannon where your data is stored. CloudCannon calculates the path to your data properties relative to parent elements in your file.

To avoid misconfiguration issues where CloudCannon cannot find the data property you want to edit, it is best to start from the values closest to the root of the file (i.e., work from the parent elements to child elements) when you add *Editable Regions* to your files.

We recommend the following process:

1. Choose a layout file you want to set up visual editing for.
2. Add all the *Editable Regions* required for values in this file, excluding any values nested inside an array or component/partial/include.
3. Add *Editable Regions* to parent elements that contain values you want to edit visually, such as arrays or components/partials/includes.
4. Finally, open any files referenced by the first layout and continue adding *Editable Regions* as per steps 2 and 3 until you reach the end of your file cascade.

Adding *Editable Regions* to a nested component first, without adding the appropriate *Editable Regions* for parent elements, will result in an error.

In the next step of this guide, we'll cover how to define *Editable Regions* for text values stored in HTML, structured data, or Markdown.


---

---
title: Visually edit images
description: Learn how to define Source or Text Editable Regions to edit image values stored in HTML or structured data.
url: https://cloudcannon.com/documentation/developer-guides/set-up-visual-editing/visually-edit-images/
content_type: developer guide
last_modified: 2026-04-16
---

Editing image data in the Visual Editor allows you to see how an image will look on your live webpage.

Image content can be stored in a structured data key and referenced by templating in a layout. You can add an Image *Editable Region* to re-render changes to your image data in the Visual Editor. Let's cover how to define one.

> **Nested image values**
> 
> To avoid `data-prop` misconfiguration errors, it is best practice to define your *Editable Regions* from the root of your file first (i.e., from parent elements to child elements). If your image values are nested inside an array or a component, you should define *Editable* *Regions* for those parent elements first. We'll cover this more in later steps of this guide.

## Image values in structured data

Content files, which contain structured data keys that populate templating in a layout file at build time, often store information image data.

Let's take a look at an example.

This file is a blog post, containing structured data keys for `heroImage`, `heroImageTitle`, and `heroImageAlt` in the front matter.

File: `first-post.mdx`

```markdown

---
title: 'First post'
author: 'C. Kent'
heroImage: '../../assets/blog-banner.jpg'
heroImageTitle: 'Blog gradient'
heroImageAlt: 'An eye-catching color gradient banner.'
---

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Vitae ultricies leo integer malesuada nunc vel risus commodo viverra.

```

Here is an excerpt from our blog layout file, containing HTML for the blog webpage and templating to populate elements with the values from each blog file.

File: `BlogPost.astro`

```Astro
```

<div class="hero-image">
    {heroImage &&
      <img
        src={heroImage} /*1*/
        title={heroImageTitle} /*2*/
        alt={heroImageAlt} /*3*/
      />
    }
</div>

```

**[1]** The value of the `src` attribute in the `<img>` element is `{heroImage}`, which is populated by the value of the `heroImage` key in the front matter of a blog file.

**[2]** The value of the `title` attribute in the `<img>` element is `{heroImageTitle}`, which is populated by the value of the `heroImageTitle` key in the front matter of a blog file.

**[3]** The value of the `alt` attribute in the `<img>` element is `{heroImageAlt}`, which is populated by the value of the `heroImageAlt` key in the front matter of a blog file.
```

> The file type for your layouts will be different depending on your SSG (e.g., Astro uses `.astro` files, Eleventy uses `.liquid` files). You can add *Editable Regions* to any of these files as long as they output to an HTML file after a *Site* build.

Together, these files output a webpage that looks like this:

![A screenshot of a blog page on our Astro website shows a header image, title, author, and content.](/assets/external_screenshots/CloudCannon-Documentation-Visual-Editing-Guide-Content-Page.png)

In this example, the front matter keys populate various attributes of the `<img>` tag in the blog layout at build time (i.e., `src` is set to `{heroImage}`, `title` is set to `{heroImageTitle}`, and `alt` is set to `{heroImageAlt}`). We can add an Image *Editable Region* to the blog layout file to enable visual editing for these image values in the entire *Collection*.

To define an Image *Editable Region*, we can add the `data-editable` and `data-prop-*` HTML attributes to the `<img>` DOM element. The `data-editable` HTML attribute defines which type of *Editable Region* you want to use which, in this case, is `image`. Alternatively, we could choose to wrap the `<img>` element in the equivalent web component `<editable-image>`, however that is not as convenient as adding attributes to existing elements.

The `data-prop-*` HTML attribute, like `data-prop` (see the [previous step of this guide](/documentation/developer-guides/set-up-visual-editing/visually-edit-text/)), defines where your data is stored. However, the `data-prop-*` attribute is an extension of the `data-prop` attribute behavior as it also passes a key name to the *Editable Region*.

A limitation of the `data-prop` attribute is that it only passes the value stored at a location to the *Editable Region*. Some *Editable Regions*, like Image, expect data in the `key: string` format. For example, `data-prop="heroImage"` pointing at the front matter object `heroImage: "/example.jpg"` would pass the value "/example.jpg" to the *Editable Region* in the Visual Editor. If we use `data-prop-src="heroImage"` instead, we can pass "src: /example.jpg" to the *Editable Region*.

To edit the image path, title, and alt text in the Visual Editor, let's use `data-prop-src="heroImage"`, `data-prop-title="heroImageTitle"`, and `data-prop-alt="heroImageAlt"` to the `<img>` tag.

> You don't have to include the image title and alt text for the Image *Editable Region* to function, but we recommend it for website SEO.

Here's what our blog layout code should look like:

File: `BlogPost.astro`

```Astro
```

<div class="hero-image">
    {heroImage &&
      <img
        data-editable="image" /*1*/
        data-prop-src="heroImage" /*2*/
        data-prop-alt="heroImageAlt" /*3*/
        data-prop-title="heroImageTitle" /*4*/
        src={heroImage}
        title={heroImageTitle}
        alt={heroImageAlt}
      />
    }
</div>

```

**[1]** The `data-editable` attribute defines what kind of data this element contains. In this case, the value is `image`.

**[2]** The `data-prop-src` attribute passes the value of `heroImage` to the Image Editable Region with the `src` key.

**[3]** The `data-prop-title` attribute passes the value of `heroImageTitle` to the Image Editable Region with the `title` key.

**[4]** The `data-prop-alt` attribute passes the value of `heroImageAlt` to the Image Editable Region with the `alt` key.
```

Once we save and rebuild our *Site*, CloudCannon will show a yellow *Editable Region* box around the image in the Visual Editor.

![A screenshot of the Visual Editor shows a yellow Editable Region box around the image and the Edit Image Data Panel.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Visual-Editor-Frontmatter-Image-Editable-Region.webp)

When you click into the Image *Editable Region*, CloudCannon will open the *Edit Image* Data Panel with the option to change the image, and update the image title and alt text.

If you upload a new image through the *Edit Image* Data Panel, CloudCannon will upload it to one of three locations. If your front matter key is configured as an [Image Input](/documentation/user-articles/what-is-a-file-input/#image), CloudCannon will upload your new image to the location defined by `options.paths.uploads`. If this option is not defined, CloudCannon will use the location defined by `paths.uploads` in the root of your CloudCannon Configuration file. Finally, if you do not have any uploads path defined, CloudCannon will upload the new image to the "uploads" folder in the root of your repository, or create one if the folder does not exist.

## Common errors

If you accidentally misconfigure your *Editable Regions*, CloudCannon will display a red warning box in the Visual Editor.

Here are a few common errors you might encounter with Source and Text *Editable Regions*:

- You did not define the `data-prop-*` HTML attribute for your Image *Editable Region*.
- The *Editable Region* has an invalid data type (e.g., your Text region has a number or object, instead of a string).
- There is no `<img>` child element in the Image *Editable Region* web component.

In the next step of this guide, we'll cover how to define *Editable Regions* for simple arrays.


---

---
title: Confirm your output URLs
description: Learn how to open your files in the Visual Editor, confirm your output URLs are correct, and update them if they are incorrect.
url: https://cloudcannon.com/documentation/developer-guides/set-up-visual-editing/confirm-your-output-urls/
content_type: developer guide
last_modified: 2026-04-16
---

When you [build](/documentation/developer-articles/what-is-a-site-build/) your *Site*, CloudCannon will run the build command appropriate for your Static Site Generator (SSG). Your SSG will build your source files into your output files. These output files are what your website visitors will see on the Internet and what CloudCannon uses as the interactive webpage in the *Visual Editor*.

## How does CloudCannon use your output files?

When you click on a source file in the *Collection Browser* to open it in the *Visual Editor*, CloudCannon opens the appropriate output file. To open the correct output file in the *Visual Editor*, CloudCannon matches output files with source files using the output URL.

However, most modern websites do not have a one-to-one relationship between source files and output files. For example, the output file for your "Home" page will be `index.html`, but the content for this file could be stored across multiple source files (e.g., one for navigation, another for the footer, and a third for page content).

Whenever you finish a successful build, CloudCannon will automatically determine the likely output URL for each source file. The next task in the *Set up Visual Editing* in-app guide asks you to *Confirm your output URLs*, ensuring that CloudCannon is opening the correct output file for each source file in your *Collection Browser*.

![A screenshot of the Confirm your output files task shows two collections with eight output files.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Confirm-Output-Files-Task.webp)

## Confirm CloudCannon matched your files correctly

You can confirm that CloudCannon matched your output files and source files correctly by opening your source files in the *Visual Editor*.

![A screenshot of the Collection browser shows previews of several blog files, sort and view dropdowns, the collection filter, and the + Add button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser.webp)

Click on a file in your *Collection Browser* to open it in an *Editing Interface*. If it doesn't open in the *Visual Editor* immediately, you can switch to the *Switch to Visual Editor* button in the *Editing Interface Header*.

![A screenshot of the Editing Interface Header Controls shows the Switch Editing Interface buttons.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Editing-Interface-Header-Controls.webp)

The webpage preview shown in the *Visual Editor* is one of the output files made by your SSG. If this is the output file you expected to see when you opened your source file in the *Visual Editor*, then CloudCannon has correctly determined the output URL for matching your output and source files.

![A screenshot of the Visual Editor shows an interactive webpage preview.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Visual-Editor-Bookshop-Sendit-Home.webp)

Try opening a few more files. If all your files open to the correct page in the *Visual Editor*, you can move on from this step of the guide and mark the in-app task as complete.

If a file will not open in the Visual Editor or opens to an incorrect webpage preview, it is most likely because CloudCannon has not determined the correct output URL. You can [update the output URL](https://cloudcannon.com//documentation/developer-guides/set-up-visual-editing/confirm-your-output-urls/) for a *Collection* to fix this issue.

## Update the output URL for a webpage preview

To help CloudCannon match webpage previews to your output files, you can specify the output URL for each *Collection* using a template string. A template string is made of plain text and placeholder values, allowing you to use structured data from your files in the *Collection*.

Navigate to one of the *Collections* that does not correctly open in the Visual Editor and click the *Configuration Mode switch* on the right of the *Site Header* to turn it on. Purple *Edit configuration* buttons will appear in several places across the CloudCannon UI, including the *Edit Advanced* in the top right of the *Collection Browser*.

Click on the *Edit Advanced* button to open the data panel.

![A screenshot of the Collection Browser shows the Edit Advanced data panel open with a text field for URL configuration.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Collection-Browser-Configuration-Mode-Edit-Advanced-URL.webp)

Find the *URL* text field in the *Edit Advanced* data panel. Here, you can specify which output URL CloudCannon should use to match webpage previews to the *Collection* using a template string.

Template strings allow you to use plain text, fixed or data placeholders, and filters to modify the value of data placeholders to create the correct URL format.

### Fixed placeholders

The following fixed placeholders are available for your output URL template string:

- `[filename]` — Populated by the original filename including the file extension.
- `[slug]` — Populated by the original filename excluding the file extension. If the filename is "index", this will result in an empty string.
- `[relative_path]` — Populated by the original file name including the file extension, relative to the *Collection* path.
- `[relative_base_path]` — Populated by the original file name excluding the file extension, relative to the *Collection* path.
- `[full_slug]` — An alias for the template path `[relative_base_path]/[slug]`.
- `[path]` — Populated by the original file name including the file extension, relative to your *Site* source.
- `[base_path]` — Populated by the original file name excluding the file extension, relative to your *Site* source.
- `[collection]` — Populated by the key for the *Collection* to which the file belongs.
- `[ext]` — Populated by the last file extension in the original file path.

Let's go through an example.

The `url` template string `/[relative_bath_path]/[slug]/` for our "Pages" *Collection* will resolve to the following output URLs:

- The file `/pages/index.md` becomes the output URL `/` (e.g., a Home landing page).
- The file `/pages/about.md` becomes the output URL `/about`.
- The file `/pages/contact/index.md` becomes the output URL `/contact/`.
- The file `/pages/contact/book-an-appointment.md` becomes the output URL `/contact/book-an-appointment`

### Data placeholders

You can reference any front matter field from your file in your output URL template string by using the key name in curly brackets (e.g., `{key}`).

You can also apply filters to your data placeholders by using the `|` character after your front matter key name, followed by the name of the filter.

Let's go through an example.

The `url` template string `/news/{date|year}/{date|month}-{date|day}_{title|slugify}/` for our "News" *Collection* will resolve to the following output URLs:

- The file `/news/our-next-feature.md` with the front matter fields `title: Our next feature!` and `date:05/11/2026` becomes the output URL `/2026/05-11_our-next-feature`.

For a complete list of filters available for data placeholders in your output URL template string, please read our documentation on [template strings](/documentation/developer-articles/configure-your-template-strings/).

Once you have updated the template string in the *URL* text field, save the changes to your *Configuration File*. CloudCannon will automatically update which webpage previews it uses for that *Collection*.

When you are happy that all your output files open in the Visual Editor successfully, you can mark the *Confirm your output files* task as complete.

In the next step of this guide, we'll learn about *Editable Regions*, including their types and best practices for implementing them.


---

---
title: Visually edit simple arrays
description: Learn how to define Array and Array Item Editable Regions to add, delete, and reorder array items in a simple array.
url: https://cloudcannon.com/documentation/developer-guides/set-up-visual-editing/visually-edit-simple-arrays/
content_type: developer guide
last_modified: 2026-04-16
---

Some webpages, or webpage components, are constructed from arrays. An array is an ordered list of data, where data is grouped into array items. Each array item could contain one or several structured data keys.

Arrays can be simple, where each item has the same structure (e.g., a testimonial component), or more complex, where each item has a different structure (e.g., a page with various components). For simple arrays, you can use Array and Array Item *Editable Regions* to enable your team to visually edit arrays, including adding, deleting, and reordering items. We'll cover complex arrays in a [later step of this guide](/documentation/developer-guides/set-up-visual-editing/visually-edit-complex-arrays-and-page-building/).

> **Nested text or image values in an array**
> 
> To avoid `data-prop` misconfiguration errors, it is best practice to define your *Editable Regions* from the root of your file first (i.e., from parent elements to child elements). If you want to edit text or image values in an array using the Visual Editor, you should define your Array and Array Item *Editable Regions* on the parent element before Text and Image.

## Arrays with identical array items

Array content is defined using structured data keys in the front matter of hybrid files (e.g., `.mdx`) or in data files (e.g., `.yml`) and referenced by templating in a layout file. Simple arrays have the same structured data keys for every array item.

Let's take a look at an example.

Our website has a "Testimonials" page, where we display testimonials from customers. The page content is stored in the front matter of a Markdown file and populates a layout file.

Here is our content file, `testimonials.md`, containing the `testimonials` array with structured data keys for `image`, `image_alt`, `name`, `job_title`, and `quote` in each array item.

File: `testimonials.md`

```Markdown

---
layout: ../layouts/TestimonialsLayout.astro
testimonials:
  - image: ../../assets/placeholder-1.jpg
    image_alt: Profile photo of D. Gale
    name: D. Gale
    job_title: CEO at Yellow Brick Industries
    quote: >-
      "In pretium libero sed velit posuere sagittis."
  - image: ../../assets/placeholder-2.jpg
    image_alt: Profile photo of S. Crow
    name: S. Crow
    job_title: CBO at Yellow Brick Industries
    quote: >-
      "Mauris at augue quis orci egestas eu in nulla."
  - image: ../../assets/placeholder-3.jpg
    image_alt: Profile photo of T. Man
    name: T. Man
    job_title: CHO at Yellow Brick Industries
    quote: >-
      "Nunc ut sem vitae tortor volutpat varius."
  - image: ../../assets/placeholder-4.jpg
    image_alt: Profile photo of C. Lion
    name: C. Lion
    job_title: CCO at Yellow Brick Industries
    quote: >-
      "Aenean pharetra orci ac tincidunt lobortis."
---

```

Here is an excerpt from our layout file, `TestimonialsLayout.astro`. This section loops over all the items in the `testimonials` array, and populates the layout using the values.

File: `TestimonialsLayout.astro`

```Astro
```

---
const { testimonials } = Astro.props.frontmatter;
---

<ul>
  {
    testimonials.map((testimonial) => (
      <li>
        {testimonial.image && (
          <img
            src={testimonial.image}
            alt={testimonial.image_alt}
          /> /*1*/
        )}
        <h4>{testimonial.name}</h4> /*2*/
        <p>{testimonial.job_title}</p> /*3*/
        <p>{testimonial.quote}</p> /*4*/
      </li>
    ))
  }
</ul>

```

**[1]** This `<img>` element contains image source and alt text attributes. The `src` and `alt` attributes are set to the template `{testimonial.image}` and `{testimonial.image_alt}` respectively.

**[2]** This `<h4>` element surrounds the template value `{testimonial.name}`.

**[3]** This `<p>` element surrounds the template value `{testimonial.job_title}`.

**[4]** This `<p>` element surrounds the template value `{testimonial.quote}`.
```

Together, these files output a webpage that looks like this:

![A screenshot of the quotes page on our Astro website shows four items, each with an image, title, author, and quote.](/assets/external_screenshots/CloudCannon-Documentation-Visual-Editing-Guide-Quotes-Page.png)

To enable visual editing for this array, we can add Array and Array Item *Editable Regions* to our layout file. Array *Editable Regions* define the boundary of the array and Array Item *Editable Regions* define each array item. Array and Array Item *Editable Regions* work together, so we must always have both.

The `<ul>` element wraps the array in our layout file, with its contents looping over every array item stored under the `testimonials` key. To define an Array *Editable Region*, let's add the `data-editable` and `data-prop` HTML attributes to the `<ul>` DOM element. The `data-editable` HTML attribute defines which type of *Editable Region* you want to use which, in this case, is `array`. Alternatively, we could choose to wrap the array templating in the equivalent web component `<editable-array>`, however that is not as convenient as adding attributes to existing elements. Our Array *Editable Region* also needs a `data-prop` to define where our array data is stored which, in this case, will be the `testimonials` front matter key.

The `<li>` element wraps each array item in our layout file, containing the HTML structure for each testimonial's content. To define an Array Item *Editable Region*, let's add the `data-editable` HTML attributes to the `<li>` DOM element. The value of `data-editable` HTML attribute should be `array-item`.

> **Where should the Array and Array Item*****Editable Regions*** **go?**
> 
> The Array *Editable Region*attribute or web component should be the immediate parent element of your array templating. The Array Item *Editable Region* attribute or web component should be the first child element of your array templating. This way, Array and Array Item should flank the templating for looping over your array.
> 
> Try to avoid any nested elements between them; they should be as close together as possible, regardless of whether you use HTML attributes, web components, or both.

If we also want to visually edit the text and images inside each array item, we can define three Text *Editable Regions* for the name, job title, and quote, and an Image *Editable Region* for our image and alt text.

Here's what our layout file should look like:

File: `TestimonialsLayout.astro`

```Astro
```

---
const { testimonials } = Astro.props.frontmatter;
---

<ul data-editable="array" data-prop="testimonials"> /*1*/
  {
    testimonials.map((testimonial) => (
      <li data-editable="array-item">
        {testimonial.image && (
          <img
            data-editable="image"
            data-prop-src="image"
            data-prop-alt="image_alt"
            src={testimonial.image}
            alt={testimonial.image_alt}
          /> /*2*/
        )}
        <h4 data-editable="text" data-prop="name">{testimonial.name}</h4> /*3*/
        <p data-editable="text" data-prop="job_title">{testimonial.job_title}</p> /*4*/
        <p data-editable="text" data-prop="quote">{testimonial.quote}</p> /*5*/
      </li>
    ))
  }
</ul>

```

**[1]** The `data-editable` attribute defines what kind of data this element contains, and the `data-prop` attribute defines the path to the data we want to edit. In this case, we want an Array *Editable Region*, so the value of `data-editable` is `array`, and we want to edit the `testimonials` structured data key in the file front matter.

**[2]** This `<img>` element contains `data-editable="image"`, `data-prop-src="image"`, and `data-prop-alt="image_alt"` to define an Image *Editable Region*.

**[3]** This `<h4>` element contains `data-editable="text"` and `data-prop="name"` to define a Text *Editable Region*.

**[4]** This `<p>` element contains `data-editable="text"` and `data-prop="job_title"` to define a Text *Editable Region*.

**[5]** This `<p>` element contains `data-editable="text"` and `data-prop="quote"` to define a Text *Editable Region*.
```

Once we save and rebuild our *Site*, CloudCannon will show a yellow *Editable Regions* box around each array item on the Testimonials page, and around each image and text field.

![A screenshot of the Visual Editor shows yellow Editable Region boxes around the array items, text, and images on the Quotes webpage.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Visual-Editor-Simple-Array-Editable-Region.webp)

When you hover an array item, CloudCannon will show a small toolbar in the top right, containing an *Edit* button and a *Drag* handler. Clicking the *Edit* button will open a data panel containing your array item fields. Clicking the *Drag* handler will open a dropdown with options to move an array item one position to the left or right, and to delete the item, while clicking and holding the *Drag* handler allows you to visually move an array item to any position in the array.

[Video: Array Editable Regions in the Visual Editor](https://player.vimeo.com/progressive_redirect/playback/1127384254/rendition/1080p/file.mp4?loc=external&signature=2a13816e5104cb323e411f0d83f84fe060f24975a7dc81fe5fe80155591af1a7)

## Common errors

If you accidentally misconfigure your *Editable Regions*, CloudCannon will display a red warning box in the Visual Editor.

Here are a few common errors you might encounter with Array *Editable Regions*:

- You did not define the `data-prop` HTML attribute.
- The *Editable Region* has an invalid data type (e.g., your Text region has a number or object, instead of a string).
- You have one or more orphaned Array Item *Editable Regions* that are not contained within an Array *Editable Region*.

In the next step of this guide, we'll cover how to define *Editable Regions* for Astro or React components.


---

---
title: Visually edit components
description: Learn how to define Component Editable Regions to enable component live re-rendering in the Visual Editor.
url: https://cloudcannon.com/documentation/developer-guides/set-up-visual-editing/visually-edit-components/
content_type: developer guide
last_modified: 2026-04-16
---

> Currently, Component *Editable Regions* are only available for Astro and React. We are working to support more types. Please get in touch with our friendly [support team](/support/) to make a request.

Many static websites use reusable code components (a.k.a., partials) ranging from a small snippet of HTML, to UI elements like a header, profile card, or an entire page layout.

You can use the Component *Editable Regions* to re-render changes to your components in the Visual Editor, or enable inline editing of component text and images in conjunction with other *Editable Regions*. Let's cover how to define one.

> **Nested text or image values**
> 
> To avoid `data-prop` misconfiguration errors, it is best practice to define your *Editable Regions* from the root of your file first (i.e., from parent elements to child elements). If you want to edit text or image values in a component using the Visual Editor, you should define your Component *Editable Region* on the parent element before Text and Image.

## Install the NPM package

Before you can use Component *Editable Regions*, you will need to install CloudCannon's *Editable Regions* NPM package.

With your website project open in your local development environment, run the following command in your terminal:

```

npm install @cloudcannon/editable-regions

```

> React is a dependency of this package. You may need to use `npm i` to install React if your local development environment is out of date.

For more information, you can visit CloudCannon's GitHub repository for the [Editable Regions NPM package](https://github.com/CloudCannon/editable-regions).

## Update Astro config file

If you use Astro, add the *Editable Regions* integration to your Astro config file:

File: `astro.config.mjs`

```JavaScript

import editableRegions from "@cloudcannon/editable-regions/astro-integration";
import { defineConfig } from "astro/config";

export default defineConfig({
  integrations: [editableRegions()],
});

```

## Register your components

Next, you need to register your components with the NPM package. To do this, you'll need to create a registration script and include it in your layout.

If you use `.astro` component files, even if you have React components nested in them, you will need to import `{ registerAstroComponent }` in your registration script. Here's an example for the CTA component.

File: `src/scripts/register-components.js`

```JavaScript
```

import { registerAstroComponent } from '@cloudcannon/editable-regions/astro';
import '@cloudcannon/editable-regions/astro-react-renderer'; /*1*/
import CTA from '../components/CTA.astro';

// Register your components
registerAstroComponent('cta', CTA);

```

**[1]** This import is only necessary if you use React components nested inside your Astro components.
```

If you use `.tsx` or `.jsx` component files, you will need to import `{ registerReactComponent }` in your registration script. Here's an example for the CTA component.

File: `src/scripts/register-components.js`

```JavaScript

import { registerReactComponent } from '@cloudcannon/editable-regions/react';
import MyComponent from './MyComponent.jsx';

registerReactComponent('my_component', MyComponent);

```

Registering your components tells CloudCannon that those components should be bundled for client side use in the Visual Editor.

## Components in layout files

Components use templating to reference structured data keys. Layout files then reference a component file. At build time, CloudCannon populates the component with the correct values and outputs it to the layout's HTML webpage.

Let's take a look at an example.

This file is a blog post, containing the `cta` object to the front matter, and the structured data keys `description`, `link`, `buttonText`, and `buttonColor`.

File: `first-post.mdx`

```Markdown

---
title: 'First post'
author: 'C. Kent'
heroImage: '../../assets/blog-banner.jpg'
heroImageTitle: 'Blog gradient'
heroImageAlt: 'An eye-catching color gradient banner.'
cta:
  description: "Need a little more help? Send a message to our friendly support team."
  link: "https://www.cloudcannon.com/support/"
  buttonText: "Send a message"
  buttonColor: "#034AD8"
---

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Vitae ultricies leo integer malesuada nunc vel risus commodo viverra.

```

Here is an excerpt from our blog layout file, containing a Call-To-Action component called `CTA` at the bottom of every blog post.

File: `BlogPost.astro`

```Astro
```

---
import CTA from '../components/CTA.astro';
---

<html lang="en">
	<body>
		<main>
			<article>
                <!-- Blog HTML here -->
			</article>
			<CTA {...Astro.props.cta} /> /*1*/
		</main>
	</body>
</html>

```

**[1]** The `<CTA>` component uses structured data in the front matter of the files in the Blog collection.
```

Finally, here's our component layout file, which contains HTML for the component and templating to populate elements with values from each blog file.

File: `components/CTA.astro`

```Astro

---
const { description, link, buttonText, buttonColor } = Astro.props;
---

<p>{description}</p>
<a href={link}>
    <button style={`background-color: ${buttonColor}`}>{buttonText}</button>
</a>

```

Together, these files output a webpage that looks like this:

![A screenshot of a blog page on our Astro website shows a call to action component under the blog content.](/assets/external_screenshots/CloudCannon-Documentation-Visual-Editing-Guide-CTA-Component.png)

In this example, the `<CTA>` component uses the properties in the `cta` object in each blog post. We can add a Component *Editable Regions* to our layout file to enable the Visual Editor to re-render any changes made with the data panel or sidebar.

First you need to import the component registration file you made earlier with a `<script>` HTML element. The `<script>` element should go inside the `<body>` element of your layout, which could be a different file depending on how your *Site* is structured (e.g., you may have a base layout file that all your other layouts reference). When you import the component registration file, you can also add instructions to check if your browser window is in Editor Mode (i.e., your webpage is open in CloudCannon's Visual Editor) and add an error warning.

Next, since the `<CTA>` component lacks an appropriate parent DOM element, you should wrap it in the `<editable-component>` web component. Our Component *Editable Region* also needs a `data-prop` to define where our component data is stored which, in this case, will be the `cta` front matter object in our blog post.

Finally, you need to add the `data-component` HTML attribute to define which registered component we are using which, in this case, is also called `cta`.

Here's what our Blog Layout code should look like:

File: `BlogPost.astro`

```Astro
```

<html lang="en">
  <body>
    <script> /*1*/
      if (window.inEditorMode) {
        import("../scripts/register-components.js").catch((error) => {
          console.warn("Failed to load CloudCannon component registration:", error);
        });
      }
    </script>
    <main>
      <article>
        <!-- Blog HTML here -->
      </article>
      <editable-component data-prop="cta" data-component="cta"> /*2*/
        <CTA {...Astro.props.cta} />
      </editable-component>
    </main>
    <Footer />
  </body>
</html>

```

**[1]** The `<script>` element instructs your browser to import the `register-components.js` file if your webpage is open in the Visual Editor.

**[2]** The `editable-component` web component defines a Component *Editable Region*. The `data-prop` attribute defines the path to the data we want to edit, and the `data-component` defines which registered component we are using. In this case, we want to edit the `cta` structured data key in the blog front matter and use the registered component `cta`.
```

If we were to save and rebuild our *Site* now, the Visual Editor would allow you to re-render the CTA component when you edit values using the data panel or sidebar, but would not allow inline editing for the text values `description` and `buttonText`. To achieve this, we also need to add Text *Editable Regions* to the CTA component file.

Here's what our CTA component code should look like:

File: `components/CTA.astro`

```Astro
```

---
const { description, link, buttonText, buttonColor } = Astro.props;
---

<p data-editable="text" data-prop="description">{description}</p>
<a href={link}>
    <button data-editable="text" data-prop="buttonText" style={`background-color: ${buttonColor}`}>{buttonText}</button>
</a>

```

**[1]** This `<p>` element contains `data-editable="text"` and `data-prop="description"` to define a Text *Editable Region*.

**[2]** This `<button>` element contains `data-editable="text"` and `data-prop="buttonText"` to define a Text *Editable Region*.
```

Once we save and rebuild our *Site*, CloudCannon will show a yellow *Editable Regions* box around all the content inside the `<CTA>` component in the Visual Editor. There are also two Text *Editable Regions* around the description and button text.

![A screenshot of the Visual Editor shows a yellow Editable Region box around the Call to Action component on the blog page.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Visual-Editor-Component-Editable-Region.webp)

When you click into the *Editable Region*, CloudCannon will open a data panel with inputs for all four structured data keys in the component: `description`, `link`, `buttonText`, and `buttonColor`.

## Common errors

If you accidentally misconfigure your *Editable Regions*, CloudCannon will display a red warning box in the Visual Editor.

Here are a few common errors you might encounter with Component *Editable Regions*:

- You did not define the `data-prop` or `data-component`HTML attributes.
- The *Editable Region* has an invalid data type (e.g., your Text region has a number or object, instead of a string).
- You reference a component that does not exist, or has not been registered.
- Component rendering errors
- Invalid component return values

In the next step of this guide, we'll cover how to define *Editable Regions* for complex arrays.


---

---
title: Configure your build settings
description: Learn how to enable Site builds on CloudCannon and configure your build settings for visual editing.
url: https://cloudcannon.com/documentation/developer-guides/set-up-visual-editing/configure-your-build-settings/
content_type: developer guide
last_modified: 2026-04-16
---

Before you can use the Visual Editor, you must have at least one successful build on CloudCannon.

Let's configure your build settings and complete a successful build. If you have already met these requirements, such as by completing the Host your website on the Internet guide, you can skip this step of the guide.

## Configure your build

To build your *Site*, CloudCannon needs to know a few details about how your website functions.

Click the *Configure your build* button in your in-app guide under the *Configure your Site's build settings* task.

![A screenshot of the Configure your Site's build settings task shows the Configure your build button.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Configure-Build-Task.webp)

CloudCannon will open the *Configure your build* modal.

![A screenshot of the Configure your build modal.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Dashboard-Configure-Build-Modal.webp)

CloudCannon can make suggestions for your build settings based on the SSG your *Site* uses and the contents of your files. You can enter your own build settings or accept a suggestion by clicking the *Use* button, and CloudCannon will populate the text field. If you are unsure about the correct build settings for your *Site*, please contact your developer or reach out to our friendly [support team](/support/).

![A screenshot of the Install Command text field and CloudCannon's suggested value in a light blue box.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Build-Configuration-Install-Command-Suggestion.webp)

Under the *Command line options* section, enter your *Install Command*, *Build Command*, *Output Path*, and *Environment Variables*. CloudCannon requires a value for *Output Path*.

![A screenshot of the Configure your build modal shows the command line options.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Build-Configuration-Command-Line-Options.webp)

Under the *Build system options* section, enter your *Preserved Paths*, and choose whether you want to enable the *Preserve Output*, *Include .git folder*, and *Manually Configure URLs* settings.

![A screenshot of the Configure your build modal shows the build system options, including Preserved Paths.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Build-Configuration-Build-System-Options.webp)

Finally, under the *Library Versions* section, review the versions of *Hugo*, *Ruby*, *Node*, and *Deno*. If your website uses any of these libraries, please ensure the version number is correct.

![A screenshot of the Configure your build modal shows the library versions for Hugo, Ruby, Node, and Deno.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Build-Configuration-Library-Versions.webp)

When you are happy with your answers, click the *Update Configuration and Build* button. CloudCannon will start your first *Site* build using the configuration you defined.

## Your first build

Your first *Site* build should start immediately.

Whenever CloudCannon is building your *Site*, the *Building...* notification will appear in the bottom right of your screen. Clicking on the *View output* button on this notification will open the *Build output* modal.

![A screenshot of the Content Editor with the Building notification in the bottom right shows a button labeled View Output.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Building-Toast-Notification.webp)

The *Build output* modal displays the *Build log* for your current build. *Build logs* are useful for keeping track of your build progress and diagnosing any issues if your build fails.

![A screenshot of the Content Editor with the Build Terminal modal open shows the progress of the current Site build.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Build-Terminal-Modal.webp)

You can access a list of all your past *Build logs* on the *Builds* tab of your *Site Dashboard*. CloudCannon added this tab to your *Dashboard* after you configured your first build.

![A screenshot of the Builds tab on the Site Dashboard shows a list of all past build logs for this Site.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Dashboard-Builds-Tab.webp)

You can also see the progress of your most recent build on the *Summary* tab of your *Dashboard*, on the right under *Build*. You can trigger a new build at any time using the *Rebuild* button on the *Site Dashboard* or cancel a running build using the *Cancel build* button.

If your build fails, please reach out to our friendly [support team](/support/).

Once you have a successful build, a link to your [Testing Domain](/documentation/user-articles/what-is-a-testing-domain/) will appear in your *Site Header*. You can click on this to see your live website in a new tab.

![A screenshot of the Site Header shows a link to the Testing Domain, which appears after your first successful Site build.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Site-Header-Tools-Post-Build.webp)

In the next step of this guide, we'll take a look at your output files and make sure CloudCannon has generated all the webpage previews you need for the Visual Editor.


---

---
title: Visually edit complex arrays and page building
description: Learn how to define Array, Array Item, and Component Editable Regions to add, delete, and reorder array items in a complex array.
url: https://cloudcannon.com/documentation/developer-guides/set-up-visual-editing/visually-edit-complex-arrays-and-page-building/
content_type: developer guide
last_modified: 2026-04-16
---

We've covered how to use Array, Array Item, and Component *Editable Regions* in the previous steps of this guide. We can use these *Editable Regions* in conjunction to enable visual editing for a complex array.

Array items in complex arrays can have different structured data keys. Complex arrays are often used to create a page-building experience, where each array item represents a block of content on your page. To enable visual editing for a complex array, including adding, deleting, and reordering items in the Visual Editor, we need to add Array, Array Item, and Component *Editable Regions*.

> **Nested text or image values in an array**
> 
> To avoid `data-prop` misconfiguration errors, it is best practice to define your *Editable Regions* from the root of your file first (i.e., from parent elements to child elements). If you want to edit text or image values in an array using the Visual Editor, you should define your Array and Array Item *Editable Regions* on the parent element before Text and Image.

## Arrays with different array items

Just like simple arrays, complex array content is defined using structured data keys in the front matter of hybrid files (e.g., `.mdx`) or in data files (e.g., `.yml`) and referenced by templating in a layout file. Simple arrays have the same structured data keys for every array item.

Let's take a look at an example.

Our website has an "About" page, where we display information about our company. We use a complex array to build this page, allowing us to add several different kinds of content blocks. The data for these content blocks is stored in the front matter of a Markdown file using array items with different structured data keys.

Here is our content file, `about.md`, containing the `contentBlocks` array.

File: `about.md`

```Markdown

---
layout: ../layouts/AboutLayout.astro
contentBlocks:
  - _name: HeroBlock
    title: We're on a mission
    description: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce lobortis mi sed est dapibus, sit amet consectetur quam euismod. Cras pretium quam vitae malesuada placerat. Curabitur ac sagittis ligula. Nunc sed ultrices leo. Vestibulum malesuada lobortis nisl, a feugiat est viverra et.
  - _name: StatsBlock
    stats:
      - figure: $200m
        text: Venture capital raised
      - figure: "2016"
        text: Established in
      - figure: 40+
        text: Amazing team members
      - figure: 44325+
        text: Active users and growing
  - _name: ContactBlock
    text: Want to get in contact with us?
    button: Click here
    image: https://preview.astro.new/blog/_astro/blog-placeholder-about.BtEdEmGp_1cKsnD.webp
---

```

Content from each array item in the `contentBlocks` array populates a component specific to that block. Here are the component files we use for our three blocks: Hero, Stats, and Contact.

File: `HeroBlock.astro`

```Astro

---
const { title, description } = Astro.props;
---

<h2>{title}</h2>
<p>{description}</p>

```

File: `StatsBlock.astro`

```Astro

---
const { stats } = Astro.props;
---

<div>
  {
    stats.map(({ figure, text }) => {
      return (
        <div>
          <p>{figure}</p>
          <p>{text}</p>
        </div>
      );
    })
  }
</div>

```

File: `ContactBlock.astro`

```Astro

---
const { text, button, image } = Astro.props;
---

<img src={image} />
<p>{text}</p>
<button type="button">{button}</button>

```

Finally, our page layout file, `AboutLayout.astro`, loops over all the items in the `contentBlocks` array, finds the appropriate layout for each item and populates that component using values from `about.md`. Here is an excerpt from our About layout file.

File: `AboutLayout.astro`

```Astro

---
const components = {};
const componentImports = import.meta.glob("../components/**/*.astro", {
  eager: true,
});
Object.entries(componentImports).forEach(([path, obj]) => {
  const name = path.replace("../components/", "").split(".")[0];
  components[name] = obj.default;
});

const { contentBlocks } = Astro.props.frontmatter;
---

<main>
  {
    contentBlocks.map((block) => {
      const Component = components[block._name];
      return (
        <section>
          <Component {...block} />
        </section>
      );
    })
  }
</main>

```

Together, these files output a webpage that looks like this:

![A screenshot of the About page on our Astro website shows header content, some statistics, an image, and a button.](/assets/external_screenshots/CloudCannon-Documentation-Visual-Editing-Guide-About-Page.png)

To enable visual editing for this complex array, we can add Array, Array Item, and Component *Editable Regions*.

Let's start by registering our content blocks as components.

Just like the [previous step of this guide](/documentation/developer-guides/set-up-visual-editing/visually-edit-components/), we need to install CloudCannon's *Editable Regions* NPM package and update our Astro config file (if applicable). Next, we can create a registration script including each of our content blocks, informing CloudCannon that they should be bundled for client-side use in the Visual Editor.

File: `src/scripts/register-components.js`

```JavaScript
```

import { registerAstroComponent } from '@cloudcannon/editable-regions/astro';
import '@cloudcannon/editable-regions/astro-react-renderer'; /*1*/
import HeroBlock from '../components/HeroBlock.astro';
import StatsBlock from '../components/StatsBlock.astro';
import ContactBlock from '../components/ContactBlock.astro';

// Register your components
registerAstroComponent('HeroBlock', HeroBlock);
registerAstroComponent('StatsBlock', StatsBlock);
registerAstroComponent('ContactBlock', ContactBlock);

```

**[1]** This import is only necessary if you use React components nested inside your Astro components.
```

Finally, we can add *Editable Regions* to our `AboutLayout.astro` file.

The `<main>` element wraps the array in our layout file, with its contents looping over every array item stored under the `contentBlocks` key. Like a simple array, let's add the `data-editable="array"` and `data-prop="contentBlocks"` HTML attributes to the `<main>` DOM element. For a complex array, we also need to add the `data-id-key` and `data-component-key` HTML attributes. The `data-id-key` attribute defines which structured data key CloudCannon should look at for each array item's unique identifier. The `data-component-key` defines which structured data key CloudCannon should look at for the name of the registered component. For simplicity's sake, we registered our components using the same name as the unique identifier, so the value for both these attributes is `_name`.

The `<section>` element wraps each array item in our layout file. Like a simple array, let's add the `data-editable="array-item"` HTML attribute to the `<section>` DOM element. For a complex array, we also need to add the `data-id` and `data-component` HTML attributes. These attributes define the unique identifier of an array item and the name of a component, respectively. We need these fields to populate for each array item at build time, so the value for both these attributes will be the templating `{block._name}`.

Here's what our layout file should look like:

File: `AboutLayout.astro`

```Astro

---
const components = {};
const componentImports = import.meta.glob("../components/**/*.astro", {
  eager: true,
});
Object.entries(componentImports).forEach(([path, obj]) => {
  const name = path.replace("../components/", "").split(".")[0];
  components[name] = obj.default;
});

const { contentBlocks } = Astro.props.frontmatter;
---

<main data-editable="array" data-prop="contentBlocks" data-id-key="_name" data-component-key="_name">
  {
    contentBlocks.map((block) => {
      const Component = components[block._name];
      return (
        <section data-editable="array-item" data-id={block._name} data-component={block._name}>
          <Component {...block} />
        </section>
      );
    })
  }
</main>

```

If we also want to visually edit the text and images inside each array item, we can define Text and Image *Editable Regions* for in each of the layout files defining our content blocks: `HeroBlock.astro`, `StatsBlock.astro`, and `ContactBlock.astro`.

Once we save and rebuild our *Site*, CloudCannon will show a yellow *Editable Regions* box around each array item, and around the content inside each array item.

We can now build pages in the Visual Editor. We can add or delete content blocks, and reorder the content blocks in the array using the options in the *Edit* menu, or the *Drag* handler.

## Common errors

If you accidentally misconfigure your *Editable Regions*, CloudCannon will display a red warning box in the Visual Editor.

Here are a few common errors you might encounter with Array *Editable Regions*:

- You did not define the `data-prop` HTML attribute.
- You did not define the `data-id-key` or `data-id` HTML attributes for a complex array.
- You cannot render new array items in the Visual Editor, because you did not define the `data-component-key` or `data-component` HTML attributes.
- The *Editable Region* has an invalid data type (e.g., your Text region has a number or object, instead of a string).
- You have one or more orphaned Array Item *Editable Regions* that are not contained within an Array *Editable Region*.

And that's it! Your *Site* is built, has output *Collections*, and you have learnt how to apply every type of *Editable Region* to enable visual editing. In the next step of this guide, we'll direct you to resources for further configuration or user guides on how to edit your files in CloudCannon.


---

---
title: Visually edit text
description: Learn how to define Source or Text Editable Regions to edit text values stored in HTML, structured data, or Markup.
url: https://cloudcannon.com/documentation/developer-guides/set-up-visual-editing/visually-edit-text/
content_type: developer guide
last_modified: 2026-04-16
---

Text is the primary content of most websites, and also the easiest value to edit visually. You can use the Source or Text *Editable Regions* to edit text values. Which one you should use will depend on where the text is stored.

Text content can be in one of three places: hard-coded in a templating file (e.g., `.astro`, `.liquid`, etc), stored in a structured data key and referenced by templating in a layout, or in the body of your content files as Markup. In these three cases, you should use a Source *Editable Region* for the first, and a Text *Editable Region* for the second and third. Let's cover how to define these.

> **Nested text values**
> 
> To avoid `data-prop` misconfiguration errors, it is best practice to define your *Editable Regions* from the root of your file first (i.e., from parent elements to child elements). If your text values are nested inside an array or a component, you should define *Editable* *Regions* for those parent elements first. We'll cover this more in later steps of this guide.

## Hard-coded text values in templating files

Standalone pages on your website, like a "Home" or "About" page, are probably generated from a single file with HTML content and templating. These pages are often landing pages, so an accurate visual editing experience is important to help your team understand exactly what a website visitor will see.

Based on the SSG your *Site* uses, the format and extension of your files may differ (e.g., Astro uses `.astro` files, Eleventy uses `.liquid` files), but as long as they output to an HTML file after a Site build, you can still add *Editable Regions*.

Let's take a look at an example.

Here is an excerpt from the "Home" page of our website. It is mainly comprised of text inside `<h1>`, `<p>`, and `<ul>` tags, as well as an `<img>` tag.

File: `index.astro`

```Astro

<!doctype html>
<html lang="en">
  <body>
    <main>
      <img src="/cloudcannon-logo.jpg">
      <h1>Hello!</h1>
      <p>
          Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
          labore et dolore magna aliqua. Vitae ultricies leo integer malesuada nunc vel risus commodo
          viverra. Adipiscing enim eu turpis egestas pretium.
      </p>
      <p>Varius sit amet mattis vulputate enim. Habitasse platea dictumst:</p>
      <ul>
          <li>Morbi tristique senectus et netus.</li>
          <li>Id semper risus in hendrerit gravida rutrum quisque non tellus.</li>
          <li>Habitasse platea dictumst quisque sagittis purus sit amet.</li>
          <li>Tellus molestie nunc non blandit massa.</li>
          <li>Cursus vitae congue mauris rhoncus.</li>
      </ul>
    </main>
  </body>
</html>

```

This file outputs a webpage that looks like this:

![A screenshot of the home page on our Astro website shows a header image, title, and content.](/assets/external_screenshots/CloudCannon-Documentation-Visual-Editing-Guide-Home-Page.png)

In this example, we want to visually edit the title of our Home page in the Visual Editor. We can add a Source *Editable Region* to our Home page.

The text value of our page title is "Hello!" which is hard-coded in an `<h1>` tag. To define a Source *Editable Region*, we can add the `data-editable`, `data-path`, and `data-key` HTML attributes to the `<h1>` DOM element.

The `data-editable` HTML attribute defines which type of *Editable Region* you want to use. To edit text values in HTML, we want this to be `source`. The `data-path` HTML attribute defines where your data is stored which, in this case, is the path of the file: `/src/pages/index.astro`. The `data-key` HTML attribute acts as a unique identifier for an *Editable Region*, so CloudCannon knows which value to update if you have several *Editable Regions* in one file. We recommend choosing a key that provides context for which area of your code an editable region affects. In this example, we'll use the value `title`.

Here's what our Home page code should look like:

File: `index.astro`

```Astro
```

<h1 data-editable="source" data-path="/src/pages/index.astro" data-key="title">Hello!</h1> /*1*/

```

**[1]** The `data-editable` attribute defines what kind of data this element contains, the `data-path` attribute defines the path to the file we want to edit, and the `data-key` attribute defines the unique identifier for this region if there are multiple regions in the file. In this case, we want a Source *Editable Region*, so the value of `data-editable` is `source`, we want to edit the `/src/pages/index.astro` file, and the unique key is `title`.
```

Once we save and rebuild our *Site*, CloudCannon will show a yellow *Editable Region* box around the `<h1>` tag content in the Visual Editor. When you click into the *Editable Region*, you can type inline to change the value of the `<h1>` tag.

## Text values in structured data

Many of the files on your website are likely to be content files, containing structured data keys (e.g., `title`, `publish_date`, `author`) in the front matter which populate templating in a layout file at build time.

Let's take a look at an example.

This file is a blog post, containing structured data keys for `title` and `author` in the front matter, and Markdown content in the body of the file.

File: `first-post.mdx`

```markdown

---
title: 'First post'
author: 'C. Kent'
heroImage: '../../assets/blog-banner.jpg'
heroImageTitle: 'Blog gradient'
heroImageAlt: 'An eye-catching color gradient banner.'
---

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Vitae ultricies leo integer malesuada nunc vel risus commodo viverra.

```

Here is an excerpt from our blog layout file, containing HTML for the blog webpage and templating to populate elements with the values from each blog file.

File: `BlogPost.astro`

```Astro
```

---
const { title, author } = Astro.props;
---
<article>
    <div class="prose">
        <div class="title">
            <h1>{title}</h1> /*1*/
            <p>By: {author}</p> /*2*/
            <hr />
        </div>
        <slot />
    </div>
</article>

```

**[1]** This `<h1>` element surrounds the template value `{title}`. This value comes from the `title` key in the front matter of a blog file.

**[2]** This `<p>` element surrounds the template value `{author}`, prepended by the plain text "By:". This value comes from the `author` key in the front matter of a blog file.
```

> The file type for your layouts will be different depending on your SSG (e.g., Astro uses `.astro` files, Eleventy uses `.liquid` files). You can add *Editable Regions* to any of these files as long as they output to an HTML file after a *Site* build.

Together, these files output a webpage that looks like this:

![A screenshot of a blog page on our Astro website shows a header image, title, author, and content.](/assets/external_screenshots/CloudCannon-Documentation-Visual-Editing-Guide-Content-Page.png)

In this example, each blog file contains two text front matter keys we want to visually edit: `title` and `author`. We can add Text *Editable Regions* to the blog layout file to enable visual editing for these text values in the entire *Collection*.

Let's start with `title`.

The `title` key in the front matter of each blog file populates the `{title}` templating field in our blog layout, which is inside an `<h1>` tag. To define a Text *Editable Region*, we can add the `data-editable` and `data-prop` HTML attributes to the `<h1>` DOM element. In this case, the value of `data-editable` should be `text`, as we want to edit a text value stored outside of the blog layout. The `data-prop` HTML attribute defines where your data is stored which, in this case, will be the `title` front matter key.

Here's what our blog layout code should look like:

File: `BlogPost.astro`

```Astro
```

<h1 data-editable="text" data-prop="title">{title}</h1> /*1*/

```

**[1]** The `data-editable` attribute defines what kind of data this element contains, and the `data-prop` attribute defines the path to the data we want to edit. In this case, we want a Text *Editable Region*, so the value of `data-editable` is `text`, and we want to edit the `title` structured data key in the file front matter.
```

Adding a Text *Editable Region* for `{author}` is slightly more complicated.

The `author` key in the front matter of each blog file populates the `{author}` templating field in our blog layout, which is inside an `<p>` tag. The `{author}` templating field is not the only content inside the `<p>` tag: the plain text "By:" prepends the author value. If we added `data-editable="text" data-prop="author"` to the `<p>` tag in our blog layout, the Visual Editor would re-render the field to only show the value of `author`, hiding the plain text.

It is important to note that Text *Editable Regions* don't modify the code in your layout file, so the "By:" plain text is not destroyed. Instead, they update the value of the front matter key and re-render the webpage preview in the Visual Editor. This leads to a mismatch in the appearance of the built *Site*, which includes "By:" before the author name, and the preview in the Visual Editor, which would not.

To avoid this issue, we can use the web component `<editable-text>` instead. The `<editable-text>` web component replaces the need for the `data-editable="text"` attribute, telling CloudCannon what type of data we are editing. This is useful if you want to edit an element that can't take attributes, or a specific section of a string.

We can add the `data-prop="author"` attribute to this web component.

Here's what our blog layout code should look like:

File: `BlogPost.astro`

```Astro
```

<p>By: <editable-text data-prop="author">{author}</editable-text></p> /*1*/

```

**[1]** The `<editable-text>` web component defines what kind of data this element contains, and the `data-prop` attribute defines the path to the data we want to edit. In this case, we used the web component to wrap the `{author}` templating specifically, and we want to edit the `author` structured data key in the file front matter.
```

Once we save and rebuild our *Site*, CloudCannon will show yellow boxes around the title and author fields on the webpage, indicating *Editable Regions* in the Visual Editor. You can edit the text value of `title` and `author` inline on the page when you click into the *Editable Region*.

![A screenshot of the Visual Editor shows yellow Editable Regions boxes around the title and author fields on the webpage.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Visual-Editor-Frontmatter-Text-Editable-Regions.webp)

## Markdown text

The majority of the text content on your website is likely to be Markdown in the body of your content files. This is also the text value that content teams will edit most often, such as when writing a new blog or updating a product description. The Markdown content of your content file will populate an element in your layout file at build time (e.g., in Astro, Markdown will populate the `<slot />` element, but other SSGs may use different syntax).

Let's take another look at the above example.

File: `first-post.mdx`

```markdown

---
title: 'First post'
author: 'C. Kent'
heroImage: '../../assets/blog-banner.jpg'
heroImageTitle: 'Blog gradient'
heroImageAlt: 'An eye-catching color gradient banner.'
---

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Vitae ultricies leo integer malesuada nunc vel risus commodo viverra.

```

File: `BlogPost.astro`

```Astro
```

---
const { title, author } = Astro.props;
---
<article>
    <div class="prose">
        <div class="title">
            <h1>{title}</h1>
            <p>By: {author}</p>
            <hr />
        </div>
        <slot /> /*1*/
    </div>
</article>

```

**[1]** This `<slot />` element marks where the markup content from a blog file will go.
```

We should still use a Text *Editable Region* to visually edit the Markdown content, so the value is stored outside of the blog layout. However, because `<slot />` is not a DOM element, we can't add the `data-editable` and `data-prop` attributes directly. Just like the `author` example above, we can wrap the `<slot />` element in a `<editable-text>` web component, which can take attributes.

The `<editable-text>` web component replaces the need for `data-editable`. In this case, there are no front matter keys we can reference with `data-prop` to tell CloudCannon where the data is stored. Instead, we can use the special value `@content` to specify Markdown content in the body of a content file.

Here's what our blog layout code should look like:

File: `BlogPost.astro`

```Astro
```

<editable-text data-prop="@content"> /*1*/
    <slot />
</editable-text>

```

**[1]** The `<editable-text>` web component defines what kind of data this element contains, and the `data-prop` attribute defines the path to the data we want to edit. In this case, we used the web component to wrap the `<slot />` element, which will be populated by Markdown content at build time, and we want to edit the Markdown content of the file, as signified by the special value `@content`.
```

Once we save and rebuild our *Site*, CloudCannon will show a yellow *Editable Region* box around the content on the webpage. When you click into the *Editable Region*, CloudCannon will also display a WYSIWYG toolbar for formatting your content.

![A screenshot of the Visual Editor shows a yellow Editable Regions box around the blog content and a WYSIWYG toolbar.](https://cc-screenshots.imgix.net/main_ac5b6387f7704da1f27d36a158c4eb2419a7854e/CloudCannon-Documentation-Visual-Editor-Content-Text-Editable-Region.webp)

## Rich text formatting options

When you click into an *Editable Region* for a text value, sometimes the Visual Editor will display a WYSIWYG toolbar with rich text formatting options. CloudCannon determines whether your text value is rich text automatically, but you can also define this behavior manually using the `data-type` HTML attribute.

File: `BlogPost.astro`

```Astro
```

<p>By: <editable-text data-prop="author" data-type="">{author}</editable-text></p> /*1*/

```

**[1]** The `<editable-text>` web component defines what kind of data this element contains, and the `data-prop` attribute defines the path to the data we want to edit. In this case, we used the web component to wrap the `{author}` templating specifically, and we want to edit the `author` structured data key in the file front matter.
```

The `data-type` attribute accepts three values: `span`, `text`, or `block`. Setting `data-type` as `span` does not allow any rich text formatting (i.e., plain, inline text), while `text` allows paragraph-level rich text, with a WYSIWYG toolbar containing formatting tools such as bold, italics, and links. Setting `data-type` to `block` allows all rich text formatting options, from paragraph-level to block-level formatting like lists, block-quotes, images, snippets, and text styling.

> If you want to specify exactly which formatting tools are available, you can manually define your WYSIWYG toolbar under the `_editables` key in your CloudCannon Configuration File. For more information, please read our documentation on [Configuring your rich text editors](/documentation/developer-articles/configure-your-rich-text-editors/#editable-regions).

Not all text values need rich text formatting options, and, in some cases, adding rich text formatting to an element that can only support plain text can be destructive to your content and HTML. When `data-type` is not defined, CloudCannon will determine an appropriate default value using the following process.

![An illustration of the flowchart CloudCannon uses to decide if rich text formatting is appropriate for an element.](assets/diagrams/CloudCannon-Documentation-Editables-Data-Type-Flowchart.png)

To begin, CloudCannon determines whether the Editable is for content or front matter. Content is any Source *Editable Region* (i.e., `data-attribute="source"` or `<source-editable>`), or Text *Editable Region* where `data-prop="@content"`. Front matter is any Text Editable where `data-prop` is set to a structured data key.

If the *Editable Region* is for content, CloudCannon will use either `text` or `block` as the default value of `data-type`, as the content is likely to need rich text formatting. Whether paragraph-level rich text formatting or all rich text formatting options are available will depend on the HTML element in the output file(e.g., `<h1>` elements can only support `text` level formatting, while `<div>` elements can support `block` level formatting).

If the *Editable Region* is for a value stored in front matter, CloudCannon will determine whether you have [input configuration](/documentation/user-articles/what-are-inputs/) for that front matter key. If you do not, CloudCannon will use `data-type="span"` by default. Similarly, if you do have input configuration, but the input type is not defined as rich text (i.e., `markdown` or `html`), CloudCannon will use `data-type="span"` by default.

If your front matter key is configured as a rich text input, CloudCannon will use either `text` or `block` as the default value of `data-type`, whichever is appropriate for the HTML element in the output file.

## Common errors

If you accidentally misconfigure your *Editable Regions*, CloudCannon will display a red warning box in the Visual Editor.

Here are a few common errors you might encounter with Source and Text *Editable Regions*:

- You did not define the `data-path` or `data-key` HTML attribute for your Source *Editable Region*, or the `data-prop` HTML attribute for your Text *Editable Region*.
- The file path defined by `data-path` does not exist.
- The *Editable Region* has an invalid data type (e.g., your Text region has a number or object, instead of a string).
- You have an unsupported value for `data-type`. It must be `span`, `text`, or `block`.
- There are Source *Editable Regions* with the same `data-key` value. This value should be unique.
- Your Text *Editable Region* contains nested HTML elements.

> Do not nest any other *Editable Regions* inside a Source *Editable Region*.

In the next step of this guide, we'll cover how to define *Editable Regions* for image values stored in structured data.


---

---
title: Introduction
description: Learn how to use the CloudCannon imgix integration with an Amazon S3 digital asset manager.
url: https://cloudcannon.com/documentation/developer-guides/imgix-guide/
content_type: developer guide
last_modified: 2026-04-16
---

No one likes slow web pages. Images and videos on your website can contribute to long loading times and negatively affect your user experience. Image and video content can also contribute to long build times in CloudCannon. Storing large visual files in your Git repository will quickly increase its size, which can affect your Site's performance.

It is important to deliver high-quality, optimized visual content on your website while minimizing the wait time for your users. For Sites with many large files, we recommend using an external Digital Asset Manager (DAM) and a content optimization tool. In this guide, we will teach you how to connect an Amazon S3 DAM and imgix to your CloudCannon Site.

Amazon Simple Storage Service ([Amazon S3](https://aws.amazon.com/s3/)) is a cloud asset storage solution. [imgix](https://www.imgix.com/) is an image and video processing tool that integrates with your Amazon S3 DAM and CloudCannon. By using an Amazon S3 DAM and imgix, you can:

- Improve your Site build times.
- Use the same assets across Sites with different Git repositories.
- Serve optimal-sized assets depending on your user's device and internet connection.
- Keep the assets in your S3 bucket private.

This guide assumes you already have imgix and AWS S3 accounts, as well as a CloudCannon Site and an Amazon S3 bucket. To create an Amazon S3 bucket, please read the [AWS documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html).


---

---
title: Connect imgix to your S3 bucket
description: Learn how to connect IMGIX to your Amazon S3 DAM.
url: https://cloudcannon.com/documentation/developer-guides/imgix-guide/connect-imgix-to-your-s3-bucket/
content_type: developer guide
last_modified: 2026-04-16
---

> Earlier in this guide, you created two S3 users. In this step, make sure to use the *Access Key ID* and *Secret Access Key* from the "S3-to-imgix" user when you connect your Amazon S3 DAM to imgix.

Although some integrations require your S3 bucket to be public, imgix does not. imgix connects to your DAM using the S3 user credentials created in the previous step, so you can keep your S3 bucket private.

For more information about connecting a source to imgix, please see their [documentation](https://docs.imgix.com/getting-started/setup/creating-sources/amazon-s3).

In this step, you will connect imgix to your S3 bucket.

1. Navigate to the [Sources page](https://dashboard.imgix.com/sources) in the imgix dashboard.
2. Click the New Source button.
3. Select *Amazon S3* from the DAM options.
4. Click the *Continue* button.
5. Enter the *Access Key ID* and *Secret Access Key* from your IAM user in the *IAM Access Key* and *IAM Access Secret* fields, respectively. If you created two users earlier in this guide, select the keys from the "S3-to-imgix" user.
6. Enter the *Bucket Name* and the *Path Prefix*, if you created one.
7. Click the *Continue* button.
8. Enter a name in the *imgix Subdomain* field for your imgix Base URL. This must be globally unique and cannot be reused.
9. Click the *Deploy Source* button.


---

---
title: Create IAM policies
description: Learn how to edit your Identity and Access Management policies to allow CloudCannon and imgix to interact with your S3 bucket.
url: https://cloudcannon.com/documentation/developer-guides/imgix-guide/create-iam-policies/
content_type: developer guide
last_modified: 2026-04-16
---

Identity and Access Management (IAM) policies determine what actions are allowed for content in your S3 bucket. We must create policies to allow CloudCannon and imgix to perform specific actions for your bucket and any object stored within it. CloudCannon requires permission to upload, edit, and preview your assets, while imgix only requires permission to read and list content from your S3 bucket in order to serve your assets.

For more information about Amazon S3 policies, please see their [documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-policy-language-overview.html).

In this step, you will create two policies, one for CloudCannon and one for imgix.

1. Open the AWS console and navigate to *IAM* under *Security, Identity, & Compliance* section in the main menu.
2. Navigate to *Policies* under *Access management*.
3. Click the *Create Policy* button.
4. Open the *JSON* tab of the new policy and paste the following JSON code. Make sure to replace “PlaceholderBucketName” with your S3 bucket name.

File: `policy.json`

```JSON
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetBucketLocation",
        "s3:GetObjectAcl",
        "s3:GetObject",
        "s3:ListBucketMultipartUploads",
        "s3:AbortMultipartUpload",
        "s3:ListBucket",
        "s3:PutObjectAcl",
        "s3:ListMultipartUploadParts"
      ],
      "Resource": [
        "arn:aws:s3:::<PlaceholderBucketName>",
        "arn:aws:s3:::<PlaceholderBucketName>/*"
      ]
    }
  ]
}
```

5. Click the *Next: Tags* button, then click *Next* again.
6. Name your policy “CloudCannon Access Policy”, then click *Create policy*.
7. Repeat steps 3 to 5 and paste the following JSON code. Make sure to replace “PlaceholderBucketName” with your S3 bucket name.

File: `policy.json`

```JSON
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetBucketLocation",
        "s3:GetObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::<PlaceholderBucketName>",
        "arn:aws:s3:::<PlaceholderBucketName>/*"
      ]
    }
  ]
}
```

8. Name your policy “imgix Access Policy”, then click *Create policy*.


---

---
title: S3 and imgix best practice
description: Learn about creating separate users and policies for access to your S3 content.
url: https://cloudcannon.com/documentation/developer-guides/imgix-guide/s3-and-imgix-best-practice/
content_type: developer guide
last_modified: 2026-04-16
---

To connect your S3 bucket to imgix or CloudCannon, you must create an S3 policy and user.

- **IAM Policy** — Determines what actions are allowed for content in your S3 bucket.
- **IAM User** — Has an Access Key ID, Secret Access Key, and Policy. Any software with this user’s keys can perform the actions permitted in the user’s policies.

CloudCannon, imgix, and AWS strongly recommend creating separate users for different tasks. This follows the principle of least privilege.

In this guide, you will create two users: one from CloudCannon to S3 and one from S3 to imgix. We recommend naming these users some variant of “CloudCannon-to-S3” and “S3-to-imgix”. As CloudCannon and imgix require different permissions, we recommend creating separate policies. This ensures that CloudCannon can upload to your S3 DAM and preview your assets, while imgix only has the permissions required to serve your assets.

> It is not necessary to create two users; one user will work. If you only want to create one user and one policy:
> 
> - In Step Four of this guide, create the first policy, "CloudCannon Access Policy." You can rename this policy.
> - In Step Five of this guide, create one user and assign your single policy. You can rename this user.
> - In Steps Six and Seven of this guide, use your single user's Access Key ID and Secret Access Key to give imgix and CloudCannon the same access to your S3 content.


---

---
title: Create IAM users
description: Learn how to create IAM users for your Amazon S3 DAM.
url: https://cloudcannon.com/documentation/developer-guides/imgix-guide/create-iam-users/
content_type: developer guide
last_modified: 2026-04-16
---

Identity and Access Management (IAM) users determine which services can access the content in your S3 bucket. Each user has three important components: an Access Key ID, a Secret Access Key, and a Policy. You created two policies in the previous step of this guide, one for CloudCannon and one for imgix.

Any software with the Access Key ID and Secret Access Key of an S3 user will be allowed to access the assets in your S3 DAM according to that user’s policies. You can view the Access Key ID for your S3 users any time, but the Secret Access Key is only visible during user creation.

> Take note of your Access Key IDs and Secret Access Keys for each user. Once you leave the *Create user* page, you cannot view the secret key again. You can [recreate your Access Key ID and Secret Access Key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys_retrieve.html) if you lose it. You can have a maximum of two access keys per user.

In this step, you will create two users and attach a policy to each.

1. Open the AWS console and navigate to *IAM* under the *Security, Identity, & Compliance* section in the main menu.
2. Navigate to *Users* under *Access management*.
3. Click the *Add Users* button.
4. Name the user “CloudCannon-to-S3”.
5. Set the *AWS credential type* as” Access key - Programmatic access”.
6. Click the *Next: Permissions* button.
7. Click *Attach existing policies directly* and select the “CloudCannon Access Policy” policy you created earlier.
8. Click the *Next: Tags* button, then the *Next: Review* button.
9. Click *Create user*.
10. Repeat steps 3 to 9 to create a second user. Name the user “S3-to-imgix” and select the “imgix Access Policy” you created earlier.


---

---
title: Edit your Cross-Origin Resource Sharing permissions
description: Learn how to edit your Cross-origin resource sharing settings to allow CloudCannon to interact with your S3 bucket.
url: https://cloudcannon.com/documentation/developer-guides/imgix-guide/edit-your-cross-origin-resource-sharing-permissions/
content_type: developer guide
last_modified: 2026-04-16
---

Cross-origin resource sharing (CORS) defines how web applications in one domain can interact with resources in a different domain. To allow CloudCannon to interact with your S3 bucket, you must explicitly enable cross-origin requests.

In this step, you will edit your CORS permissions.

1. Open AWS and select your S3 bucket.
2. Open the *Permissions* tab, scroll to the *Cross-origin resource sharing (CORS)* section, and click *Edit*.
3. Copy the following JSON code into your CORS settings.

File: `CORS.json`

```json
[
  {
    "AllowedHeaders": [
      "*"
    ],
    "AllowedMethods": [
      "GET",
      "PUT",
      "POST",
      "DELETE",
      "HEAD"
    ],
    "AllowedOrigins": [
      "*"
    ],
    "ExposeHeaders": []
  }
]
```

4. Click save.

The above code does not restrict which URLs are allowed to access your S3 bucket. As an optional extra step, you can edit the `AllowedOrigins` key to restrict access to your Sites. Origins can match a single URL, such as `https://my-site.com`, or multiple URLs using wildcard characters, `https://*.my-site.com`.

If you edit your `AllowedOrigins` you must also include `https://app.cloudcannon.com`, to ensure that CloudCannon can upload to your bucket and pull previews of your assets within the editor.

Here is an example:

File: `CORS.json`

```json
"AllowedOrigins": [
  "https://*.my-site.com",
  "https://app.cloudcannon.com"
]
```


---

---
title: Connect your S3 bucket to CloudCannon
description: Learn how to connect your Amazon S3 DAM to your CloudCannon Site.
url: https://cloudcannon.com/documentation/developer-guides/imgix-guide/connect-your-s3-bucket-to-cloudcannon/
content_type: developer guide
last_modified: 2026-04-16
---

> Earlier in this guide, you created two S3 users. In this step, make sure to use the *Access Key ID* and *Secret Access Key* from the "CloudCannon-to-S3" user when you connect your Amazon S3 DAM to CloudCannon.

In this step, you will connect CloudCannon to your S3 bucket.

1. Open the *Assets* page under *Site Settings*.
2. Select the *New DAM* option in the *Link DAM* dropdown menu.
3. Select the *Amazon S3* option in the *DAM provider* dropdown menu.
4. Enter a name to identify your DAM in CloudCannon.
5. Set the *Base URL* to the IMGIX base URL.
6. Set the *S3 Bucket Name* to the name of your bucket in S3.
7. Select the same *AWS Region* as your S3 bucket.
8. Enter the *Access Key ID* and *Secret Access Key* from your IAM user in the *IAM Access Key* and *IAM Access Secret* fields, respectively. If you created two users earlier in this guide, select the keys from the "CloudCannon-to-S3" user.
9. Click the *Authenticate* button to save and close the modal.
10. Click the *Link DAM* button.

IMGIX and your S3 bucket are now connected to your CloudCannon Site.

You can optionally set an *Extra Prefix* for your DAM. An extra prefix prepends a specific string to all asset paths, affecting all assets you upload to your DAM from this Site and the DAM browser in CloudCannon. This is useful if you want to ensure that your Site can only interact with a specific folder in your DAM.

To configure an *Extra Prefix,* navigate to the *Assets* page under *Site Settings*, click on the *Context Menu* for your linked Amazon S3 DAM, and select *Settings* from the menu. Enter the prefix in the *Extra prefix* field.


---

---
title: Introduction
description: Discover our recommended best practices for integrating multilingual Hugo sites.
url: https://cloudcannon.com/documentation/developer-guides/hugo-multilingual/
content_type: developer guide
last_modified: 2026-04-16
---

Hugo has two approaches to manage translated content with files:

- including the language code in the **filename**, or
- including the language code in the **content directory/folder**.

Note that Hugo does not support using both approaches at the same time.

Because CloudCannon collections are based around folders, the approach you choose will change the editing experience. This guide outlines the best practices for each approach.

> This guide focuses on integrating with CloudCannon, it does **not** cover:
> 
> - Setting up a [multilingual Hugo](https://gohugo.io/content-management/multilingual/) site; we recommend [Hugo Multilingual Part 1: Content translation](https://www.regisphilibert.com/blog/2018/08/hugo-multilingual-part-1-managing-content-translation/) by Régis Philibert.
> - The Hugo `i18n` shortcode, which could be added as a [Snippet](/documentation/developer-articles/snippets-using-hugo-shortcodes/).
> - [Multihost](https://gohugo.io/content-management/multilingual/#configure-multilingual-multihost) introduces editing problems as a site on CloudCannon uses one domain. Using multiple sites in a staging-production workflow can work around this.


---

---
title: Translation by filename
description: Managing multilingual Hugo sites translated by filename.
url: https://cloudcannon.com/documentation/developer-guides/hugo-multilingual/translation-by-filename/
content_type: developer guide
last_modified: 2026-04-16
---

This approach is similar to a non-multilingual configuration. Related content stays together, making it easier to see inconsistencies across languages. However, it may be harder to find or distinguish specific files.

Hugo calls this [Translation by filename](https://gohugo.io/content-management/multilingual/#translation-by-filename). You will need to specify a language per file, as an extension prefix (e.g. `content/blog/my-post.es.md`).

The best practice here is to **define a collection for each folder of related files** (e.g. Posts, Pages, Staff Members). Each collection contains the files from all languages.

You'll need a custom [create path](/documentation/developer-articles/set-the-path-for-new-files/) here to include the language code in new filenames.

Here's an example with Pages and Posts:

```
├── ```
├── content
│   ├── about.md
│   ├── about.es.md
│   ├── about.fr.md
│   └── blog
│       ├── first-post.md
│       ├── first-post.es.md
│       └── first-post.fr.md
└── ```
```

File: `cloudcannon.config.yml`

```YAML
```
collections_config:
  pages:
    path: content
    filter___1___: strict
  posts:
    paths: content/blog
    create___2___:
      path: '[relative_base_path]/{title|slugify}{suffix}.md'
      extra_data:
        dot: '.'
        suffix: '{dot|if=language}{language|lowercase}'
      _inputs:
        language___3___:
          type: select
          options:
            allow_empty: true
            value_key: lang_code
            values:
              - name: English
                lang_code:
              - name: Spanish
                lang_code: es
              - name: French
                lang_code: fr
```

**[1]** When you browse a collection in CloudCannon, all files within that folder will be shown by default.
Applying the `strict` filter to a collection instead limits the UI to show only the files that exactly match that collection.

In this case, it prevents files from the Posts collection in the `content/blog/` subdirectory
from appearing when browsing the `pages` collection.

**[2]** The [create option](/documentation/developer-articles/set-the-path-for-new-files/) controls the filename and path when creating new content files.

Placeholders are specified inside curly braces, and editors will be prompted to supply values for them when saving the file for the first time.
If the placeholders share names with top level inputs in your front matter, editing them in the prompt also changes those values in the file contents.

In this case, editors will be prompted to add a `title` and `language` when saving the file for the first time.

When "English" is chosen, no language code is added to the filename - in this example English is the default language, and Hugo has no extra filename suffix for the default language.

**[3]** This `_inputs` entry restricts the language editors can choose to one of the specified languages. `language` would be a text input without this, which would work but is more prone to errors.

By selecting from a list of objects and setting the `value_key`, we allow the editor to select the option "English" while saving an empty value.
```


---

---
title: Translation by content directory
description: Managing multilingual Hugo sites translated by content directory/folder.
url: https://cloudcannon.com/documentation/developer-guides/hugo-multilingual/translation-by-content-directory/
content_type: developer guide
last_modified: 2026-04-16
---

This approach separates all languages, which can make it easier to find specific files. More configuration entries are required, however, resulting in a longer site navigation.

Hugo calls this [Translation by content directory](https://gohugo.io/content-management/multilingual/#translation-by-content-directory). Your files will be placed inside a top-level content folder for each language (e.g. `content/es/posts/my-post.md`).

The best practice here is to **define a collection per language and folder of related files** (e.g. Pages EN, Pages ES, Pages FR, Posts EN, Posts ES, Posts FR).

Here's an example with Pages and Posts:

```
├── ```
├── content
│   ├── en
│   │   ├── about.md
│   │   └── blog
│   │       └── first-post.md
│   ├── es
│   │   ├── about.md
│   │   └── blog
│   │       └── first-post.md
│   └── fr
│       ├── about.md
│       └── blog
│           └── first-post.md
└── ```
```

File: `cloudcannon.config.yml`

```YAML
```
collections_config:
  pages_en:
    name: Pages EN
    icon: wysiwyg
    path: content/en
    parse_branch_index___1___: true
    filter___2___: strict
  pages_es:
    name: Pages ES
    icon: wysiwyg
    path: content/es
    parse_branch_index___1___: true
    filter___2___: strict
  pages_fr:
    name: Pages FR
    icon: wysiwyg
    path: content/en
    parse_branch_index___1___: true
    filter___2___: strict
  posts_en:
    name: Posts EN
    icon: event_available
    paths: content/en/blog
  posts_es:
    name: Posts ES
    icon: event_available
    paths: content/es/blog
  posts_fr:
    name: Posts FR
    icon: event_available
    paths: content/fr/blog
```

**[1]** The `parse_branch_index` option is specific to Hugo sites on CloudCannon, and affects what collection `_index.*` files get assigned to.
By default these files do not get assigned to the closest collection, as they usually represent the landing pages of your site.
As such, they will be assigned to the global `pages` collection unless otherwise configured.

If a collection is tagged as `parse_branch_index: true`, any `_index.*` files in the collection path (and subdirectories) will be assigned
to it.

In this case, we want the `content/*/blog/_index.md` files to be in the `pages_*` collection for their language,
rather than in the global `pages` collection, or the inner `posts_*` collection.

**[2]** When you browse a collection in CloudCannon, all files within that folder will be shown by default.
Applying the `strict` filter to a collection instead limits the UI to show only the files that exactly match that collection.

In this case, it prevents files from the `posts_*` collections in the `content/*/blog/` subdirectories
from appearing when browsing the `pages` collection for that language.
```


---

---
title: Introduction to Bookshop with Astro
description: Learn how to build a live-editable website using Astro and Bookshop on CloudCannon.
url: https://cloudcannon.com/documentation/developer-guides/bookshop-astro-guide/
content_type: developer guide
last_modified: 2026-04-16
---

Welcome to the guide for setting up an Astro website using Bookshop. Through this guide, we'll cover what Bookshop is and what it brings to the table, how to integrate it into an Astro website, and how to connect everything together to produce a fully static website that can be edited live in the browser using CloudCannon.

> Bookshop added experimental support for Astro in version **3.6.0**.
> 
> Please open an issue on the [Bookshop GitHub repository](https://github.com/CloudCannon/bookshop/issues) if you encounter any trouble when integrating your site.

## What is Bookshop?

Bookshop is a collection of tooling that provides a component development workflow for static websites, and aids in the creation of a page-building interface in the CloudCannon CMS.

Bookshop is fully open-source and is available on GitHub at [CloudCannon/bookshop](https://github.com/CloudCannon/bookshop/). As a tool that integrates into your codebase, we want to ensure you aren't vendor-locked to our platform. Sites built using Bookshop remain fully portable and can be built or hosted anywhere on the web.

## What does Bookshop bring to Astro?

For developers working locally, Bookshop first provides an Astro integration that is used to live update your components. When dealing with your components, this integration provides a `bookshop:live` directive to mark a component for live editing. The `bookshop:live` directive can be added to any component referenced from an Astro template. This looks like:

File: `src/pages/index.astro`

```astro
<Hello bookshop:live text="My title text" />
```

We'll cover more about components in another chapter; for now, the important thing to know is that Bookshop components can be written using either Astro or React and, in most cases, can directly use your existing templating.

Another tool that Bookshop provides is the Bookshop Component Browser. This allows you to view and test your components locally without adding them to pages on your site.

## What does Bookshop bring to CloudCannon?

Once you have connected your site to CloudCannon, Bookshop's live editing features use your component files to generate CloudCannon configuration as part of your site build. Under the hood Bookshop creates [CloudCannon Structures](/documentation/developer-articles/what-is-a-structure/) for each of your components, allowing your team to add and remove component objects in the CMS.

Next, when your site is loaded into CloudCannon's Visual Editor, an additional Bookshop script is loaded. This script loads your component files into the browser, alongside a Bookshop engine that understands Astro and React components. Using this, Bookshop can subscribe to data in the CMS using the [CloudCannon Visual Data Preview API](/documentation/developer-articles/what-are-visual-data-previews/) to render changes to your components live on the page.

Finally, after rendering components, the Bookshop script tags them with [CloudCannon Visual Data Bindings](/documentation/developer-articles/what-are-visual-data-bindings/). These data bindings allow you to click on elements directly in the Visual Editor and add, edit, or rearrange them visually.


---

---
title: Component Preview Thumbnails
description: Show previews of your components in the CMS component picker
url: https://cloudcannon.com/documentation/developer-guides/bookshop-astro-guide/thumbnails/
content_type: developer guide
last_modified: 2026-04-16
---

When an editor is selecting a component in CloudCannon,
the icon from the component spec is used as the default thumbnail:

File: `hero.bookshop.yml`

```yaml
spec:
  icon: nature_people #*
```

You can provide a custom image to use instead by placing a matching `<component>.preview.<format>`
file in your component directory. This will only be shown when adding new components to a page:

```
├── ```
├── src
│   └── components
│       └── hero
│           ├── hero.bookshop.yml
│           ├── hero.astro
│           └── hero.preview.png
└── ```
```

You can also specify a `<component>.icon.<format>` file, which will be shown alongside existing components
in CloudCannon's array view:

```
├── ```
├── src
│   └── components
│       └── hero
│           ├── hero.bookshop.yml
│           ├── hero.astro
│           └── hero.icon.svg
└── ```
```


---

---
title: Using Bookshop components
description: Using your Astro Bookshop components on your site
url: https://cloudcannon.com/documentation/developer-guides/bookshop-astro-guide/using-components/
content_type: developer guide
last_modified: 2026-04-16
---

Using a Bookshop component on your Astro site is similar to using a regular component, with a few differences.

## The Bookshop component directive

The Bookshop integration provides a `bookshop:live` for use in your Astro template files.

If you've been following along with this guide, add the following snippet to a page to use the sample component we created:

File: `src/pages/index.astro`

```astro
---
import Sample from '../components/sample/sample.astro'
---
<Sample bookshop:live text="Hello from the sample component" />
```

This matches the standard syntax for using a component in an Astro file, but with the added `bookshop:live` directive. Bookshop processes components with this directive at build time to set up live visual editing and visual data bindings.

The `bookshop:live` directive can only be used in Astro templates, but there are no limitations on where those templates can be located. For example, you could enable live editing for a component only within a certain layout or parent component. You can also add the `bookshop:live` directive to React components imported in your Astro templates.

Like other Astro directives, the `bookshop:live` directive must be visible at compile time. So if you're using the spread syntax for your component's props, you must add the directive separately from the object being spread otherwise Bookshop will be unable to process that component.

An example of using the `bookshop:live` directive with the spread syntax might look like this:

File: `src/pages/page.astro`

```astro
---
import Sample from '../components/sample/sample.astro';

const props = { /* ... */ };
---
<Sample bookshop:live {...props} />
```

You can find more information on template directives and how to use them at Astro's [template directives reference documentation](https://docs.astro.build/en/reference/directives-reference).

## Rendering dynamic components

The `bookshop:live` directive can also be applied to components with dynamic values. This means if you have a variable list of component names and you want to render all of them with Bookshop you can use this:

File: `src/pages/page.astro`

```astro
```
---
const componentData = [
  {
    _bookshop_name: "hero", //1
    title: "Hello World",
    subtext: "My page hero contents",
    image: "/image.png"
  }
];

const components = import .meta.glob("../components/**/*.astro", {
  eager: true,
});

---

<main>
  {componentData.map((block) => {
    const name = `../components/${block._bookshop_name}.astro`;
    const Component = components[name].default;
    return <Component bookshop:live {...block} />;
  })}
</main>

```

**[1]** Later in this guide, we'll cover creating CloudCannon Structures from your Bookshop components.
When doing so, the generated Structures will automatically include this `_bookshop_name` value for you to use.
```

## Passing Data to Bookshop Components

To live edit Bookshop components, Bookshop needs to know which data comes from the page front matter,
and a clear path between a component and the front matter data it draws from.

The front matter data is always assumed to come from the `Astro.props.frontmatter` variable. This means Bookshop
will automatically work for Markdown pages using layouts. Instead, if you're using an Astro template, you
need to assign the front matter prop yourself.

Here's an example of a page that loads its content using static paths:

File: `src/pages/page.astro`

```astro
---
import { getCollection } from "astro:content";
import Page from '../components/page.astro';

export async function getStaticPaths() {
  const pages = await getCollection("pages");
  return pages.map((page) => {
    return { params: { slug }, props: { frontmatter: page.data } };
  });
}

const page = Astro.props.frontmatter;
---

<Page bookshop:live {...page} />

```

Once you have defined your front matter data, Bookshop should be able to track the flow of data to the component that uses it through most reassignments and functions. However, if your data is not detected correctly, you should move the logic that operates on that data as close as possible to where that data is used.


---

---
title: Live Editing Fallbacks
description: Add custom handling for components that cannot be visually edited
url: https://cloudcannon.com/documentation/developer-guides/bookshop-astro-guide/live-fallbacks/
content_type: developer guide
last_modified: 2026-04-16
---

Some components will never be editable without the full context of your Astro site. For example,
if you rely heavily on a package without browser support or access file and network resources directly.

In these cases, you'll need to provide fallback content for Bookshop to use or opt out of live previews
for a set of components altogether.

## Rendering different content when live editing

Bookshop sets a global flag when rendering your components in the Visual Editor. Using this flag
you can show extra information to your editors or render fallback content instead of unsupported templating.

File: `components/sample/sample.astro`

```astro
{ 
  ENV_BOOKSHOP_LIVE
    ? <>
        <p>I am being edited live!</p>
        <h1>Fallback Title</h1>
      </> 
    : <>
        <p>Standard build output</p>
        <h1>{ serverOnlyFunction() }</h1>
      </>
}
```

With the above component, your production-hosted site will contain `Standard build output` and the output
of the `serverOnlyFunction` function. Only when inside CloudCannon's Visual Editor, where `serverOnlyFunction` does not exist,
will your editors see the `Fallback Title` branch of the template.


---

---
title: Configuring live editing
description: Connecting Bookshop to CloudCannon's live editing
url: https://cloudcannon.com/documentation/developer-guides/bookshop-astro-guide/configuring-live-editing/
content_type: developer guide
last_modified: 2026-04-16
---

Bookshop can render changes to your components live in CloudCannon, allowing you to build rich visual editing experiences.

## Installing Bookshop's development dependencies

To power the live editing experience, Bookshop depends on a few extra packages. Unlike the previous integration we installed, these dependencies have no impact on your production site: they only provide Bookshop tooling locally on your machine and within the CloudCannon Visual Editor.

File: `Command line`

```bash
```
         #1
npm i -D --save-exact @bookshop/generate @bookshop/browser @bookshop/astro-engine
```

**[1]** Bookshop releases all packages on every release, so the version numbers should
always stay the same. Using `--save-exact` here means that npm won't use a newer version
than the one specified.
```

## Running the Bookshop generate command

Bookshop provides a command to run after your static site build. This command automatically discovers your component library and site files and connects CloudCannon's live editing APIs to the Bookshop components on your site.

Additionally, when we cover the structured data features of Bookshop, this command will create your CloudCannon Structures for you.

To run this command, add the following to a [CloudCannon postbuild script](https://cloudcannon.com/documentation/developer-articles/extending-your-build-process-with-hooks/) at the root of your repository:

File: `.cloudcannon/postbuild`

```bash
npx @bookshop/generate
```

With that in place, any Bookshop components that use data from the front matter of a page will render changes live in the Visual Editor.

Also in the Visual Editor, you will notice CloudCannon's Data Bindings have been added around your components, allowing you to click directly on the page and open an editing panel.

As an example, if we have a markdown page with front matter:

File: `src/pages/about.md`

```markdown
---
title: About
layout: ../layouts/base.astro
hero_component:
  title: On a mission to change email marketing
  description: We're here to breathe new air into email marketing and help grow your business.
  button:
    text: "Try This Free"
    link: "/signup"
---
```

And a layout that uses that front matter to render a component:

File: `src/layouts/base.astro`

```astro
---
import AboutHero from '../components/about/hero.astro'

const { frontmatter } = Astro.props;
---

<AboutHero bookshop:live {...frontmatter.hero_component}>
```

When viewed in the Visual Editor, we will be able to interact with the element directly on the page and open up an editing panel:

![An example page matching the aforementioned code block, showing a data panel open in CloudCannon's visual editor after interacting directly with a component.](assets/deprecated/sendit-data-binding.png)


---

---
title: Nesting Components
description: Nest Bookshop components and create structured data within your components
url: https://cloudcannon.com/documentation/developer-guides/bookshop-astro-guide/nesting-components/
content_type: developer guide
last_modified: 2026-04-16
---

The Bookshop `blueprint` of your component config can help configure
some advanced Structure use cases on CloudCannon.

## Nesting components

Your blueprint can reference other components and Structures, which will embed their structured data within.
For example, this saves you from having to re-define the required inputs if your `hero` component
contains an editable `button` component — using component nesting your blueprint might look like this:

File: `hero.bookshop.yml`

```yml
```
blueprint:
  hero_text: Hello World
  button: bookshop:button #1
```

**[1]** This is a string, and could also be written `button: "bookshop:button"`.
```

In this example, the button key will become an Object Structure containing the values specified in your button component blueprint.
If you desired an array of buttons, you could use the following:

File: `hero.bookshop.yml`

```yml
```
blueprint:
  hero_text: Hello World
  buttons: #1
    - bookshop:button
```

**[1]** Or more concisely, `buttons: [bookshop:button]`
```

In general, any `bookshop:<component_name>` string will be replaced with the structure of that component,
and will allow editors to add and remove that component.

## Nesting a set of components

If you're creating a layout component, you likely want to support a set of components.
For this, you can reference the keys we defined in `spec.structures`:

File: `section.bookshop.yml`

```yml
```
blueprint:
  section_label: My Section
  header: bookshop:structure:content_blocks #1
  inner_components: [bookshop:structure:content_blocks] #2
```

**[1]** The `header` key will become a single component that can be selected from the set of components tagged as `content_blocks`

**[2]** The `inner_components` key will become an array that can contain any components tagged as `content_blocks`
```

## Nesting Example

To give a concrete example, let's say we have a `hero` component:

File: `hero.bookshop.yml`

```yml
spec:
  structures: [content_blocks]

blueprint:
  hero_text: Hello World
  cta_button: bookshop:button
  column_components: [bookshop:structure:content_blocks]
```

Then our matching component template file might look like this:

File: `hero.astro`

```astro
```
---
import Button from './button.astro'

const { hero_text, cta_button, column_components } = Astro.props;
const components = import.meta.glob("./**/*.astro", {
  eager: true,
});
---
<div class="hero">
  <h1>{ hero_text }</h1>
  {cta_button && <Button {...cta_button}/>} /*1*/
  {column_components.map((block) => {
    const name = `components/${block._bookshop_name}.astro`;
    const Component = components[name].default;
    return <Component {...block} />;
  })}
</div>
```

**[1]** Object Structures in CloudCannon may be empty, as the component can be removed and replaced, so your template should check for the existence of this component.
```

## Initializing Nested Components

Nested components using the `bookshop:*` shorthand will be initialized empty by default. For example, the blueprint:

File: `hero.bookshop.yml`

```yml
blueprint:
  hero_text: Hello World
  button: bookshop:button
```

Will be initialized in CloudCannon as:

File: `page.md`

```yml
  - _bookshop_name: hero 
    hero_text: Hello World
    button:
```

Where the `button` input will provide an editor with the option to add a button component.
To instead have the button component exist on creation, you can use the syntax `bookshop:button!`:

File: `hero.bookshop.yml`

```yml
blueprint:
  hero_text: Hello World
  button: bookshop:button!
```

The same setting can be applied to a structure shorthand by specifying the component that should be initialized.
Take the following example:

File: `section.bookshop.yml`

```yml
blueprint:
  section_label: Hello World
  column_components:
    - bookshop:structure:content_blocks!(hero)
    - bookshop:structure:content_blocks!(button)
```

This will be initialized in CloudCannon as:

File: `page.md`

```yml
  - _bookshop_name: section 
    section_label: Hello World
    column_components:
      - _bookshop_name: hero
        # ... hero fields
      - _bookshop_name: button
        # ... button fields
```

Where `column_components` can be then further added to or removed from by an editor,
using components from the tagged structure.


---

---
title: Page Building
description: Use your components to visually build pages from scratch
url: https://cloudcannon.com/documentation/developer-guides/bookshop-astro-guide/page-building/
content_type: developer guide
last_modified: 2026-04-16
---

With your components live rendering and your Structures created in CloudCannon, we now have the ingredients to create a page-building experience in the CMS.

## Looping components

Once you have a few more components built out, an ideal front matter section might look like this:

File: `src/pages/index.md`

```yml
---
layout: ../layouts/PageLayout.astro
content_blocks:

  - _bookshop_name: hero
    title: Kākā
    subtitle: The New Zealand kākā is a large species of parrot

  - _bookshop_name: content
    content_markdown: >-
      The New Zealand kākā lives in lowland and mid-altitude native forest

  - _bookshop_name: image
    image_url: /uploads/Scrapping_kaka.jpg
    image_alt: The bird that screams loudest and most persistently gets to own the branch

  - _bookshop_name: stats
    length: 45cm
    weight: 452g
    color: reddish
---
```

Now we need to create a page component that loops over each item in this array and renders them on the page using the dynamic components we covered in [Using Bookshop components](/documentation/developer-guides/bookshop-astro-guide/using-components/#rendering-dynamic-components).
Instead of creating this component in our regular `src/components` directory we're going to create this component in our Bookshop shared components directory. We'll explain what this means later, but for now create a `shared/astro` directory in your `src` folder.
This directory is where we'll place all our future shared components. Next, create an empty `page.astro` component inside your `src/shared/astro` directory.

Afterward, you should have a directory structure like this:

```
├── ```
├── src
│   ├── components
│   │   └── sample
│   │       └── sample.astro
│   └── shared
│       └── astro
│           └── page.astro
└── ```
```

Now add the following code to your `page.astro` component:

File: `src/shared/astro/page.astro`

```astro
---
const { contentBlocks } = Astro.props;
const components = {};
const componentImports = import.meta.glob("../../components/**/*.astro", {
  eager: true,
});
Object.entries(componentImports).forEach(([path, obj]) => {
  const parts = path
    .replace("../../components/", "")
    .split(".")[0]
    .split("/");
  if (parts[parts.length - 1] === parts[parts.length - 2]) {
    parts.pop();
  }
  const bookshopName = parts.join("/");
  components[bookshopName] = obj.default;
});
---

<main>
  {contentBlocks.map((block) => {
    const Component = components[block._bookshop_name];
    return <Component {...block} />;
  })}
</main>

```

This example implementation loads all the Astro components in your components library and renders them according
to the `contentBlocks` array prop.

We'll also need to add a layout that passes the `content_blocks` array from the markdown to our new page component.

File: `src/layouts/PageLayout.astro`

```astro
---
import Page from '../shared/astro/page.astro';

const { frontmatter } = Astro.props;
---

<Page bookshop:live contentBlocks={frontmatter.content_blocks} />
```

Note that we don't need to add the `bookshop:live` directive to the subcomponents within a page
because the entire page component is already live rendering.

It is important to put our component loop inside another Bookshop component rather than
using it directly in our layout because Bookshop can only live render changes within
the boundaries of Bookshop components. If we look at the loop in our page component and note where
the internal live editing boundaries would be, it will look like this:

File: `src/shared/astro/page.astro`

```astro
{frontmatter.content_blocks.map((block) => {
  const name = `../components/${block._bookshop_name}.astro`;
  const Component = components[name].default;
  return <>
    {/* start live editing */}
    <Component bookshop:live {...block} />;
    {/* end live editing */}
  </>
})}
```

So if we were to use this loop directly, each component individually would update changes live,
but rearranging or adding new components wouldn't render correctly
because the outer `frontmatter.content_blocks.map` loop wouldn't get re-rendered.
Adding the loop to a page component ensures that the entire loop is contained within a live editing boundary and is re-rendered whenever components are added or moved.

## Shared Components

Earlier we introduced the `shared/astro` directory for shared components. Shared components are components
that need to re-render in the Visual Editor but aren't semantically a "component"
that an editor would add to a page. In the previous section, we made our page component a shared component
because we needed it to re-render our `content_blocks` array, but editors shouldn't be able to add page
components within a page. Apart from this distinction, these files are
functionally the same as your other components and can be imported and used the same way.

## Taking stock

With the steps taken so far, you should have the framework for a fully functional page builder, rendering live when editing on CloudCannon. Now is a great moment to jump into your codebase, start migrating some components, and experiment with the system.

The following sections of this guide will cover some of Bookshop's remaining features that can help polish the page-building experience, but aren't required while setting things up.


---

---
title: Getting set up
description: The first steps for building an Astro site with Bookshop
url: https://cloudcannon.com/documentation/developer-guides/bookshop-astro-guide/getting-set-up/
content_type: developer guide
last_modified: 2026-04-16
---

Building a site with Bookshop requires a specific directory structure that lives alongside your website, and an Astro integration to discover and use components.

> As a useful reference, the [Astro Sendit Template](https://github.com/CloudCannon/sendit-astro-template) repository
> contains an example site fully integrated with visual editing. You can browse the code
> and file structure of the template to help solidify the concepts covered in this guide.

## Prerequisites

Bookshop requires that you have Node >= 16 installed on your machine.

## Creating your Bookshop directory

Bookshop requires that your component files live in a specific directory structure, which allows for components to be discovered automatically.

The easiest way to get started is to create a `bookshop` folder containing a `bookshop.config.cjs` in your site `src` folder alongside the existing Astro `components` directory. This way Bookshop can automatically discover components from the `components` directory.

With this in mind, the basic directory structure for an Astro Bookshop site will look like this:

```
├── ```
├── public
├── src
│   ├── bookshop
│   │   └── bookshop.config.cjs
│   ├── components
│   ├── layouts
│   └── pages
├── astro.config.mjs
└── ```
```

Inside your `bookshop.config.cjs` add the following content:

File: `bookshop.config.cjs`

```javascript
// Standard bookshop configuration
module.exports = {
  engines: {
    "@bookshop/astro-engine": {}
  }
}
```

This file houses the configuration for your Bookshop project. In this case, we configure Bookshop to use the `@bookshop/astro-engine` package for any live component rendering.

## Connecting Bookshop to Astro

To connect Bookshop and Astro, install the `@bookshop/astro-bookshop` integration from npm:

**npm:**

File: `Command line`

```bash
npm i --save-exact @bookshop/astro-bookshop
```

**Yarn:**

File: `Command line`

```bash
yarn add --exact @bookshop/astro-bookshop
```

Within your Astro config, import this integration and add it to your Astro config.

File: `astro.config.mjs`

```astro
import { defineConfig } from 'astro/config';
import bookshop from '@bookshop/astro-bookshop';

export default defineConfig({
  // ...
  integrations: [bookshop()]
});
```

Now that you have Bookshop installed and your Astro site can access it, we can look at creating and using components.


---

---
title: Configuring Inputs
description: Apply CloudCannon configuration to the inputs specified in your component configuration
url: https://cloudcannon.com/documentation/developer-guides/bookshop-astro-guide/configuring-inputs/
content_type: developer guide
last_modified: 2026-04-16
---

The `_inputs` section of your Bookshop file can be used to configure the keys in your generated structures.

This configuration is scoped to the individual component,
so you can configure the same key differently across components — even
if the components are nested within one another.

File: `sample.bookshop.yml`

```yaml
blueprint:
  text: "Hello World!"
  color: "#034AD8"
  date:
  button: bookshop:button

_inputs:
  text:
    comment: "This comment will show up in the CMS"
  color:
    type: color
  date:
    instance_value: NOW
```

File: `button.bookshop.yml`

```yaml
blueprint:
  text: "Hello World!"
  color: "#034AD8"

_inputs:
  text:
    comment: "A different comment specific to the button component"
  color:
    type: select
    options:
      values:
        - "#034AD8"
        - "#403AFC"
```

Despite both components specifying `text` and `color` inputs, their input configuration is unique
and scoped to the content of each `blueprint` object.

Input configuration is passed directly to CloudCannon; see the [CloudCannon Inputs Documentation](/documentation/user-articles/what-are-inputs/) to read more.


---

---
title: Using Structures
description: Create structured, reusable data from your components
url: https://cloudcannon.com/documentation/developer-guides/bookshop-astro-guide/using-structures/
content_type: developer guide
last_modified: 2026-04-16
---

So far, we have introduced how to use components on a site and how to update them live when the front matter of a page changes. The next aspect to tackle is adding components to and removing them from a page. This is where CloudCannon Structures come into the picture.

## What are Structures?

Structures are CloudCannon's answer to structured data on static sites. You can read more about structures in [Create a structure](/documentation/developer-articles/create-a-structure/) and the [Structures reference](/documentation/developer-reference/configuration-file/types/_structures/). The main thing to know is that for Bookshop, Structures define the set of components that you can add to a specific key in CloudCannon.

## The Bookshop specification file

To start with CloudCannon Structures, we first need to add Bookshop specification files for our components. The Bookshop specification file for a component is created next to that component and has the same name. If you're following along with the guide, you can create an empty `sample.bookshop.yml` next to our sample component.

Afterward, your file structure should look like this:

```
├── ```
├── src
│   └── components
│       └── sample
│           ├── sample.astro
│           └── sample.bookshop.yml
└── ```
```

Similarly to the live editing setup, this file isn't required when building your site. Instead, it's picked up by the `@bookshop/generate` command to configure your component in CloudCannon.

Here's a bare-bones file to illustrate the main keys:

File: `sample.bookshop.yml`

```yaml
```
spec: #1
  structures:
    - content_blocks
  label: My Component

blueprint: #2
  text: "Hello World!"

preview: #3

_inputs: #4
```

**[1]** The `spec` section names this component and tells CloudCannon where you can place this component on your site.

**[2]** The `blueprint` section defines the data your component needs and provides the default values when a new component is created.

**[3]** The `preview` section is used in the Bookshop component browser and doesn't affect visual editing. We can ignore this key for now.

**[4]** The `_inputs` section is passed through as [CloudCannon's input configuration](/documentation/user-articles/what-are-inputs/),
allowing you to customize the fields specified in the `blueprint`.
```

To get things started, we'll focus on the required `spec` and `blueprint` sections.

## The component spec

The component `spec` controls everything about how a component is displayed in the CMS and where it can be added to a page. Let's walk through a more fleshed-out `spec` section:

File: `sample.bookshop.yml`

```yaml
```
spec:
  structures: #1
    - content_blocks
  label: My Component #2
  description: A very simple component #3
  icon: nature_people #4
```

**[1]** The `structures` key tells CloudCannon where this component can be added. In this example,
we are adding this component to the set of `content_blocks` structures.
In practice, this means that if a `content_blocks` key exists anywhere on your site,
for example, in the front matter of a page, CloudCannon will give editors the option to add
the `sample` component to that array or object.

**[2]** The `label` key is used as the main title of the component when selecting new components,
and browsing the existing components on a page.

**[3]** The `description` key can help provide context when selecting a new component in CloudCannon.

**[4]** The `icon` key is shown alongside existing components in CloudCannon, and when selecting new components.
This should be the attribute name of any [Material Icon](https://fonts.google.com/icons).
```

## The component blueprint

The component `blueprint` is used to generate the CloudCannon Structure for your component. This object will be used as the initial data when the component is added to a page and represents all of the editable data that your component takes.

If our `sample` component contained the following blueprint:

File: `sample.bookshop.yml`

```yaml
blueprint:
  text: "Hello World!"
  color: "#034AD8"
  image:
    image_url: "/image.png"
    image_alt: "My alternate text"
```

Then creating a new `sample` component in CloudCannon would present us with the following data editor:

![A data editor panel open in CloudCannon showing the initialized state of a new Sample component when added to the page](assets/deprecated/new-sample-component.png)

Component blueprints contain some other powerful features for helping create your Structures. We'll see those soon in the [Nesting components](/documentation/developer-guides/bookshop-astro-guide/nesting-components/) page of this guide.

## Generating and using Structures

The `npx @bookshop/generate` command that we set up when [configuring live editing](/documentation/developer-guides/bookshop-astro-guide/configuring-live-editing/) will automatically create Structures from your Bookshop components and make them available to CloudCannon. This process happens as part of your site's build step on CloudCannon.

The Structures listed in your component's `spec` determine where you can add that component in CloudCannon. For a `sample` component tagged as:

File: `sample.bookshop.yml`

```yaml
spec:
  structures:
    - content_blocks
```

With the page:

File: `pages/index.md`

```markdown
---
content_blocks:
---
```

CloudCannon will treat `content_blocks` as an array and allow editors to add the `sample` component to it.

You can also reference Bookshop generated structures in your CloudCannon input configuration.
For example, If you wanted to create a `page_components` input in CloudCannon that has
access to your Bookshop structures, you could configure `page_components` like this:

File: `cloudcannon.config.yml`

```YAML
```
_inputs:
  page_components:
    type___1___: array
    options:
      structures___2___: _structures.content_blocks
```

**[1]** Here you may also specify `type: object` that will function similarly to an array with a maximum length of one.
As an object, a single component from the set of Structures can be added or removed.

**[2]** Bookshop generated structures are available under the `_structures` key. This line sets the components available in
the `page_component` input to be all those assigned to the `content_blocks` structure in their Bookshop specification.
```

## Supported File Formats

Bookshop supports reading component files written in `yaml`, `toml`, `json`, and `js`.
Above, we have been writing the Bookshop configuration files using YAML.
This is the recommended format, but if you prefer, you can choose another.

> Can't decide? You can always run `npx @bookshop/up --format <format>`
> to automatically convert all of your Bookshop specification files if you change your mind.


---

---
title: Component templating
description: Creating your Astro components for Bookshop
url: https://cloudcannon.com/documentation/developer-guides/bookshop-astro-guide/component-templating/
content_type: developer guide
last_modified: 2026-04-16
---

Bookshop components use the templating language of your chosen static site generator. For Astro, Bookshop supports writing components as `.astro` files or in React as either `.jsx` or `.tsx` files.

## Creating your first component

Bookshop components live in the `src/components/` directory that Astro creates by default. Each component can be placed at the top level of a folder or nested in a folder matching that component's name.

To start, let's have a look at a sample bookshop component. Create an empty file at `src/components/sample/sample.astro` in your site and add the following content:

File: `src/components/sample/sample.astro`

```astro
<div class="c-sample">
  <p>{ Astro.props.text }</p>
</div>
```

If you're used to writing Astro templates on your site, the contents of this component should be very familiar. Beyond the special directory structure that this component should live in, any existing components should be compatible with Bookshop without any changes. Notice that this component is nested in a folder with the same name as the component. This doesn't change the component's Bookshop name (`sample`) but can be useful for grouping files related to this component — we'll see some examples of this later on.

Here's a hypothetical React component that uses some more advanced syntax:

File: `src/components/hero.jsx`

```jsx
export default ({ date, title, subtitle }) => {
  return <div class="c-hero">
    <p className="date">Published on {date.toLocaleDateString()}</p>
    <h1>{ title }</h1>
    {subtitle && <h2>{ subtitle }</h2>}
  </div>;
}
```

As with the Astro example, this component uses standard React JSX, and any existing React components should be compatible with Bookshop by default. With this component, we've opted not to nest it inside a folder. This can be cleaner when creating individual components that don't have any supporting files.

## Supported templating and functions

There are some restrictions on the features you can use inside your components. Since Bookshop renders your components in the browser, any functions or packages that you use must be able to run in a browser. Bookshop will include any `.png`, `.svg`, `.jpg`, and `.webp` assets imported by your components for live editing, but other asset types are not supported.


---

---
title: Importing Bookshop Styles
description: Write your styles alongside your components and import them automatically
url: https://cloudcannon.com/documentation/developer-guides/bookshop-astro-guide/bookshop-styles/
content_type: developer guide
last_modified: 2026-04-16
---

Bookshop provides helpers for writing SCSS styles alongside your components.
While not required, this can help organize your component directory and keep components self-contained.

## The Bookshop SCSS file

To add a Bookshop SCSS file for a component, create a `.scss` file next to your component with
the same name, just like the Bookshop data file from [Using Structures](/documentation/developer-guides/bookshop-astro-guide/using-structures).

So, if we wanted to add styles for our sample component we would create a `sample.scss` file in the same
folder as our `sample.astro` file. Afterward, our directory structure will look like this:

```
├── ```
├── src
│   └── components
│       └── sample
│           ├── sample.astro
│           ├── sample.bookshop.yml
│           └── sample.scss
└── ```
```

> These files are optional. You can safely delete them
> if you would rather maintain your component styles elsewhere.

## Global Bookshop SCSS

In addition to per-component SCSS files, you can also use Bookshop to include global SCSS files,
which will affect all components on your site. Global SCSS files live in the `shared/styles` directory,
so a site with a single `global.scss` might look like this:

```
├── ```
├── src
│   └── shared
│       └── styles
│           └── global.scss
└── ```
```

Bookshop first imports all the styles in the `shared/styles/` directory, followed by all component styles
in alphabetical order. As such, the `shared/styles/` directory is a great place to define any variables or mixins
that your component styles will use.

## Building your Bookshop SCSS

To include Bookshop styles on an Astro website, Bookshop provides a `@bookshop/sass` package
to include as part of your build step:

File: `Command line`

```bash
npx @bookshop/sass -b src -o public/css/bookshop.css
```

This command compiles all of the styles from your Bookshop directory,
and outputs a CSS file ready to be referenced on your website or imported into another style pipeline.

> The `@bookshop/sass` command will run any PostCSS plugins you have configured in your working directory.

To easily add this command as part of your workflow, install the `@bookshop/sass` package and reference
`bookshop-sass` from your package.json:

File: `package.json`

```json
{
  ...
  "scripts": {
    ...
    "sass:build": "bookshop-sass -b src -o public/css/bookshop.css",
    "sass:watch": "bookshop-sass -b src -o public/css/bookshop.css -w"
  }
}
```

> Run `npx @bookshop/sass --help` to see the available options.


---

---
title: Controlling Data Bindings
description: Control how CloudCannon adds automatic data bindings to your components
url: https://cloudcannon.com/documentation/developer-guides/bookshop-astro-guide/data-bindings/
content_type: developer guide
last_modified: 2026-04-16
---

With components on the page, Bookshop will create CloudCannon's
[Visual Data Bindings](https://cloudcannon.com/documentation/developer-articles/what-are-visual-data-bindings/) automatically
if it can find the data for that component in your page's front matter.

You can customize this behavior by including a flag in the component's data. Bookshop will look for any of the following keys:

- `data_binding`
- `dataBinding`
- `_data_binding`
- `_dataBinding`

Astro templates can also use the `bookshop:binding` directive to disable data bindings at build time.

For example:

File: `page.astro`

```astro
```
<Item props={props}/> //1
<Item props={props} bookshop:binding={false}/> //2
```

**[1]** By default, a component will be given a data binding if possible.

**[2]** This component will **not** be given a data binding.
```

> This flag only applies to the tagged component and doesn't cascade
> down. Any subcomponents will follow the standard rules or may also
> specify their own Data Binding flag.


---

---
title: Introduction to Bookshop with Eleventy
description: Learn how to build a live-editable website using Eleventy and Bookshop on CloudCannon.
url: https://cloudcannon.com/documentation/developer-guides/bookshop-eleventy-guide/
content_type: developer guide
last_modified: 2026-04-16
---

Welcome to the guide for setting up an Eleventy website using Bookshop.
Through this guide, we'll cover what Bookshop is and what it brings to the table,
how to integrate it into an Eleventy website, and how to connect everything together
to produce a fully static website that can be edited live in the browser using CloudCannon.

## What is Bookshop?

Bookshop is a collection of tooling that provides a component development workflow for static websites,
and aids in the creation of a page-building interface in the CloudCannon CMS.

An important facet of Bookshop is that it is fully open-source, and available on Github at [CloudCannon/bookshop](https://github.com/CloudCannon/bookshop/).
As a tool that integrates into your codebase, we want to ensure that you aren't vendor-locked to our platform.
Sites built using Bookshop remain fully portable, and can be built or hosted anywhere on the web.

## What does Bookshop bring to Eleventy?

For developers working locally, Bookshop first provides an Eleventy plugin that is used to load your components.
When dealing with your components, this plugin replaces the `include` tag that you would otherwise use. In a layout, this looks like:

File: `_includes/layouts/home.liquid`

```html
{% bookshop "hero" text: "My title text" %}
```

The semantics of this tag are the same as the standard include tag,
but instead of loading an include Bookshop will, in this case, locate and load the `hero` component.
We'll cover more about components in another chapter; for now, the important thing to know is that Bookshop components
use the templating language of your SSG, and in most cases can be directly migrated from your existing templating.

Another tool that Bookshop provides is the Bookshop Component Browser. This allows you to view and test your components
locally without adding them to pages on your site.

## What does Bookshop bring to CloudCannon?

Once your site is connected to CloudCannon, Bookshop's live editing features use your component files to
generate CloudCannon configuration as part of your site build. Under the hood Bookshop creates
[CloudCannon Structures](/documentation/developer-articles/create-a-structure/) for each of your components,
which allows your team to add and remove component objects in the CMS.

Next, when your site is loaded into CloudCannon's Visual Editor, an additional Bookshop script is loaded.
This script loads your component files into the browser, alongside a Bookshop engine that understands Eleventy components.
Using this, Bookshop can subscribe to data in the CMS using the [CloudCannon Visual Data Preview API](/documentation/developer-articles/what-are-visual-data-previews/)
to render changes to your components live on the page.

Finally, after rendering components, the Bookshop script tags them with [CloudCannon Visual Data Bindings](/documentation/developer-articles/what-are-visual-data-bindings/).
These data bindings allow you to click on elements directly in the Visual Editor, and add, edit, or rearrange them visually.


---

---
title: Component Preview Thumbnails
description: Show previews of your components in the CMS component picker
url: https://cloudcannon.com/documentation/developer-guides/bookshop-eleventy-guide/thumbnails/
content_type: developer guide
last_modified: 2026-04-16
---

When an editor is selecting a component in CloudCannon,
the icon from the component spec will be used as the default thumbnail:

File: `hero.bookshop.yml`

```yaml
spec:
  icon: nature_people #*
```

You can provide a custom image to use instead by placing a matching `<component>.preview.<format>`
file in your component directory. This will only be shown when adding new components to a page:

```
├── ```
├── _component-library
│   └── components
│       └── hero
│           ├── hero.bookshop.yml
│           ├── hero.eleventy.liquid
│           └── hero.preview.png
└── ```
```

You can also specify a `<component>.icon.<format>` file, which will be shown alongside existing components
in CloudCannon's array view:

```
├── ```
├── _component-library
│   └── components
│       └── hero
│           ├── hero.bookshop.yml
│           ├── hero.eleventy.liquid
│           └── hero.icon.svg
└── ```
```


---

---
title: Using Bookshop components
description: Using your Eleventy Bookshop components on your site
url: https://cloudcannon.com/documentation/developer-guides/bookshop-eleventy-guide/using-components/
content_type: developer guide
last_modified: 2026-04-16
---

Using a Bookshop component on your Eleventy site is very similar to using a regular Liquid include, with a few small differences.

## The Bookshop tag

The Bookshop plugin provides a `bookshop` tag for use in your layouts.

If you've been following along with this guide, add the following snippet
to a layout to use the sample component we created:

File: `_includes/layouts/base.liquid`

```markdown
...

{% bookshop "sample" text: "Hello from the sample component" %}

...
```

This component matches the syntax of the standard Liquid include, but takes a Bookshop component name rather than a file path.

> The Bookshop name of a component is the path to its directory.
> The name for `components/sample/sample.eleventy.liquid` is `sample`,
> and the name for `components/generic/button/button.eleventy.liquid` would be `generic/button`.

There are no limitations on referencing Bookshop comonents from other components — the `{% bookshop %}` tag can be used anywhere
on your site or in your components.

## Bookshop's bind syntax

Often when working with Bookshop components your data will live in a front-matter object, with all keys passed through.
This might end up looking like:

File: `page.liquid`

```markdown
---
hero:
  title: Hello World
  subtext: My page hero contents
  image: /image.png
---

{% bookshop "hero" title: hero.title subtext: hero.subtext image: hero.image %}

```

Passing through each key can quickly become unwieldy. To help with this, Bookshop provides
the bind attribute:

File: `page.liquid`

```markdown
---
hero:
  title: Hello World
  subtext: My page hero contents
  image: /image.png
---

{% bookshop "hero" bind: hero %}

```

This functions similar to the spread operator in JavaScript, passing all
object keys as props to the component.

## Rendering dynamic components

The Bookshop tag supports interpolating Liquid, so if you have your component name in a variable you can use:

File: `page.liquid`

```markdown
```
---
components:
  - _bookshop_name: hero #1
    title: Hello World
    subtext: My page hero contents
    image: /image.png
---

{% for component in components %}
  {% bookshop "{{component._bookshop_name}}" bind: component %}
{% endfor %}

```

**[1]** Later in this guide we'll cover creating CloudCannon Structures from your Bookshop components.
When doing do, the generated Structures will automatically include this `_bookshop_name` value for you to use.
```

## Passing Data to Bookshop Components

In order to live edit Bookshop components, Bookshop needs a clear path between a component
and the data it draws from.

In general, you should avoid adding logic around your Bookshop components in your
site layouts, and instead move that logic into a Bookshop component or helper.

For example:

File: `page.liquid`

```markdown
```
---
hero_text: "Hello World"
---
{% bookshop 'hero' text: hero_text %} <!--1-->

{% assign my_title = hero_text %}
{% bookshop 'hero' text: my_title %} <!--2-->
```

**[1]** This component can make the connection between the `text` prop and the page's front matter,
and will work as expected in the visual editor.

**[2]** This component doesn't have the context to find the origin of the `text` prop,
and will error in the visual editor.
*(Reassignments **inside** Bookshop components will work correctly).*
```


---

---
title: Live Editing Fallbacks
description: Add custom handling for components that cannot be visually edited
url: https://cloudcannon.com/documentation/developer-guides/bookshop-eleventy-guide/live-fallbacks/
content_type: developer guide
last_modified: 2026-04-16
---

Some components will never be editable without the full context of your Eleventy site. For example,
if you rely heavily on a custom plugin, or access file and network resources directly.

In these cases, you'll need to provide fallback content for Bookshop to use, or opt out of live previews
for a set of components altogether.

## Rendering different content when live editing

Bookshop sets a global flag when rendering your components in the Visual Editor. Using this flag
you can show extra information to your editors, or render fallback content instead of unsupported templating.

You can render special content in the live editing
environment by checking the Bookshop Live Editor flag. This can be
useful to show extra information to your editors, or to use a feature
that isn't supported while live editing.

File: `components/sample/sample.eleventy.liquid`

```liquid
{% if env_bookshop_live %}

  <p>I am being edited live!</p>
  <h1>Fallback Title</h1>

{% else %}

  <p>Standard build output</p>
  <h1>{{ title | custom_filter }}</h1>

{% endif %}
```

With the above component, your production hosted site will contain `Standard build output` and the output
from the `custom_filter` filter. Only when inside CloudCannon's Visual Editor, where `custom_filter` does not exist,
your editors will see the `Fallback Title` branch of the template.

This approach alone will not work for custom plugins, as these must exist when the templating is parsed.
For example, the following template will fail to render:

File: `components/sample/sample.eleventy.liquid`

```liquid
{% if env_bookshop_live %}

  <p>I am being edited live!</p>
  <h1>Fallback Title</h1>

{% else %}

  <p>Standard build output</p>
  <h1>{% my_plugin %}</h1>

{% endif %}
```

To resolve this error, [define your custom plugin via your Bookshop configuration](/documentation/developer-guides/bookshop-eleventy-guide/custom-plugins/).

File: `bookshop/my-plugin.js`

```javascript
module.exports = function (Liquid) {
    this.registerTag('my_plugin', () => {
      return true;
    });
}
```

The above snippet registers the `my_plugin` tag, which will allow the component to parse successfully.

In this example we don't add any functionality inside the plugin, so we would still wrap its usage in a `{% if env_bookshop_live %}` check.
As another option, we could instead implement a fallback inside our custom plugin file, and avoid using the `env_bookshop_live` check altogether.

## Disabling Live Editing

In some cases you can disable live editing entirely, using a flag in the component data.

This only works for components that are referenced in a site layout, and opts out of
rendering that tree of components and subcomponents. As such, this feature is intended
for rendering components such as navigation and footer templates from your Bookshop.
In the page building workflow, you should instead use the `env_bookshop_live` template check referenced above.

To disable live editing, Bookshop will look for any of the following keys on a **top-level** component:

- live_render
- liveRender
- _live_render
- _liveRender

File: `page.liquid`

```liquid
```
{% bookshop 'navigation' props: props %} <!--1-->

{% bookshop 'navigation' live_render: false props: props %} <!--2-->
```

**[1]** This component will attempt to re-render in the visual editor.

**[2]** This component will **not** re-render in the visual editor.
```


---

---
title: Configuring live editing
description: Connecting Bookshop to CloudCannon's live editing
url: https://cloudcannon.com/documentation/developer-guides/bookshop-eleventy-guide/configuring-live-editing/
content_type: developer guide
last_modified: 2026-04-16
---

Bookshop can render changes to your components live in CloudCannon, allowing you to build rich visual editing experiences.

## Installing Bookshop's development dependencies

To power the live editing experience, Bookshop requires a few extra packages to be installed. Unlike the previous plugin we installed, these dependencies have no impact on your production site: they only provide Bookshop tooling locally on your machine and within the CloudCannon Visual Editor.

File: `Command line`

```bash
```
         #1
npm i -D --save-exact @bookshop/generate @bookshop/browser @bookshop/eleventy-engine
```

**[1]** Bookshop releases all packages on every release, so the version numbers should
always stay exactly the same. Using `--save-exact` here means that npm won't use a newer version
than the one specified.
```

## Running the Bookshop generate command

Bookshop provides a command to run after your static site build. This command automatically discovers your component library and your site files, and connects CloudCannon's live editing APIs to the Bookshop components on your site.

Additionally, when we cover the structured data features of Bookshop, this command will do the work of creating your CloudCannon Structures for you.

To run this command, add the following to a [CloudCannon postbuild script](https://cloudcannon.com/documentation/developer-articles/extending-your-build-process-with-hooks/) at the root of your repository:

File: `.cloudcannon/postbuild`

```bash
npx @bookshop/generate
```

With that in place, any Bookshop components that use data from the front matter of a page should render changes live in the Visual Editor.

Additionally, you should notice CloudCannon's Data Bindings have been added around your components, allowing you to click directly on the page and open an editing panel.

As an example, if we have a component that pulls from front matter:

File: `about.html`

```liquid
---
title: About
layout: base.liquid
permalink: /about/
hero_component:
  title: On a mission to change email marketing
  description: We're here to breathe new air into email marketing and help grow your business.
  button:
    text: "Try This Free"
    link: "/signup"
---

{% bookshop "about/hero" bind: hero_component %}

```

When viewed in the Visual Editor, we will be able to interact with the element directly on the page and open up an editing panel:

![An example page matching the aforementioned code block, showing a data panel open in CloudCannon's visual editor after interacting directly with a component.](assets/deprecated/sendit-data-binding.png)


---

---
title: Component Playground
description: Build and test your components locally in Bookshop's playground application
url: https://cloudcannon.com/documentation/developer-guides/bookshop-eleventy-guide/component-playground/
content_type: developer guide
last_modified: 2026-04-16
---

The Bookshop component playground allows you to browse and
experiment with your components. When running in development, the
component playground also provides hot reloading of component templating
and styles.

After getting your Bookshop dependencies installed,
run the following command in the root of your repository:

File: `Command line`

```bash
```
npx @bookshop/browser #1
```

**[1]** Add the `--help` flag to see all available options.
```

By default, this will discover any Bookshop directories in or under the current working directory,
and will host a component library on port 30775.

After running this command, a component playground will be viewable on [http://localhost:30775](http://localhost:30775/)

## Specifying preview data for your components

The `blueprint` of your component specification represents the initial state of your component
when it is added to a page in CloudCannon. When previewing a component locally, however, we usually
want to see the component as it would appear in a realistic setting.

The `preview` key of your component specification allows you to do this by providing the data that
Bookshop should use in the playground, and will be merged into the component `blueprint`.

This is a deep merge, so given the following specification:

File: `hero.bookshop.yml`

```yaml
blueprint:
  hero_text: "Hello World"
  cta:
    button_text: ""
    button_url: "#"

preview:
  cta:
    button_text: "Click me"
```

Your component preview data will be:

File: `Playground Preview`

```yaml
hero_text: "Hello World"
cta:
  button_text: "Click me"
  button_url: "#"
```

As a result, your `preview` key doesn't need to mirror the entire component structure,
and can instead cherry-pick the relevant keys to override for the preview.


---

---
title: Nesting Components
description: Nest Bookshop components and create structured data within your components
url: https://cloudcannon.com/documentation/developer-guides/bookshop-eleventy-guide/nesting-components/
content_type: developer guide
last_modified: 2026-04-16
---

The Bookshop `blueprint` of your component config can help configure
some advanced Structure use-cases on CloudCannon.

## Nesting components

Your blueprint can reference other components and Structures, which will embed their structured data within.
For example, this saves you from having to re-define the required inputs if your `hero` component
contains an editable `button` component — using component nesting your blueprint might look like:

File: `hero.bookshop.yml`

```yml
```
blueprint:
  hero_text: Hello World
  button: bookshop:button #1
```

**[1]** This is a string, and could also be written `button: "bookshop:button"`.
```

In this example, the button key will become an Object Structure containing the values specified in your button component blueprint.
If you desired an array of buttons, you could use the following:

File: `hero.bookshop.yml`

```yml
```
blueprint:
  hero_text: Hello World
  buttons: #1
    - bookshop:button
```

**[1]** Or more concisely, `buttons: [bookshop:button]`
```

In general, any `bookshop:<component_name>` string will be replaced with the structure of that component,
and will allow editors to add and remove that component.

## Nesting a set of components

If you're creating a layout component, you likely want to support a set of components.
For this, you can reference the keys we defined in `spec.structures`:

File: `section.bookshop.yml`

```yml
```
blueprint:
  section_label: My Section
  header: bookshop:structure:content_blocks #1
  inner_components: [bookshop:structure:content_blocks] #2
```

**[1]** The `header` key will become a single component that can be selected from the set of components tagged as `content_blocks`

**[2]** The `inner_components` key will become an array that can contain any components tagged as `content_blocks`
```

## Nesting Example

To give a concrete example, let's say we have an example `hero` component:

File: `hero.bookshop.yml`

```yml
spec:
  structures: [content_blocks]

blueprint:
  hero_text: Hello World
  cta_button: bookshop:button
  column_components: [bookshop:structure:content_blocks]
```

Then our matching component template file might look like:

File: `hero.eleventy.liquid`

```liquid
```
<div class="hero">
  <h1>{{ hero_text }}</h1>
  {% if cta_button %} <!--1-->
    {% bookshop "button" bind: cta_button %}
  {% endif %}
  {% for component in column_components %}
    {% bookshop "{{ component._bookshop_name }}" bind: component %}
  {% endfor %}
</div>
```

**[1]** Object Structures in CloudCannon may be empty, as the component can be removed and replaced, so your template should check for the existence of this component.
```

## Initializing Nested Components

By default, nested components using the `bookshop:*` shorthand will be initialized empty. For example, the blueprint:

File: `hero.bookshop.yml`

```yml
blueprint:
  hero_text: Hello World
  button: bookshop:button
```

Will be initialized in CloudCannon as:

File: `page.md`

```yml
  - _bookshop_name: hero 
    hero_text: Hello World
    button:
```

Where the `button` input will provide an editor with the option to add a button component.
To instead have the button component exist on creation, you can use the syntax `bookshop:button!`:

File: `hero.bookshop.yml`

```yml
blueprint:
  hero_text: Hello World
  button: bookshop:button!
```

The same setting can be applied to a structure shorthand by specifying the component that should be initialized.
Taking the following example:

File: `section.bookshop.yml`

```yml
blueprint:
  section_label: Hello World
  column_components:
    - bookshop:structure:content_blocks!(hero)
    - bookshop:structure:content_blocks!(button)
```

This will be initialized in CloudCannon as:

File: `page.md`

```yml
  - _bookshop_name: section 
    section_label: Hello World
    column_components:
      - _bookshop_name: hero
        # ... hero fields
      - _bookshop_name: button
        # ... button fields
```

Where `column_components` can be then further added to/removed from by an editor,
using components from the tagged structure.


---

---
title: Using Data and Collections
description: Using Eleventy collections and data files from within your Bookshop components
url: https://cloudcannon.com/documentation/developer-guides/bookshop-eleventy-guide/data-collections/
content_type: developer guide
last_modified: 2026-04-16
---

When building your site, your Bookshop components are executed as standard Eleventy partials.
This means they have access to everything in Eleventy, including the data and collections of your site.

When Bookshop is building live previews of your components in the editor, this isn't always the case.
For example, your liquid plugins and site assets won't be available to the templating engine.

Bookshop **does** provide some access to data and collections in the visual editor, with a few caveats.
In many cases, you can continue to use both data and collections in your templating without modification.

## Pulling from collections

Accessing `collections.*` in your liquid templating works by default. All front matter from collections files
will be accessible, but some collection fields such as `content` will not be available when live editing.

One thing to note is that Bookshop is tied to [CloudCannon's collection modal](/documentation/user-articles/what-is-a-collection/), not Eleventy's.
Usually these will line up if your site is properly configured for CloudCannon, but in some instances they won't.
Most notably, collections for CloudCannon (and thus Bookshop) must be segmented by folder; files spread across multiple
folders with the same `tags` key will not be available as a collection when your component is rendered in the Visual Editor.

File: `components/sample/sample.eleventy.liquid`

```liquid
```
{%- for post in collections.post -%}
  <h2>{{ post.data.title }}</h2> <!--1-->
  <p>{{ post.content }}</p> <!--2-->
{%- endfor -%}
```

**[1]** Page titles and any other front-matter will be rendered.

**[2]** Page content will not be available, and will be returned empty.
```

## Pulling from data

Bookshop can pass through data from your site for live editing. This data is sourced from the CMS build,
which means it does need to be defined using [data_config in your CloudCannon configuration file](https://cloudcannon.com/documentation/developer-articles/define-your-data/).

The following CloudCannon config will allow access to `authors.*` and `offices.*` when rendering your components
in the Visual Editor:

File: `cloudcannon.config.yml`

```YAML
data_config:
  authors: true
  offices: true
```

## Passing data into components

It's best to avoid accessing data and collections from the layout around your components,
and instead move that access into a Bookshop component or helper. If the collections or data are sourced
in your layout and passed into your component, they will not be present when live editing.

File: `page.liquid`

```markdown
```
---
---

{% assign posts = collections.post %}
{% bookshop 'grid' posts: posts %} <!--1-->
```

**[1]** Bookshop will not be able to provide this collection data when live editing, as it is fetched from
outside the Bookshop component.
Instead, access `collections.post` from within the `grid` component.
```


---

---
title: Page Building
description: Use your components to visually build pages from scratch
url: https://cloudcannon.com/documentation/developer-guides/bookshop-eleventy-guide/page-building/
content_type: developer guide
last_modified: 2026-04-16
---

With your components live rendering, and Structures created in CloudCannon,
we now have the ingredients we need to create a page-building experience in the CMS.

## Looping components

Once you have a few more components built out, an ideal front-matter section might look like:

File: `content/index.md`

```yml
---
content_blocks:
  
  - _bookshop_name: hero
    title: Kākā
    subtitle: The New Zealand kākā is a large species of parrot
  
  - _bookshop_name: content
    content_markdown: >-
      The New Zealand kākā lives in lowland and mid-altitude native forest
  
  - _bookshop_name: image
    image_url: /uploads/Scrapping_kaka.jpg
    image_alt: The bird that screams loudest and most persistently gets to own the branch
  
  - _bookshop_name: stats
    length: 45cm
    weight: 452g
    color: reddish
---
```

To render this array of components on the page, we can loop over them and use the
liquid interpolation we covered in [Using Bookshop components](/documentation/developer-guides/bookshop-eleventy-guide/using-components/#rendering-dynamic-components):

File: `layout.html`

```html
{% for block in content_blocks %}
  {% bookshop "{{block._bookshop_name}}" bind: block %}
{% endfor %}
```

While this will work to render these components, using this directly
in a layout on your site will cause problems when live editing.
Bookshop can only live render changes within the boundaries of Bookshop components.

This means that if the above loop is placed directly in one of your Eleventy files,
the live editing boundaries will be:

File: `layout.html`

```html
{% for block in content_blocks %}
  <!-- start live editing -->
  {% bookshop "{{block._bookshop_name}}" bind: block %}
  <!-- end live editing -->
{% endfor %}
```

In this setup, each component individually will update changes live,
but rearranging or adding new components will not render correctly,
as the `{% for block in content_blocks %}` loop is not being rerendered.

The solution to this is to simply move this loop inside a Bookshop component. In fact,
the `@bookshop/init` command we ran earlier created a template explicity for this purpose:

```
├── ```
├── _component-library
│   ├── components
│   │   └── sample
│   │       └── sample.eleventy.liquid
│   └── shared
│       └── eleventy
│           └── page.eleventy.liquid
└── ```
```

## Bookshop Includes

You'll notice that this file doesn't live in the components directory, and is
instead in the `shared/eleventy` folder. This is a location for you to place templating
that needs to rerender in the Visual Editor, but isn't semantically a "component"
that an editor would add to a page.
Apart from this distinction, these files are functionally the same as your components,
and can be accessed using the `bookshop_include` tag:

File: `layout.html`

```html
{% bookshop_include "page" content_blocks: content_blocks %}
```

By passing all of the data to our `page` helper and looping within,
Bookshop is now able to update the entire page when the `content_blocks` array is changed.

## Taking stock

With the steps taken so far, you should have the framework for a fully functional page builder,
rendering live when editing on CloudCannon. This is a great moment to jump into your codebase,
start migrating some components, and experiment with the system.

The following sections of this guide will cover some of Bookshop's remaining features that can help polish
the page-building experience, but might not be required while setting things up.


---

---
title: Getting set up
description: The first steps for building an Eleventy site with Bookshop
url: https://cloudcannon.com/documentation/developer-guides/bookshop-eleventy-guide/getting-set-up/
content_type: developer guide
last_modified: 2026-04-16
---

Building a site with Bookshop requires a specific directory structure that lives alongside your website, and an Eleventy plugin to discover and use components.

> As a useful reference, the [Eleventy Bookshop Starter](https://github.com/CloudCannon/eleventy-bookshop-starter/) repository
> contains a simple site fully integrated with visual editing. Browsing the code and the file structure
> of the starter site can be helpful to solidify the concepts covered in this guide.

## Prerequisites

Bookshop requires Node >= 16 to be installed on your machine.

Currently, Bookshop only supports liquid templating on Eleventy sites.

## Creating your Bookshop directory

Bookshop requires that your component files live in a specific directory structure, which allows for components to be discovered automatically.

The easiest way to get started is to run Bookshop's `init` command. This should be run alongside your website source files:

File: `Command line`

```bash

npx @bookshop/init --new _component-library --framework eleventy

```

After running this command, the following directory structure will be created:

```
├── ```
├── _component-library
│   ├── bookshop
│   │   └── bookshop.config.cjs
│   ├── components
│   │   └── sample
│   │       ├── sample.bookshop.yml
│   │       ├── sample.eleventy.liquid
│   │       └── sample.scss
│   └── shared
│       ├── eleventy
│       │   └── page.eleventy.liquid
│       └── styles
│           └── global.scss
└── ```
```

Here's a quick run-through of what has been generated:

**`bookshop/bookshop.config.cjs`**

This houses the configuration for your Bookshop project, in this case instructing Bookshop to use the `@bookshop/eleventy-engine` package for any live component rendering.

**`components/`**

This is where you will write your component files, a sample component has been added for you.

**`shared/eleventy/`**

Any non-component files that you want to be able to use when live editing can be placed here. A page helper has been created, which helps render arrays of components.

**`shared/styles/`**

Optionally, any SCSS files in this directory will be imported alphabetically before component SCSS files. These are used on both the site, and the component browser.

## Connecting Bookshop to Eleventy

To connect Bookshop and Eleventy, install the `@bookshop/eleventy-bookshop` plugin from npm:

**npm:**

File: `Command line`

```bash
npm i --save-exact @bookshop/eleventy-bookshop
```

**Yarn:**

File: `Command line`

```bash
yarn add --exact @bookshop/eleventy-bookshop
```

Within your Eleventy config, import this plugin and specify the path to your Bookshop project.

File: `.eleventy.js`

```javascript
```

const pluginBookshop = require("@bookshop/eleventy-bookshop");

module.exports = function (eleventyConfig) {
  // ...

  eleventyConfig.addPlugin(pluginBookshop({
    bookshopLocations: ["_component-library"], /*1*/ /*2*/
    pathPrefix: '', /*3*/
  }));

  // ...
};

```

**[1]** Make sure that `bookshopLocations` points to the component library you just created, relative to your Eleventy source.

**[2]** If you specify multiple paths, components will be merged from all sources that exist.

**[3]** The `pathPrefix` provided must match the `pathPrefix` configured in your `.eleventy.js` configuration.

If you aren't using `pathPrefix`, this option can be omitted.
```

Now that Bookshop is installed and your Eleventy site can access it, we can look at creating and using components.


---

---
title: Configuring Inputs
description: Apply CloudCannon configuration to the inputs specified in your component configuration
url: https://cloudcannon.com/documentation/developer-guides/bookshop-eleventy-guide/configuring-inputs/
content_type: developer guide
last_modified: 2026-04-16
---

The `_inputs` section of your Bookshop file can be used to configure the keys in your generated structures.

This configuration is scoped to the individual component,
so you can configure the same key differently across components — even
if the components are nested within one another.

File: `sample.bookshop.yml`

```yaml
blueprint:
  text: "Hello World!"
  color: "#034AD8"
  date:
  button: bookshop:button

_inputs:
  text:
    comment: "This comment will show up in the CMS"
  color:
    type: color
  date:
    instance_value: NOW
```

File: `button.bookshop.yml`

```yaml
blueprint:
  text: "Hello World!"
  color: "#034AD8"

_inputs:
  text:
    comment: "A different comment specific to the button component"
  color:
    type: select
    options:
      values:
        - "#034AD8"
        - "#403AFC"
```

Despite both components specifying `text` and `color` inputs, their input configuration is unique
and scoped to the content of each `blueprint` object.

Input configuration is passed directly to CloudCannon; see the [CloudCannon Inputs Documentation](/documentation/user-articles/what-are-inputs/) to read more.


---

---
title: Using Structures
description: Create structured, reusable data from your components
url: https://cloudcannon.com/documentation/developer-guides/bookshop-eleventy-guide/using-structures/
content_type: developer guide
last_modified: 2026-04-16
---

So far we have introduced how to use components on a site, and how to update them live when the front matter of a page changes.

The next aspect to tackle is how to add and remove components to a page, which is where CloudCannon Structures come into the picture.

## What are Structures?

Structures are CloudCannon's answer to structured data on static sites. You can read more about structures in [Create a structure](/documentation/developer-articles/create-a-structure/) and the [Structures reference](/documentation/developer-reference/configuration-file/types/_structures/), but the main thing to know is that for Bookshop, Structures define the set of components that can be added to a specific key in CloudCannon.

## The Bookshop component file

Earlier, when we ran the `@bookshop/init` command, a sample component was created for us. Alongside the `sample.eleventy.liquid` templating file, a `sample.bookshop.yml` file was initialized.

```
├── ```
├── _component-library
│   └── components
│       └── sample
│           ├── sample.eleventy.liquid
│           └── sample.bookshop.yml
└── ```
```

Similar to the live editing setup, this file isn't required when building your site. Instead, it's picked up by the `@bookshop/generate` command to configure your component in CloudCannon.

Here's a bare-bones file to illustrate the main keys:

File: `sample.bookshop.yml`

```yaml
```
spec: #1
  structures:
    - content_blocks
  label: My Component

blueprint: #2
  text: "Hello World!"

preview: #3

_inputs: #4
```

**[1]** The `spec` section names this component, and tells CloudCannon where this component can be placed on your site.

**[2]** The `blueprint` section defines the data your component needs, and provides the default values when a new component is created.

**[3]** The `preview` section is used in the Bookshop component browser, and doesn't affect visual editing. We can ignore this key for now.

**[4]** The `_inputs` section is passed through as [CloudCannon's input configuration](/documentation/user-articles/what-are-inputs/),
allowing you to customize the fields specified in the `blueprint`.
```

To get things started, we'll focus on the required `spec` and `blueprint` sections.

## The component spec

The component `spec` controls everything about how a component should be displayed in the CMS, and where it can be added to a page. Let's walk through a more fleshed out `spec` section:

File: `sample.bookshop.yml`

```yaml
```
spec:
  structures: #1
    - content_blocks
  label: My Component #2
  description: A very simple component #3
  icon: nature_people #4
```

**[1]** The `structures` key tells CloudCannon where this component can be added. In this example,
we are adding this component to the set of `content_blocks` structures.
In practice this means that if a `content_blocks` key exists anywhere on your site,
for example in the front matter of a page, CloudCannon will give editors the option to add
the `sample` component to that array or object.

**[2]** The `label` key is used as the main title of the component when selecting new components,
and browsing the existing components on a page.

**[3]** The `description` key can help provide context when selecting a new component in CloudCannon.

**[4]** The `icon` key is shown alongside existing components in CloudCannon, and when selecting new components.
This should be the attribute name of any [Material Icon](https://fonts.google.com/icons).
```

## The component blueprint

The component `blueprint` is used to generate the CloudCannon Structure for your component. This object will be used as the initial data when the component is added to a page, and represents all of the editable data that your component takes.

If our `sample` component contained the following blueprint:

File: `sample.bookshop.yml`

```yaml
blueprint:
  text: "Hello World!"
  color: "#034AD8"
  image:
    image_url: "/image.png"
    image_alt: "My alternate text"
```

Then creating a new `sample` component in CloudCannon would present us with the following data editor:

![A data editor panel open in CloudCannon showing the initialized state of a new Sample component when added to the page](assets/deprecated/new-sample-component.png)

Component blueprints contain some other powerful features for helping create your Structures. We'll see those soon in the [Nesting components](/documentation/developer-guides/bookshop-eleventy-guide/nesting-components/) page of this guide.

## Generating and using Structures

The `npx @bookshop/generate` command that we set up when [configuring live editing](/documentation/developer-guides/bookshop-eleventy-guide/configuring-live-editing/) will automatically create Structures from your Bookshop components and make them available to CloudCannon. This process happens as part of your site build step on CloudCannon.

The Structures that your component is assigned to determines where it can be added in CloudCannon. For a `sample` component tagged as:

File: `sample.bookshop.yml`

```yaml
spec:
  structures:
    - content_blocks
```

With the page:

File: `pages/index.md`

```markdown
---
content_blocks:
---
```

CloudCannon will treat `content_blocks` as an array, and allow editors to add the `sample` component to it. Structures can also be accessed in CloudCannon using input configuration; if you want to use a different key, you can configure:

File: `cloudcannon.config.yml`

```YAML
```
_inputs:
  page_components:
    type___1___: array
    options:
      structures: _structures.content_blocks
```

**[1]** Here you may also specify `type: object`, which will function similar to an array with a maximum length of one.
As an object, a single component from the set of Structures can be added or removed.
```

## Supported File Formats

In the examples above, we have been writing the Bookshop configuration files using YAML. This is the recommended format, but you can also choose another if you prefer.

Bookshop supports reading component files written in `yaml`, `toml`, `json`, and `js`.

> Can't decide? You can always run `npx @bookshop/up --format <format>`
> to automatically convert all of your files if you change your mind.


---

---
title: Component templating
description: Creating your Eleventy components for Bookshop
url: https://cloudcannon.com/documentation/developer-guides/bookshop-eleventy-guide/component-templating/
content_type: developer guide
last_modified: 2026-04-16
---

Bookshop components use the templating language of your chosen static site generator.
For Eleventy, Bookshop supports writing components as `.liquid` files.

## Creating your first component

If you followed the previous [Getting set up](/documentation/developer-guides/bookshop-eleventy-guide/getting-set-up/) section of this guide
and ran the `@bookshop/init` command, a sample component will have been created for you:

```
├── ```
├── _component-library
│   └── components
│       └── sample
│           ├── sample.bookshop.yml
│           ├── sample.scss
│           └── sample.eleventy.liquid
└── ```
```

Bookshop components live in the `components/` directory, each inside a folder matching their name.

> Bookshop supports multiple SSG targets, so to reduce conflicts each SSG is namespaced. This is why your component files will
> be `.eleventy.liquid`, rather than `.liquid`.

For now, we're going to ignore the `.scss` and `.bookshop.yml` files and just look at the `.eleventy.liquid` templating file.
If you don't have this component, create an empty file at `components/sample/sample.eleventy.liquid` in your Bookshop folder.

If we look inside the sample file that was created for us, we'll see:

File: `components/sample/sample.eleventy.liquid`

```liquid
<div class="c-sample">
  <p>{{ text }}</p>
</div>
```

If you're used to writing Liquid includes on your Eleventy site, the contents of this component should be very familiar.
Beyond the special directory structure that this component should live in, the templating can *(in most cases)* be migrated directly
from any existing Eleventy includes.

Here's a hypothetical component that uses more Liquid syntax:

File: `components/hero/hero.eleventy.liquid`

```liquid
<div class="c-hero">
  <p class="date">Published on {{ publish_date | date: '%a, %b %d, %y' }}</p>
  <h1>{{ title }}</h1>
  {% if subtitle %}
    <h2>{{ subtitle }}</h2>
  {% endif %}
</div>
```

## Scaffolding new components

The `@bookshop/init` command also provides a way to create new components:

File: `Command line`

```bash
npx @bookshop/init --component <name>
```

Running the above command in an existing Bookshop will scaffold out some initial component files for you.

## Supported templating filters and functions

There are some restrictions on the features you can use inside your components.
Since Bookshop renders your components in the browser, any custom filters you define in your `.eleventy.js`
configuration won't be available.

Any filters that are defined in the [LiquidJS Filter documentation](https://liquidjs.com/filters/overview.html) will be available,
and Bookshop also provides working `markdownify`, `slugify`, and `url` filters that match Eleventy's default logic.

Bookshop only has access to the files in your component browser when live editing, so accessing any of your
Eleventy includes from within a component will cause an error in the Visual Editor. If these need to be accessed,
turn them into Bookshop components, or use Bookshop's [bookshop_include](/documentation/developer-guides/bookshop-eleventy-guide/page-building/#bookshop-includes) feature.


---

---
title: Importing Bookshop Styles
description: Write your styles alongside your components and import them automatically
url: https://cloudcannon.com/documentation/developer-guides/bookshop-eleventy-guide/bookshop-styles/
content_type: developer guide
last_modified: 2026-04-16
---

Bookshop provides helpers for writing SCSS styles alongside your components.
While not required, this can help organize your component directory and keep components self-contained.

## The Bookshop SCSS file

The last files for us to cover from the `@bookshop/init` command we ran earlier are the SCSS files that were
created for us.

```
├── ```
├── _component-library
│   ├── components
│   │   └── sample
│   │       ├── sample.eleventy.liquid
│   │       ├── sample.bookshop.yml
│   │       └── sample.scss
│   └── shared
│       └── styles
│           └── global.scss
└── ```
```

> These files are completely optional, and can be safely deleted
> if you would rather maintain your component styles elsewhere.

To include Bookshop styles on an Eleventy website, Bookshop provides a `@bookshop/sass` package
to include as part of your build step:

File: `Command line`

```bash
npx @bookshop/sass -b component-library -o site/css/bookshop.css
```

This compiles all of the styles from your Bookshop directory,
and outputs a CSS file ready to be referenced on your website or imported into another style pipeline.

Bookshop first imports all styles that exist in the `shared/styles/` directory, followed by all component styles
in alphabetical order. As such the `shared/styles/` directory is a great place to define any variables or mixins
that your component styles will use.

> The `@bookshop/sass` command will run any PostCSS plugins you have configured in your working directory.

To easily add this command as part of your workflow, install the `@bookshop/sass` package and reference
`bookshop-sass` from your package.json:

File: `package.json`

```json
{
  ...
  "scripts": {
    ...
    "sass:build": "bookshop-sass -b component-library -o site/css/bookshop.css",
    "sass:watch": "bookshop-sass -b component-library -o site/css/bookshop.css -w"
  }
}
```

> Run `npx @bookshop/sass --help` to see the available options.


---

---
title: Defining Custom Plugins
description: Add custom Liquid plugins to Bookshop's Eleventy engine
url: https://cloudcannon.com/documentation/developer-guides/bookshop-eleventy-guide/custom-plugins/
content_type: developer guide
last_modified: 2026-04-16
---

Bookshop allows you to specify custom Liquid plugins to extend the live editing interface. For example,
custom tags and plugins can be defined to allow your components to render in the Visual Editor.

There are some limitations here — for example, plugins that interact with the filesystem or network will not work.
In these cases, providing Bookshop a fallback plugin can be enough to unblock your components in the Visual Editor.

## Configuring plugins

Plugins be specified in your Bookshop configuration file:

File: `bookshop/bookshop.config.cjs`

```javascript
module.exports = {
    engines: {
        "@bookshop/eleventy-engine": {
            "plugins": ["./custom-plugin-one.js", "./custom-plugin-two.js"]
        }
    }
}
```

The paths specified here should be a path to each plugin file, relative to the `bookshop.config.cjs` file.

## Writing plugins

Plugins defined for Eleventy target LiquidJS.
See the LiquidJS documentation on [Registering Filters/Tags](https://liquidjs.com/tutorials/register-filters-tags.html) for in-depth instructions.

Each plugin file should export a function that takes a `Liquid` argument, which gives you access to configure the LiquidJS instance as required.

## Example custom LiquidJS filter

File: `bookshop/custom-filter.js`

```javascript
import yaml from "js-yaml";

module.exports = function (Liquid) {
    this.registerFilter("load_yaml", (text) => {
        return yaml.load(text)
    });
}
```

This example also includes pulling in a dependency.
This dependency should be installed in the working directory, likely the root of your repository.
Any dependencies referenced must support being bundled for web targets, so packages that rely on NodeJS APIs will not work here.


---

---
title: Controlling Data Bindings
description: Control how CloudCannon adds automatic data bindings to your components
url: https://cloudcannon.com/documentation/developer-guides/bookshop-eleventy-guide/data-bindings/
content_type: developer guide
last_modified: 2026-04-16
---

With components on the page, Bookshop will create CloudCannon's
[Visual Data Bindings](https://cloudcannon.com/documentation/developer-articles/what-are-visual-data-bindings/) automatically
if the data for that component can be found in your page's front matter.

By default, Bookshop will add bindings for any components
on the page, but will not add bindings for shared helper files. This
prevents Bookshop from rendering data bindings around our shared page helper,
so that the components within are immediately accessible.

This behavior can be customized by including a flag in the component's data. Bookshop will look for any of the following keys:

- `data_binding`
- `dataBinding`
- `_data_binding`
- `_dataBinding`

For example:

File: `page.liquid`

```liquid
```
<!-- Components -->
{% bookshop 'item' props: props %} <!--1-->
{% bookshop 'item' data_binding: false props: props %} <!--2-->

<!-- Includes -->
{% bookshop_include 'page' props: props %} <!--3-->
{% bookshop_include 'page' data_binding: true props: props %} <!--4-->
```

**[1]** By default, a component will be given a data binding if possible.

**[2]** This component will **not** be given a data binding.

**[3]** By default, bookshop_include helpers will not be given a data binding.

**[4]** This helper **will** be given a data binding.
```

> This flag only applies to the tagged component directly and doesn't cascade
> down. Any subcomponents will follow the standard rules, or may also
> specify their own Data Binding flag.