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

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.

Scripts:

Other skills:

Quick reference

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