cloudcannon-configuration

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

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.

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.