リファレンス

リファレンスページは、ファイル形式、コマンド、制限の集合など、名前で呼べる 1 つの対象についての事実を、漏れなく均一な構造で列挙します。トーンは平易で率直です。

読者が 1 つの対象について正確な事実を調べる必要があるときに、リファレンスページを使います。このタイプを支配する法則は 2 つです。完全性（欠けた項目は、辞書から単語が欠けたのと同じようにリファレンスを壊します）と均一性（すべての項目が同じ順序で同じ問いに答えること）です。次のようなものではありません。

• ハウツー。 リファレンスは説明し、手順は示しません。「これを行うには、まず ...」という項目があるなら、ハウツーを切り出してリンクします。
• コンセプト。 見解と根拠はコンセプトページに置きます。冒頭で許される本文は、コンセプトへのリンク付きの導入文 1 文だけです。
• 寄せ集め。 「その他」に置いた事実は見つからなくなります。1 ページにつき 1 対象にし、プロダクト自身の構造をミラーします。

全体の比較は コンテンツタイプ を参照してください。実例は よくある Cf-Polished ステータス と Logpush API の設定 を参照してください。

• タイトル: 読者が検索するときの対象名です。例: 「CLI commands」「Event types」「Limits」。単独のページには「Reference」を使い、子ページがあるセクションには名詞を使います。裸の名前が曖昧なときだけ、名詞に "reference" を足します（例: 「Retry policy reference」）。
• 説明: 対象が受け入れる項目の種類と、各項目が列挙する事実のカテゴリを書きます。

Nimbus の reference レシピを使って、このページを生成します。コーディングエージェントがページのひな形と自己レビュー用チェックリストを取得し、製品に合わせて調整します。

npx @cloudflare/nimbus-docs add content-reference

yarn @cloudflare/nimbus-docs add content-reference

pnpm @cloudflare/nimbus-docs add content-reference

レシピが出力する frontmatter を Cloudflare のスキーマに合わせて調整します。レシピが出力する type などの汎用フィールドではなく、pcx_content_type と products を設定します。

• テーブル が代表的なコンポーネントです。項目の前にクイックリファレンステーブルを置くと、よくある参照をスクロールなしで済ませられます。テーブルは単純に保ちます。セル結合やレイアウトで意味を持たせると、スキャンも抽出も壊れます。
• 定義行 は、型、デフォルト、必須、制約など、同じ事実を決まった順序で持ちます。太字やバッジの付け方をすべての項目で揃えます。
• DirectoryListing は、リファレンスが単独ページではなくセクションであるときに、子ページへリンクします。
• 向かないもの: Steps、Cards、コールアウト（警告が必要な事実は、通常は項目内の制約として書きます）。項目を隠すタブやアコーディオンも避けます（折りたたまれた項目は、検索して拾う読者にも抽出にも見えません）。

pcx_content_type: reference
products:
  - product-a
  - product-b

詳しくは pcx_content_type を参照してください。

リファレンスは完全であるか、範囲を明確に区切るかのいずれかです。中間はありません。サブセットが別の場所にあるなら、先頭行でその場所を示します。各事実の情報源は 1 つだけにします。コードやスキーマにある値は生成し、まだ生成できない場合は情報源を明記して、メンテナーが何と差分を取るかを分かるようにします。制限やクォータなど、手メンテの事実ページには、見える reviewed 日付を付けます。対象がおよそ 30 項目を超えたら、ファイル構成やコマンドグループなど、対象自身の切れ目で分割します。アルファベット順では分割しません。

• 自己識別できる項目。 すべての項目見出しにフルネームを付けます。例: 「Retry」見出しの下の max_attempts ではなく、ドット区切りパス retry.max_attempts。取り出したチャンクが自分の身元を持てるようにします。
• 機械で検証できる値。 範囲、デフォルト、制限は「妥当な数」ではなくリテラル値で書きます。例はフェンス付きブロックに、現実的な値で最小限にします。
• 隠さない。 すべての項目を開いたままにします。折りたたみやタブの中の項目は抽出から見えません。リファレンスページの Markdown 版が、そのページです。