Mode d’emploi
- Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
- Consultez le document original pour les outils, identifiants et environnements requis.
- Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/cloudcannon/agent-skills --skill cloudcannon-visual-editingAvant de commencer
- L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
- Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Document Skill original
Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.
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. |
