Come usare
- Copia il comando e controlla il pacchetto prima di installarlo nel tuo ambiente agente.
- Controlla strumenti, credenziali e ambienti richiesti nel documento originale.
- Descrivi input e risultato desiderato; confronta l’output con le fonti.
npx skills add https://github.com/cloudcannon/agent-skills --skill cloudcannon-visual-editingPrima di iniziare
- L’installazione non include abbonamenti, quote API o accesso ai file.
- Stelle e installazioni indicano attività, non un test indipendente di qualità o sicurezza.
Documento Skill originale
Contenuto dal repository con titoli, esempi, codice, tabelle, link e immagini preservati.
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.ymlfiles,@bookshop/*packages,_bookshop_namekeys) — 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 |
| 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 + conditionalregisterComponentsimport; Hugo: module import +editable-regionspartial; Eleventy: plugin + conditionalregister-components.jsimport 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-onlyjustification 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. |
