cloudcannon-visual-editing

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.

Contents

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
react/visual-editing-reference.md	React components, in any SSG — registration, the EditableRegions export, JSX markup, rich text hosts, blueprints
vue/visual-editing-reference.md	Vue components, in any SSG — registration, the EditableRegions export
svelte/visual-editing-reference.md	Svelte components, in any SSG — registration, the EditableRegions export
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. A site that renders React, Vue or Svelte components also reads that framework's visual-editing-reference.md above, where the SSG's reading order lists it.

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
Next.js	nextjs/overview.md	Start here for Next.js — the EditableRegions root, reading order
Next.js	nextjs/visual-editing.md	Layout root, gated editor loader, component map, infrastructure checklist, Next.js checklist items
Next.js	nextjs/visual-editing-reference.md	Next.js's deltas: client-safe registered components, router hooks, MDX bodies
Next.js	nextjs/troubleshooting.md	Next.js-specific symptom → fix

Scripts:

Script	Purpose
scripts/setup-editable-regions-astro.sh	Astro only. Installs package, wires Astro integration, creates registerComponents.ts stub. Hugo, Eleventy and Next.js 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

1. 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; Next.js: EditableRegions root in app/layout.tsx or pages/_app + gated registerComponents import)
2. Census — Document every visible section on every key page with treatment decisions (visual-editing.md § Section census)
3. Implement — Work through sections, adding editable attributes per the census
4. 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; Next.js: add it to componentMap.ts).
"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.