cloudcannon-configuration

CloudCannon の設定

このスキルでは、CloudCannon にサイトのコンテンツの解釈方法と表示方法を伝える cloudcannon.config.yml と、サイトのビルド方法を伝える .cloudcannon/initial-site-settings.json の作成とカスタマイズを扱います。

使用する場合

• cloudcannon.config.yml または .cloudcannon/initial-site-settings.json を作成またはカスタマイズするとき
• コレクション、入力項目、構造、または選択データを追加または変更するとき
• エディターにフィールドが表示されない、または誤った入力タイプで表示されるとき
• コレクションの URL を設定して、ページをビジュアルエディターで開けるようにするとき

使用しない場合

• テンプレートに編集可能な領域を追加する場合 — その場合は cloudcannon-visual-editing を使用します。このスキルでは、それらの領域の背後にあるデータを設定します。
• コンテンツ内の MDX コンポーネントまたはインライン HTML を扱う場合 — その場合は cloudcannon-snippets を使用します。
• 移行全体を実行する場合 — migrate-to-cloudcannon から開始してください。このスキルのフェーズ 2 に進みます。
• ホストされたサイトを操作する場合 — 認証、サイトの一覧表示または作成、サイトファイルの読み書き、ビルドの実行、既存サイトのビルド設定の変更には、cloudcannon-cli を使用します。このスキルでは設定に記述する内容を決め、もう一方のスキルではコマンドを実行します。

設定を書く前に必ず実行すること

mkdir -p .cloudcannon/migration
curl -sL "https://github.com/cloudcannon/configuration-types/releases/latest/download/cloudcannon-config.latest.schema.json" \
  -o .cloudcannon/migration/cloudcannon-config.latest.schema.json
curl -sL "https://github.com/cloudcannon/configuration-types/releases/latest/download/cloudcannon-initial-site-settings.schema.json" \
  -o .cloudcannon/migration/cloudcannon-initial-site-settings.schema.json

両方のファイルが存在するまで、先に進まないでください。学習データには存在しないキーが含まれることがあります。唯一の信頼できる情報源はスキーマです。

クエリレシピ、.gitignore ルール、および yaml-language-server ルールについては、json-schemas.md を参照してください。

既存の設定ファイルを、.yml だけでなく、どの形式でも確認してください（cloudcannon.config.{yml,yaml,json,js,cjs,mjs}）。既存のファイルがある場合はそれをカスタマイズし、参考のために configure generate を --dry-run 付きでのみ実行してください。--dry-run を付けずに実行すると、CLI はそのファイルと同じ場所に 2 つ目の cloudcannon.config.yml を書き込みます。既存のファイルがない場合は、ベースラインを生成してください。configuration.md § ベースラインの生成 を参照してください。

無効なキー

設定を書く前に、この表を確認してください。ここに挙げるのは、エージェントが記述したもののスキーマには存在しないキーです。正式な情報源は JSON スキーマです。

誤り	正しい
disable_url_preview: true	disable_url: true。コレクションの出力 URL を無効にします。
output: false	url を省略して disable_url: true を設定するか、コレクションの代わりに data_config を使用します。
type: hidden	任意の入力で type の隣に hidden: true を指定します。hidden: "<query>" を指定すると、条件に応じて非表示になります。
text または textarea 入力の options.max	min_length と組み合わせて options.max_length を指定します。
ブロックキー（bulletedlist、blockquote、format、table）を指定した _editables.text	_editables.text はインライン専用です。_editables のキーとスキーマの対応を参照してください。
heading2: true、heading3: true	スペース区切りの文字列 format: "p h1 h2 h3" を指定します。_editables のキーとスキーマの対応を参照してください。
options.collections: [team]	value_key と preview を指定して values: collections.team を使用します。inputs.md § コレクションから選択肢を取得するを参照してください。
options.structures: my_blocks	完全なパス _structures.my_blocks を指定します。structures.md § 4 つのルールを参照してください。
timezone: "+10:00"	Australia/Melbourne などのトップレベルの IANA 名を指定します。デフォルトは Etc/UTC です。configuration.md § 生成された設定を確認するを参照してください。
paths.collections、paths.data	collections_config.<name>.path および data_config.<name>.path を指定します。
paths.output	このキーはありません。ビルドツールが出力ディレクトリを設定します。paths にはアセットディレクトリのみを指定します：static、uploads、uploads_filename、dam_uploads、dam_uploads_filename、dam_static、uploads_use_relative_path。
スキーマの列挙値にない Material Symbols 名（place など）	location_on など、列挙値にある名前を指定します。無効な名前はデフォルトのアイコンにフォールバックします。json-schemas.mdのアイコンに関するレシピで確認してください。

すべてのタスクに適用されるルール

• 開始する前に、検証チェックリストとSSGのチェックリストを確認し、目指す内容を把握してください。
• 両方のチェックリストのすべての項目を検証できた場合にのみ、完了してください。
• 編集者に表示されるすべてのフィールドに、明示的な_inputsエントリーを設定してください。型推論はフォールバックです。configuration.md § すべてのフィールドを明示的に設定するを参照してください。
• 変更を加えるたびに、npx @cloudcannon/cli validateを実行してください。キーに関する警告が表示された場合は、§ 無効なキーで正しいキーを確認してください。

目次

ファイル	読むタイミング
configuration.md	設定を書くときは、まず必ず読みます。手順と共通の検証チェックリストが記載されています。
json-schemas.md	キーを書く前に読み、スキーマにそのキーが存在することを確認します。
cloudcannon-cli-guide.md	ベースラインを段階的に生成するとき、または検証するときに読みます。CLI の残りの機能については cloudcannon-cli を参照してください。
schemas.md	コレクションを追加する前、または schemas を記述する前に読みます。1 つのコレクションに複数のスキーマを含められます。
inputs.md	_inputs を記述する前に読みます。
structures.md	フィールドに配列やオブジェクトが含まれる場合に読みます。ストラクチャがないと、エディターで項目を追加できません。
collection-urls.md	コレクションがページを生成する場合、または Visual Editor でページを読み込めない場合に読みます。
build-commands.md	install_command や node_version を記述するとき、またはビルドにジェネレーターやビルド後の手順がある場合に読みます。
routing.md	サイトでレスポンスヘッダー、リダイレクト、リライトを設定する場合に読みます（フレームワーク設定、_headers、netlify.toml、vercel.json）。
configuration-gotchas.md	設定中に、複数の SSG にまたがる注意点を調べる場合に読みます。
troubleshooting.md	設定にすでに問題があり、症状をもとに作業する場合に読みます。

SSG 固有の情報： SSG の overview.md から読み始めてください。読む順序と、その SSG に関するすべてのファイルが記載されています。

サイトで使用するもの	最初に読むファイル
Astro	astro/overview.md
Hugo	hugo/overview.md
Eleventy	eleventy/overview.md
Next.js	nextjs/overview.md

その他のスキル：

スキル	読むタイミング
make-site-multilingual	多言語サイトを設定するときに読みます。ロケールデータセット、ロケールごとのコレクション、ロケール接頭辞付き URL が含まれます。
cloudcannon-dev-server	ユーザーが設定済みのサイトを CloudCannon で開き、コレクションや入力項目を試したい場合に読みます。