CloudCannon Visual Editing

@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.

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

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.

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

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.

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

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

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.

cloudcannon-visual-editing

NPX Install

Tags

SKILL.md Content