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.ymlor.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
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
_inputsentry; type inference is a fallback — see configuration.md § Configure every field explicitly. - Run
npx @cloudcannon/cli validateafter every round of changes. When it flags a key, look up the correct one in § Invalid keys.
Contents
| 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 | Writing install_command or node_version, or the build has generators or post-build steps. |
| routing.md | The site sets response headers, redirects or rewrites (framework config, _headers, netlify.toml, vercel.json). |
| 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 |
| Next.js | nextjs/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. |