cloudcannon-configuration

Original：🇺🇸 English

Translated

Use when configuring a site for CloudCannon for any of the following. Download the JSON schemas before writing any configuration (see the top of SKILL.md). - Setting up cloudcannon.config.yml or .cloudcannon/initial-site-settings.json - Generating a baseline with the CloudCannon CLI - Adding or modifying Collections, Inputs, Structures, or Select Data - Setting up Structures for Array and Object Inputs - Configuring Collection URLs - Troubleshooting missing fields or Input types

7installs

Sourcecloudcannon/agent-skills

Added on2026-10-30

NPX Install

npx skill4agent add cloudcannon/agent-skills cloudcannon-configuration

SKILL.md Content

View Translation Comparison →

CloudCannon configuration

This skill covers creating and customizing

cloudcannon.config.yml

, which tells CloudCannon how to understand and present the site's content, and

.cloudcannon/initial-site-settings.json

, which tells CloudCannon how to build the site.

When to use

Creating or customizing

cloudcannon.config.yml

or

.cloudcannon/initial-site-settings.json

Adding or changing Collections, Inputs, Structures, or Select Data
A field is missing from the editor, or shows the wrong Input type
Configuring Collection URLs so pages open in the Visual Editor

When not to use

Adding editable regions to templates — that is
```
cloudcannon-visual-editing
```
. This skill configures the data behind them.
MDX components or inline HTML in content — that is
```
cloudcannon-snippets
```
Running a full migration — start at
```
migrate-to-cloudcannon
```
, which enters this skill at Phase 2
Operating on a hosted site — authenticating, listing or creating sites, reading and writing site files, triggering builds, or changing an existing site's build configuration is
```
cloudcannon-cli
```
. This skill decides what a configuration should say; that one runs the commands.

Do this before writing any configuration

bash

mkdir -p .cloudcannon/migration
curl -sL "https://github.com/cloudcannon/configuration-types/releases/latest/download/cloudcannon-config.latest.schema.json" \
  -o .cloudcannon/migration/cloudcannon-config.latest.schema.json
curl -sL "https://github.com/cloudcannon/configuration-types/releases/latest/download/cloudcannon-initial-site-settings.schema.json" \
  -o .cloudcannon/migration/cloudcannon-initial-site-settings.schema.json

Do not proceed until both files exist. Training data hallucinates keys — the schemas are the only authoritative source.

Query recipes, the

.gitignore

rule, and the

yaml-language-server

rule are in json-schemas.md.

Check for an existing config in any format —

cloudcannon.config.{yml,yaml,json,js,cjs,mjs}

, not only

.yml

. If one exists, customize it, and run

configure generate

only with

--dry-run

, for reference; without

--dry-run

the CLI writes a second

cloudcannon.config.yml

beside it. If none exists, generate a baseline — see configuration.md § Generate a baseline.

Invalid keys

Check this table before writing config. These are keys agents have written that the schema doesn't have; the JSON schemas are authoritative.

Wrong	Correct
`disable_url_preview: true`	`disable_url: true` , which turns off the collection's output URL.
`output: false`	Omit `url` and set `disable_url: true` , or use `data_config` instead of a collection.
`type: hidden`	`hidden: true` beside `type` , on any input; `hidden: "<query>"` hides it conditionally.
`options.max` on a `text` or `textarea` input	`options.max_length` , paired with `min_length` .
`_editables.text` with block keys ( `bulletedlist` , `blockquote` , `format` , `table` )	`_editables.text` is inline-only — see § `_editables` key-to-schema mapping.
`heading2: true` , `heading3: true`	`format: "p h1 h2 h3"` , a space-separated string — see § `_editables` key-to-schema mapping.
`options.collections: [team]`	`values: collections.team` with `value_key` and `preview` — see inputs.md § Select values from a collection.
`options.structures: my_blocks`	The full path, `_structures.my_blocks` — see structures.md § The four rules.
`timezone: "+10:00"`	A top-level IANA name such as `Australia/Melbourne` , defaulting to `Etc/UTC` — see configuration.md § Review the generated config.
`paths.collections` , `paths.data`	`collections_config.<name>.path` and `data_config.<name>.path` .
`paths.output`	No such key: the build tool sets the output directory. `paths` holds asset directories only: `static` , `uploads` , `uploads_filename` , `dam_uploads` , `dam_uploads_filename` , `dam_static` , `uploads_use_relative_path` .
A Material Symbols name outside the schema's enum, such as `place`	A name from the enum, such as `location_on` ; an invalid name falls back to the default icon — check it with the icon recipe in json-schemas.md.

Rules for every task

Read the Verification checklist and the SSG's checklist before starting, so you know what to aim for.
Finish only when every item in both checklists is verified.
Give every field editors see an explicit
```
_inputs
```
entry; type inference is a fallback — see configuration.md § Configure every field explicitly.
Run
```
npx @cloudcannon/cli validate
```
after every round of changes. When it flags a key, look up the correct one in § Invalid keys.

File	Read when
configuration.md	Always, first, when writing config — the steps and the shared verification checklist.
json-schemas.md	Before writing any key, to check it exists in the schema.
cloudcannon-cli-guide.md	Generating the baseline step by step, or validating; the rest of the CLI is `cloudcannon-cli` .
schemas.md	Before adding a collection or writing its `schemas` — one collection can hold many schemas.
inputs.md	Before writing `_inputs` .
structures.md	Any field holds an array or an object, since editors can't add items without a structure.
collection-urls.md	Any collection produces pages, or a page fails to load in the Visual Editor.
build-commands.md	The build has generators or post-build steps.
configuration-gotchas.md	Looking up a cross-SSG pitfall while configuring.
troubleshooting.md	Configuration is already wrong and you're working from a symptom.

SSG-specific: enter through the SSG's

overview.md

; it gives the reading order and lists every file for that SSG.

The site uses	Start at
Astro	astro/overview.md
Hugo	hugo/overview.md
Eleventy	eleventy/overview.md

Other skills:

Skill	Read when
make-site-multilingual	Configuring a multilingual site: locale datasets, per-locale collections and locale-prefixed URLs.
cloudcannon-dev-server	The user wants to open the configured site in CloudCannon and try the collections and inputs.