cloudcannon-visual-editing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CloudCannon Visual Editing

CloudCannon 可视化编辑

@cloudcannon/editable-regions

makes page elements interactive in CloudCannon's Visual Editor. This skill covers the editable regions API, integration setup, and SSG-specific patterns for wiring up text, image, array, and component editables.

@cloudcannon/editable-regions

使页面元素在 CloudCannon 的 Visual Editor 中可交互。本 skill 涵盖 editable regions API、集成设置，以及为 text、image、array 和 component editables 接入内容的 SSG 专用模式。

When to use

何时使用

Adding Visual Editor support to a new or existing CloudCannon site
Making page sections editable (text, images, arrays, components)
Setting up component re-rendering for live preview
Debugging editable regions that aren't appearing or updating
Adding editable regions to shared partials backed by data files

为新建或现有的 CloudCannon 站点添加 Visual Editor 支持
让页面区块可编辑（text、images、arrays、components）
设置 component 重渲染以实现 live preview
调试未出现或未更新的 editable regions
为由 data files 支持的 shared partials 添加 editable regions

When not to use

何时不应使用

The field has no
_inputs
entry or the collection is unconfigured — configure it first with
```
cloudcannon-configuration
```
. An editable region with no matching Input errors in the editor.
Editors need to insert new markup inside rich text — that is
```
cloudcannon-snippets
```
. Editable regions edit what is already rendered.
The site uses Bookshop (
```
*.bookshop.yml
```
files,
```
@bookshop/*
```
packages,
```
_bookshop_name
```
keys) — start at
```
cloudcannon-bookshop
```
. It routes back here for the regions.
A page will not open in the Visual Editor at all — that is usually a wrong collection
```
url
```
, not a region problem. See cloudcannon-configuration/collection-urls.md.

字段没有
_inputs
entry，或 collection 尚未配置——请先使用
```
cloudcannon-configuration
```
进行配置。如果 editable region 没有匹配的 Input，编辑器会报错。
编辑人员需要在 rich text 中插入新 markup——请使用
```
cloudcannon-snippets
```
。Editable regions 只能编辑已经渲染的内容。
站点使用 Bookshop（
```
*.bookshop.yml
```
文件、
```
@bookshop/*
```
packages、
```
_bookshop_name
```
keys）——请从
```
cloudcannon-bookshop
```
开始。它会引导你返回本文档处理 regions。
页面完全无法在 Visual Editor 中打开——这通常是 collection
```
url
```
配置错误，而不是 region 问题。请参阅 cloudcannon-configuration/collection-urls.md。

Doc	When to read
editable-regions.md	Start here. Region types, the attribute reference, custom-element equivalents
visual-editing.md	Section census, completeness checklist, pre-handoff sweep — every SSG
visual-editing-reference.md	On demand. Data-prop paths, arrays, page builders, components, source editables
editable-regions-internals.md	The Visual Editor JavaScript API; lifecycle traces and quirks when debugging
troubleshooting.md	Symptom → fix, when regions do not appear, update, or write where expected

SSG-specific:

Enter through the SSG's

overview.md

; it gives the reading order for that SSG's files.

SSG	Doc	Purpose
Astro	astro/overview.md	Start here for Astro — reading order and what each file covers
Astro	astro/visual-editing.md	Setup workflow, infrastructure checklist, Astro checklist items
Astro	astro/visual-editing-reference.md	Astro's deltas from the generic pattern reference (read on demand)
Astro	astro/troubleshooting.md	Astro-specific symptom → fix
Hugo	hugo/overview.md	Start here for Hugo — reading order and what each file covers
Hugo	hugo/visual-editing.md	Module setup, infrastructure checklist, Hugo checklist items, local checks
Hugo	hugo/visual-editing-reference.md	Hugo's deltas: partials-only re-render, `ENV_CLIENT` , what the editor's Hugo has
Hugo	hugo/troubleshooting.md	Hugo-specific symptom → fix
Eleventy	eleventy/overview.md	Start here for Eleventy — Liquid or Nunjucks path, reading order
Eleventy	eleventy/visual-editing.md	Plugin setup per path, infrastructure checklist, Eleventy checklist items, local checks
Eleventy	eleventy/visual-editing-reference.md	Eleventy's deltas: includes as components, the config in the browser, Nunjucks sites
Eleventy	eleventy/troubleshooting.md	Eleventy-specific symptom → fix

Scripts:

Script	Purpose
scripts/setup-editable-regions-astro.sh	Astro only. Installs package, wires Astro integration, creates `registerComponents.ts` stub. Hugo and Eleventy need no script — see their `visual-editing.md`

Other skills:

Skill	When to read
make-site-multilingual	The site is multilingual. Translation keys ( `data-rosey` ) must sit on region hosts rather than inside them, and component regions need explicit key passthrough
cloudcannon-dev-server	The regions are written and the user needs to try them. Starts a local CloudCannon that rebuilds as they edit

文档	何时阅读
editable-regions.md	从这里开始。Region 类型、属性参考、custom-element 等价用法
visual-editing.md	区块清点、完整性检查清单、交付前检查——适用于所有 SSG
visual-editing-reference.md	按需阅读。Data-prop paths、arrays、page builders、components、source editables
editable-regions-internals.md	Visual Editor JavaScript API；调试时的 lifecycle traces 和 quirks
troubleshooting.md	症状 → 修复方案，适用于 regions 未出现、未更新或未按预期写入的情况

SSG 专用：

请通过对应 SSG 的

overview.md

进入；其中给出了该 SSG 文件的阅读顺序。

SSG	文档	用途
Astro	astro/overview.md	Astro 请从这里开始——阅读顺序及每个文件的内容
Astro	astro/visual-editing.md	设置工作流、基础设施检查清单、Astro 检查项
Astro	astro/visual-editing-reference.md	Astro 相对于通用模式参考的差异（按需阅读）
Astro	astro/troubleshooting.md	Astro 专用症状 → 修复方案
Hugo	hugo/overview.md	Hugo 请从这里开始——阅读顺序及每个文件的内容
Hugo	hugo/visual-editing.md	Module 设置、基础设施检查清单、Hugo 检查项、本地检查
Hugo	hugo/visual-editing-reference.md	Hugo 的差异：仅 partial 重渲染、 `ENV_CLIENT` 、编辑器中的 Hugo 所具备的内容
Hugo	hugo/troubleshooting.md	Hugo 专用症状 → 修复方案
Eleventy	eleventy/overview.md	Eleventy 请从这里开始——Liquid 或 Nunjucks 路径、阅读顺序
Eleventy	eleventy/visual-editing.md	按路径进行 Plugin 设置、基础设施检查清单、Eleventy 检查项、本地检查
Eleventy	eleventy/visual-editing-reference.md	Eleventy 的差异：将 includes 作为 components、浏览器中的配置、Nunjucks sites
Eleventy	eleventy/troubleshooting.md	Eleventy 专用症状 → 修复方案

Scripts：

Script	用途
scripts/setup-editable-regions-astro.sh	仅适用于 Astro。安装 package、接入 Astro integration、创建 `registerComponents.ts` stub。Hugo 和 Eleventy 无需脚本——请参阅各自的 `visual-editing.md`

其他 skills：

Skill	何时阅读
make-site-multilingual	站点是多语言的。Translation keys（ `data-rosey` ）必须位于 region hosts 上，而不是 regions 内部，并且 component regions 需要显式传递 key
cloudcannon-dev-server	Regions 已完成写入，用户需要试用。启动本地 CloudCannon，并在编辑时自动重新构建

Quick reference

快速参考

Region type	Use for	Key attributes
`text`	Inline rich text	`data-editable="text"` `data-prop` `data-type`
`image`	Image picker	`data-editable="image"` `data-prop` (or `data-prop-src` / `data-prop-alt` )
`array`	List CRUD	`data-editable="array"` `data-prop` on container
`array-item`	Each list item	`data-editable="array-item"` on each child
`component`	Re-rendering sections	`data-editable="component"` `data-component` `data-prop`
`source`	Hardcoded text in templates	`data-editable="source"` `data-path` `data-key`

Rule of thumb: Use

component

when a section has conditional elements, style bindings, or derived content. Nest primitives (

text

image

array

) inside components for inline editing.

Region 类型	用途	关键属性
`text`	Inline rich text	`data-editable="text"` `data-prop` `data-type`
`image`	Image picker	`data-editable="image"` `data-prop` （或 `data-prop-src` / `data-prop-alt` ）
`array`	List CRUD	容器上使用 `data-editable="array"` `data-prop`
`array-item`	每个列表项	每个子项上使用 `data-editable="array-item"`
`component`	重渲染区块	`data-editable="component"` `data-component` `data-prop`
`source`	Templates 中的硬编码文本	`data-editable="source"` `data-path` `data-key`

经验法则： 当区块包含条件元素、样式绑定或派生内容时，使用

component

。将基础类型（

text

、

image

、

array

）嵌套在 components 中，以支持内联编辑。

Workflow

工作流

Setup — Install and wire the integration per the SSG's
```
visual-editing.md
```
(Astro: setup script + conditional
```
registerComponents
```
import; Hugo: module import +
```
editable-regions
```
partial; Eleventy: plugin + conditional
```
register-components.js
```
import on Liquid sites, nothing on Nunjucks sites)
Census — Document every visible section on every key page with treatment decisions (visual-editing.md § Section census)
Implement — Work through sections, adding editable attributes per the census
Verify — Run the completeness checklist in visual-editing.md, then the SSG's extra items

设置——按照对应 SSG 的
```
visual-editing.md
```
安装并接入 integration（Astro：setup script + 条件式
```
registerComponents
```
import；Hugo：module import +
```
editable-regions
```
partial；Eleventy：plugin + Liquid sites 上的条件式
```
register-components.js
```
import，Nunjucks sites 无需 import）
清点——按照处理决策，记录每个关键页面上的所有可见区块（visual-editing.md § Section census）
实现——逐个处理区块，根据清点结果添加 editable attributes
验证——运行 visual-editing.md 中的完整性检查清单，然后完成该 SSG 的额外检查项

Checklist reinforcement

检查清单要求

The SSG-specific workflow docs contain detailed completeness checklists. These are not optional.

Read the checklist BEFORE starting so you know what to aim for
You are not done until every checklist item is verified
Every section in the census must have editable regions OR a documented
```
sidebar-only
```
justification with a specific technical reason
Don't mark arrays as done without nested editables on their items — CRUD controls alone are not sufficient

SSG 专用工作流文档包含详细的完整性检查清单。这些检查项不可省略。

开始前阅读检查清单，以便明确需要完成的目标
除非验证了每一个检查项，否则任务尚未完成
清点结果中的每个区块都必须包含 editable regions，或者提供记录在案的
```
sidebar-only
```
理由及具体技术原因
不要在数组项未嵌套 editables 的情况下将其标记为完成——仅有 CRUD controls 并不足够

Common mistakes

常见错误

Excuse	Reality
"Text editables are enough for this page"	Check images, arrays, and components too. Text-only is a half-finished job.
"This component is too complex for editable regions"	If it renders data from a content collection, it should be editable. Simplify the component or wrap it in `editable-component` for sidebar re-rendering.
"The footer/nav doesn't need editables"	Shared partials need data-file-backed editables. Every visible section needs a treatment.
"Array items just need add/remove controls"	Without nested text/image editables on items, editors can't edit field values inline.
"I'll register components later"	Components the integration can't resolve can't re-render. Wire them as you go (Astro: register; Hugo: make it a partial; Eleventy: make it a Liquid include).
"Source editables aren't needed — this text rarely changes"	If it's visible, it should be editable -- but the mechanism depends on the page. Data file for shared UI; for page text, see visual-editing-reference.md § When to use source editables.
"I'll source-editable any hardcoded string on a page"	Page builder is the default; source editables are the exception, for one-off pages whose structure stays with the developer. If editors need to add, remove or reorder sections, use a page builder. See visual-editing-reference.md § When to use source editables.

常见说法	实际情况
“这个页面有 text editables 就足够了”	还要检查 images、arrays 和 components。仅支持 text 的实现只完成了一半。
“这个 component 对 editable regions 来说太复杂”	如果它渲染 content collection 中的数据，就应当可编辑。请简化 component，或将其包装在 `editable-component` 中，以便在 sidebar 中重新渲染。
“footer/nav 不需要 editables”	Shared partials 需要由 data file 支持的 editables。每个可见区块都需要相应的处理方式。
“数组项只需要添加/删除 controls”	如果数组项中没有嵌套的 text/image editables，编辑人员就无法内联编辑字段值。
“我稍后会注册 components”	Integration 无法解析的 components 无法重新渲染。请在开发过程中同步接入（Astro：register；Hugo：制作为 partial；Eleventy：制作为 Liquid include）。
“不需要 source editables——这些文本很少变化”	只要内容可见，就应当可以编辑，但其_机制_取决于页面。对于共享 UI 使用 data file；对于页面文本，请参阅 visual-editing-reference.md § When to use source editables。
“我会把页面上任何硬编码字符串都设为 source editable”	Page builder 是默认方案，source editables 仅用于结构始终由开发者维护的一次性页面。如果编辑人员需要添加、删除或重新排列区块，请使用 page builder。请参阅 visual-editing-reference.md § When to use source editables。