cloudcannon-configuration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CloudCannon configuration

CloudCannon 配置

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.

本 skill 介绍如何创建和自定义

cloudcannon.config.yml

，该文件告诉 CloudCannon 如何理解和呈现站点内容；以及

.cloudcannon/initial-site-settings.json

，该文件告诉 CloudCannon 如何构建站点。

When to use

何时使用

Creating or customizing

cloudcannon.config.yml

.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

创建或自定义

cloudcannon.config.yml

或

.cloudcannon/initial-site-settings.json

添加或更改 Collections、Inputs、Structures 或 Select Data
编辑器中缺少某个字段，或显示了错误的 Input 类型
配置 Collection URLs，使页面可以在 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.

向模板添加可编辑区域——请使用
```
cloudcannon-visual-editing
```
。本 skill 用于配置这些区域背后的数据。
内容中的 MDX components 或 inline HTML——请使用
```
cloudcannon-snippets
```
。
执行完整迁移——请从
```
migrate-to-cloudcannon
```
开始，该流程会在 Phase 2 进入本 skill。
操作托管站点——身份验证、列出或创建站点、读写站点文件、触发构建或更改现有站点的构建配置，请使用
```
cloudcannon-cli
```
。本 skill 决定配置应该包含什么，而后者负责执行命令。

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.

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

在两个文件都存在之前不要继续。训练数据可能会臆造不存在的 key——schemas 才是唯一权威来源。

查询 recipes、

.gitignore

规则和

yaml-language-server

规则见 json-schemas.md。

检查是否存在任意格式的现有配置——例如

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

，而不仅仅检查

.yml

。如果存在配置，请对其进行自定义，并且仅使用

--dry-run

运行

configure generate

以供参考；不使用

--dry-run

时，CLI 会在现有配置旁边写入第二个

cloudcannon.config.yml

。如果不存在配置，请生成基线配置——参见 configuration.md § Generate a baseline。

Invalid keys

无效的 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.

编写配置前请检查此表。下表中的 keys 是 Agent 曾写入但 schema 中并不存在的 key；JSON schemas 是唯一权威来源。

错误	正确
`disable_url_preview: true`	`disable_url: true` ，用于关闭该 Collection 的输出 URL。
`output: false`	省略 `url` 并设置 `disable_url: true` ，或者使用 `data_config` 代替 Collection。
`type: hidden`	在任意 Input 的 `type` 旁设置 `hidden: true` ； `hidden: "<query>"` 可按条件隐藏。
在 `text` 或 `textarea` Input 上使用 `options.max`	使用 `options.max_length` ，并与 `min_length` 配对。
在 `_editables.text` 中使用块级 keys（ `bulletedlist` 、 `blockquote` 、 `format` 、 `table` ）	`_editables.text` 仅支持行内内容——参见 § `_editables` key-to-schema mapping。
`heading2: true` 、 `heading3: true`	`format: "p h1 h2 h3"` ，即以空格分隔的字符串——参见 § `_editables` key-to-schema mapping。
`options.collections: [team]`	使用 `values: collections.team` ，并设置 `value_key` 和 `preview` ——参见 inputs.md § Select values from a collection。
`options.structures: my_blocks`	使用完整路径 `_structures.my_blocks` ——参见 structures.md § The four rules。
`timezone: "+10:00"`	使用顶层 IANA 名称，例如 `Australia/Melbourne` ，默认值为 `Etc/UTC` ——参见 configuration.md § Review the generated config。
`paths.collections` 、 `paths.data`	使用 `collections_config.<name>.path` 和 `data_config.<name>.path` 。
`paths.output`	不存在此 key：构建工具会设置输出目录。 `paths` 仅用于存放静态资源目录： `static` 、 `uploads` 、 `uploads_filename` 、 `dam_uploads` 、 `dam_uploads_filename` 、 `dam_static` 、 `uploads_use_relative_path` 。
使用 schema enum 之外的 Material Symbols 名称，例如 `place`	使用 enum 中的名称，例如 `location_on` ；无效名称会回退为默认图标——可使用 json-schemas.md 中的 icon recipe 进行检查。

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.

开始前，阅读 Verification checklist 和对应 SSG 的清单，以明确需要达到的目标。
只有在两个清单中的每一项都验证通过后才能完成任务。
对编辑器可见的每个字段，都要提供明确的
```
_inputs
```
条目；类型推断仅作为回退方案——参见 configuration.md § Configure every field explicitly。
每轮更改后都要运行
```
npx @cloudcannon/cli validate
```
。当它标记某个 key 时，在 § Invalid keys 中查找正确的 key。

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.

文件	何时阅读
configuration.md	编写配置时始终首先阅读——包含相关步骤和通用验证清单。
json-schemas.md	编写任何 key 之前，用于确认该 key 是否存在于 schema 中。
cloudcannon-cli-guide.md	需要逐步生成基线配置或进行验证时；CLI 的其他内容请参阅 `cloudcannon-cli` 。
schemas.md	添加 Collection 或编写其 `schemas` 之前——一个 Collection 可以包含多个 schemas。
inputs.md	编写 `_inputs` 之前。
structures.md	任意字段包含数组或对象时，因为没有 Structure，编辑器将无法添加条目。
collection-urls.md	任意 Collection 会生成页面时，或页面无法在 Visual Editor 中加载时。
build-commands.md	构建过程包含 generators 或 post-build steps 时。
configuration-gotchas.md	配置期间需要查找跨 SSG 的常见问题时。
troubleshooting.md	配置已经出错，并且需要根据具体症状进行排查时。

**特定 SSG：**请通过对应 SSG 的

overview.md

进入；其中会提供阅读顺序，并列出该 SSG 的所有文件。

站点使用	从这里开始
Astro	astro/overview.md
Hugo	hugo/overview.md
Eleventy	eleventy/overview.md

其他 skills：

Skill	何时阅读
make-site-multilingual	配置多语言站点：locale 数据集、按 locale 划分的 Collections，以及带 locale 前缀的 URLs。
cloudcannon-dev-server	用户希望在 CloudCannon 中打开已配置的站点，并试用 Collections 和 Inputs 时。