cloudcannon-snippets

CloudCannon スニペット

スニペットを使うと、編集者は CloudCannon のリッチテキストコンテンツエディター内で、複雑なマークアップ（コンポーネント、ショートコード、埋め込み）を挿入および編集できます。このスキルでは、SSG レイヤー（コンポーネントをインポート／ビルドする方法）と CloudCannon レイヤー（エディターに構文を認識させる _snippets 設定）の両方を扱います。

使用する場面

• 新規または既存の CloudCannon サイトにスニペットのサポートを追加する
• コンテンツエディターで使う MDX コンポーネント（Astro、Next.js）、Hugo のショートコード、Eleventy のショートコードやインクルードを設定する
• Markdown コンテンツにインライン HTML スニペット（figure、video、details）を追加する
• スニペットの解析、ラウンドトリップ、ツールバーの問題をデバッグする

使用しない場面

• コンポーネントはインラインコンテンツではなく、ページビルダーブロックにすべき — 編集者はリッチテキストツールバーではなく、構造からブロックを選びます。cloudcannon-configuration と、移行スキルのページ構築ガイドを参照してください。
• レンダリング済みの既存要素をその場で編集可能にする — これは cloudcannon-visual-editing の対象です。スニペットは新しいマークアップを挿入し、編集可能領域はページ上にすでにあるマークアップを編集します。
• コンポーネントやインライン HTML を含まない通常の Markdown コンテンツ — スニペットの設定は不要です

目次

ドキュメント	読む場面
snippets.md	まずはこちらをお読みください。両レイヤーの概要、設定の階層、使用する方式、スニペットのプロパティ、ツールバーの設定、.md ファイル内の raw HTML スニペット
template-based.md	コンポーネント構文が組み込みテンプレートと一致する場合（最も一般的な方法）
raw.md	コンポーネントにカスタム構文が必要な場合（例：client:load、標準外の属性）
built-in-templates.md	組み込みの MDX、Hugo、Eleventy テンプレート、インポートバンドル、パーサーの内部動作について理解する
gotchas.md	予防ルール — 落とし穴とその回避方法
troubleshooting.md	症状の一覧 — すでに問題が発生している場合はこちらから確認してください。該当するルールに案内します

SSG 固有:

SSG	ドキュメント
Astro	astro/overview.md — MDX スタック、astro-auto-import、MDX と raw の使い分け
Hugo	hugo/overview.md — ショートコード、組み込みショートコードのインポート、Hugo テンプレートの選択
Eleventy	eleventy/overview.md — ショートコードとインクルード、Liquid または Nunjucks テンプレートの選択、{% raw %}
Next.js	nextjs/overview.md — @next/mdx、next-mdx-remote またはコンテンツレイヤー、共通コンポーネントマップ

すぐに判断する

ケース	アプローチ
コンポーネントの構文が組み込みテンプレートと一致する	テンプレートベース — template-based.md を参照してください
追加の構文、SSG ディレクティブ、カスタム解析がある	Raw — raw.md を参照してください
.md 内のインライン HTML（<figure>、<video>）	Raw スニペット — snippets.md § インライン HTML 用の Raw スニペット を参照してください
コレクション内の 3 つ以上のファイルで、同じコンポーネントが冒頭または末尾にある	レイアウトフィールドを検討してください — snippets.md § スニペットかレイアウトフィールドか？ のテストを適用し、ユーザーに確認してください

ほとんどの設定では、シンプルなコンポーネントにはテンプレートベースを、SSG 固有のディレクティブを含むものには Raw を使用します。

チェックリスト

開始前にこれを読み、完了時に各項目を確認してください。

• コンテンツファイルで使われているすべてのコンポーネントに _snippets エントリーがある
• _editables で、該当するコンテンツブロックに snippet: true が含まれている
• 各スニペットが正しく往復する（エディターから挿入し、保存して再度開いても、マークアップが変わらない）
• スニペットフィールド用に _inputs が設定されている（画像フィールドには type: image を設定するなど）
• スニペットのプレビューが設定されている（画像を含むスニペットには view: gallery を設定）
• picker_preview で静的な値を使用している（ピッカーのコンテキストでは解決されない key: ルックアップは使用しない）

よくある間違い

言い訳	実際のところ
「組み込みテンプレートで対応できます」	往復変換を確認してください。組み込みテンプレートには既知のエッジケースがあります。詳しくはgotchas.mdをご覧ください。
「スニペットツールバーの設定は後でします」	ツールバーがないと、エディターからスニペットを挿入できません。今すぐ_editablesにsnippet: trueを追加してください。
「このコンポーネントはニッチすぎて、スニペットにするほどではありません」	エディターがコンテンツ内で目にするなら、編集できる必要があります。設定してください。
「コンテンツ内にインポート文があっても問題ありません」	インポートをコンテンツファイルに記述せずに済むよう、コンポーネントを共通の場所から解決してください（Astro：astro-auto-import、Next.js：mdx-components.tsxまたは共通コンポーネントマップ）。HugoとEleventyのショートコードにはインポートは不要です。
「この用途なら_snippets_importsを使えます」	使わないでください。誤って一致する可能性のある包括的なマッチャーが読み込まれます。明示的な_snippetsエントリーを記述してください。インポートによってのみ利用できるビルド済みスニペット（Hugoの組み込みショートコード、Eleventyの{% raw %}）は例外です。名前を指定してincludeしてください。
「_snippetsを設定したので、スニペットは完了です」	astro.config.mjsでastro-auto-importを設定し、MDXファイルからimport行を削除しない限り、エディターにはMDXコンテンツの先頭に生のimport文が表示されます。パイプラインの4つのステップすべてが必要です。詳しくはastro/overview.md § MDX setup pipelineをご覧ください。
「MDXのインライングリッド画像は、生のHTMLのままで問題ありません」	エディターでは、生の<div class="grid">と<Image>のブロックを安全に編集できません。対応する_snippetsエントリーを作成し、自己終了型の<Gallery images={[{src, alt}, ...]} />コンポーネント（自動インポート）に切り出してください。詳しくはtemplate-based.md § Array-of-objects propsをご覧ください。cc-friendly-conventions.md § Image galleries in MDX contentもご覧ください。