cloudcannon-visual-editing

CloudCannon ビジュアル編集

@cloudcannon/editable-regions を使うと、CloudCannon のビジュアルエディターでページ要素を操作できるようになります。このスキルでは、編集可能領域 API、連携の設定、テキスト、画像、配列、コンポーネントの編集可能要素を組み込むための SSG 固有のパターンについて説明します。

使用するタイミング

• 新しい CloudCannon サイト、または既存の CloudCannon サイトにビジュアルエディターのサポートを追加するとき
• ページのセクション（テキスト、画像、配列、コンポーネント）を編集可能にするとき
• ライブプレビュー用にコンポーネントの再レンダリングを設定するとき
• 編集可能領域が表示されない、または更新されない問題をデバッグするとき
• データファイルを参照する共有パーシャルに編集可能領域を追加するとき

使用しないタイミング

• フィールドに _inputs エントリーがない、またはコレクションが設定されていない場合 — まず cloudcannon-configuration で設定してください。一致する Input がない編集可能領域は、エディターでエラーになります。
• エディターがリッチテキスト内に新しいマークアップを挿入する必要がある場合 — それには cloudcannon-snippets を使用します。編集可能領域では、すでにレンダリングされている内容を編集します。
• サイトで Bookshop を使用している場合（*.bookshop.yml ファイル、@bookshop/* パッケージ、_bookshop_name キー） — cloudcannon-bookshop から始めてください。編集可能領域については、そこからこのドキュメントに案内されます。
• ページがビジュアルエディターでまったく開かない場合 — 通常は編集可能領域ではなく、コレクションの url が誤っています。cloudcannon-configuration/collection-urls.md を参照してください。

目次

ドキュメント	参照するタイミング
editable-regions.md	まずはこちらを参照してください。領域の種類、属性のリファレンス、カスタム要素に相当するもの
visual-editing.md	セクションの調査、完全性チェックリスト、引き渡し前の確認 — すべての SSG
visual-editing-reference.md	必要に応じて参照してください。データプロパティのパス、配列、ページビルダー、コンポーネント、ソース編集可能要素
react/visual-editing-reference.md	あらゆる SSG の React コンポーネント — 登録、EditableRegions エクスポート、JSX マークアップ、リッチテキストのホスト、ブループリント
vue/visual-editing-reference.md	あらゆる SSG の Vue コンポーネント — 登録、EditableRegions エクスポート
svelte/visual-editing-reference.md	あらゆる SSG の Svelte コンポーネント — 登録、EditableRegions エクスポート
editable-regions-internals.md	ビジュアルエディターの JavaScript API。デバッグ時のライフサイクルの追跡と注意点
troubleshooting.md	症状 → 解決策。領域が表示されない、更新されない、想定した場所に書き込まれない場合

SSG 固有の情報：

SSG の overview.md から読み始めてください。その SSG のファイルを読む順序が記載されています。React、Vue、Svelte のコンポーネントをレンダリングするサイトでは、上記の該当フレームワークの visual-editing-reference.md も参照してください。SSG の読み進める順序には、そのファイルも記載されています。

SSG	ドキュメント	目的
Astro	astro/overview.md	Astro の場合はここから — 読む順序と各ファイルの内容
Astro	astro/visual-editing.md	セットアップのワークフロー、インフラストラクチャのチェックリスト、Astro のチェックリスト項目
Astro	astro/visual-editing-reference.md	汎用パターンのリファレンスと Astro の違い（必要に応じて参照）
Astro	astro/troubleshooting.md	Astro 固有の症状 → 解決策
Hugo	hugo/overview.md	Hugo の場合はここから — 読む順序と各ファイルの内容
Hugo	hugo/visual-editing.md	モジュールのセットアップ、インフラストラクチャのチェックリスト、Hugo のチェックリスト項目、ローカルチェック
Hugo	hugo/visual-editing-reference.md	Hugo の違い：partials のみの再レンダリング、ENV_CLIENT、エディター側の Hugo にあるもの
Hugo	hugo/troubleshooting.md	Hugo 固有の症状 → 解決策
Eleventy	eleventy/overview.md	Eleventy の場合はここから — Liquid または Nunjucks の手順、読む順序
Eleventy	eleventy/visual-editing.md	手順ごとのプラグインのセットアップ、インフラストラクチャのチェックリスト、Eleventy のチェックリスト項目、ローカルチェック
Eleventy	eleventy/visual-editing-reference.md	Eleventy の違い：コンポーネントとしてのインクルード、ブラウザー内の設定、Nunjucks サイト
Eleventy	eleventy/troubleshooting.md	Eleventy 固有の症状 → 解決策
Next.js	nextjs/overview.md	Next.js の場合はここから — EditableRegions のルート、読む順序
Next.js	nextjs/visual-editing.md	レイアウトのルート、条件付きエディターローダー、コンポーネントマップ、インフラストラクチャのチェックリスト、Next.js のチェックリスト項目
Next.js	nextjs/visual-editing-reference.md	Next.js の違い：クライアントセーフな登録済みコンポーネント、ルーターのフック、MDX 本文
Next.js	nextjs/troubleshooting.md	Next.js 固有の症状 → 解決策

スクリプト：

スクリプト	目的
scripts/setup-editable-regions-astro.sh	Astro のみ。 パッケージをインストールし、Astro インテグレーションを設定して、registerComponents.ts のスタブを作成します。Hugo、Eleventy、Next.js ではスクリプトは不要です。それぞれの visual-editing.md を参照してください

その他のスキル：

スキル	読むタイミング
make-site-multilingual	サイトが多言語の場合。翻訳キー（data-rosey）は領域の内側ではなく、領域ホストに配置する必要があります。また、コンポーネント領域には明示的なキーの受け渡しが必要です
cloudcannon-dev-server	領域を記述し、ユーザーが試す必要がある場合。編集に合わせて再ビルドするローカルの CloudCannon を起動します

クイックリファレンス

領域の種類	用途	主な属性
text	インラインのリッチテキスト	data-editable="text" data-prop data-type
image	画像ピッカー	data-editable="image" data-prop（または data-prop-src／data-prop-alt）
array	リストの CRUD	コンテナーに data-editable="array" data-prop
array-item	各リスト項目	各子要素に data-editable="array-item"
component	セクションの再レンダリング	data-editable="component" data-component data-prop
source	テンプレート内のハードコードされたテキスト	data-editable="source" data-path data-key

経験則： 条件付き要素、スタイルのバインディング、または派生コンテンツがあるセクションには component を使用します。インライン編集には、プリミティブ（text、image、array）をコンポーネントの中にネストします。

ワークフロー

1. セットアップ — SSG の visual-editing.md に従ってインテグレーションをインストールして設定します（Astro：セットアップスクリプト＋条件付きの registerComponents インポート、Hugo：モジュールのインポート＋editable-regions パーシャル、Eleventy：プラグイン＋Liquid サイトでは条件付きの register-components.js インポート、Nunjucks サイトでは不要、Next.js：app/layout.tsx または pages/_app のルートに EditableRegions を配置＋条件付きの registerComponents インポート）
2. 現状調査 — 主な各ページの表示されるすべてのセクションについて、対応方針とともに記録します（visual-editing.md § セクションの現状調査）
3. 実装 — セクションごとに作業し、現状調査に従って編集可能な属性を追加します
4. 検証 — visual-editing.md の完全性チェックリストを実行し、その後、SSG 固有の追加項目も確認します

チェックリストの徹底

SSG 固有のワークフロードキュメントには、詳細な完全性チェックリストが記載されています。これらは任意ではありません。

• 作業を始める前にチェックリストを読むことで、目指すべき状態を把握してください
• チェックリストのすべての項目を検証するまで、作業は完了していません
• センサスの各セクションには、編集可能な領域を設けるか、具体的な技術的理由を記載した sidebar-only の説明を用意してください
• 配列の項目にネストされた編集可能領域がない場合、作業済みとしないでください。CRUD コントロールだけでは不十分です

よくある間違い

言い訳	実際のところ
"このページはテキストの編集可能領域だけで十分"	画像、配列、コンポーネントも確認してください。テキストだけでは作業が半分しか完了していません。
"このコンポーネントは編集可能領域にするには複雑すぎる"	コンテンツコレクションのデータをレンダリングするなら、編集可能にする必要があります。コンポーネントを簡素化するか、サイドバーで再レンダリングできるように editable-component でラップしてください。
"フッターやナビゲーションに編集可能領域は必要ない"	共有パーシャルには、データファイルを参照する編集可能領域が必要です。表示されるすべてのセクションに対応が必要です。
"配列の項目には追加／削除コントロールだけあればよい"	項目にネストされたテキスト／画像の編集可能領域がないと、編集者はインラインでフィールド値を編集できません。
"コンポーネントの登録は後で行う"	インテグレーションが解決できないコンポーネントは再レンダリングできません。作業を進めながら接続してください（Astro：登録する、Hugo：パーシャルにする、Eleventy：Liquid インクルードにする、Next.js：componentMap.ts に追加する）。
"ソース編集可能領域は不要。このテキストはめったに変更されない"	表示されるものは編集可能にする必要があります。ただし、方法 はページによって異なります。共有 UI にはデータファイルを使用し、ページのテキストについては visual-editing-reference.md § ソース編集可能領域を使用する場合 を参照してください。
"ページ内のハードコードされた文字列はすべてソース編集可能領域にする"	デフォルトはページビルダーです。ソース編集可能領域は、構造を開発者が管理し続ける単発ページ向けの例外です。編集者がセクションの追加、削除、並べ替えを行う必要がある場合は、ページビルダーを使用してください。visual-editing-reference.md § ソース編集可能領域を使用する場合 を参照してください。