ドキュメントサイトのMDXページを、決まりどおりエラーなく書く

## 書く前に、ドキュメントサイトの作りを調べる リポジトリをMarkdownファイルの緩やかな集合ではなく、スキーマ駆動型のドキュメントアプリケーションとして扱います。 サイトジェネレーター、ドキュメントテーマ、コンポーネントフレームワーク、パッケージマネージャー、ランタイムバージョン、デプロイ先を特定します。 リポジトリで固定された再現可能なコマンドを使って依存関係をインストールします。 ランタイムとパッケージマネージャーのバージョンを、リポジトリのメタデータと一致させます。 慣例的な名前を想定せず、主要な貢献ブランチを確認します。 ユーザー向けページ、再利用可能なパーシャル、変更履歴、用語集データ、製品メタデータ、その他の構造化コレクションを区別します。 カスタムコンポーネント、コンテンツスキーマ、Markdownプラグイン、コード強調表示プラグイン、アイコン、アセット、スタイル、動的ルートを、それぞれ指定された層に保ちます。 静的なpublicファイルと、サイトジェネレーターが処理する画像を区別して扱います。 中央のコンポーネントエクスポートモジュールを、MDX用の公開インポート窓口として使います。 コレクションスキーマを、受け付けるフィールドと値の型に関する正本とします。 生成されたスキルまたは参照ディレクトリをビルド成果物として扱います。 生成ディレクトリを編集したり、無視対象の生成コンテンツをコミットしたりしてはいけません。 専門的なレビューボットやデプロイワーカーを変更する前に、ネストされた指示を読みます。 リポジトリ固有のスタイル、コンポーネント、手順の参照資料を正本の指針として使います。 一般的なMarkdownの習慣を、サイトのMDX規則やスキーマ規則より優先してはいけません。 ## ページを正しいフォルダーに置き、ファイル名の決まりを守る ユーザー向けドキュメントのページは、製品または主題のディレクトリ配下に置きます。 再利用可能なスニペットは、パーシャルコレクションに置きます。 変更履歴の項目は、対応する製品または主題のサブディレクトリに置きます。 用語集の用語やその他の構造化メタデータは、それぞれのスキーマが管理するコレクションに置きます。 サイトが要求する場合は、ナビゲーション可能なすべてのコンテンツフォルダーにインデックスページを必須とします。 単語をハイフンで区切った小文字のファイル名を使います。 コンテンツディレクトリ内のファイルを、明示的に許可されたテキストおよびデータ拡張子に限定します。 一般的に許可される型は、MDX、JSON、YAML、プレーンテキストです。 サポート対象外のファイルを隠さず、拡張子検証によって許可リストを適用します。 スキーマの走査対象となるコンテンツディレクトリ内に、画像や任意のバイナリを置いてはいけません。 処理可能な画像は、最適化用の専用アセットツリーに置きます。 本当に静的なファイルは、変更せず配信する必要がある場合に限りpublicツリーに置きます。 ディレクトリ名を既存の製品メタデータと一致させます。 未知の製品キーに対して、変更履歴またはコレクションのサブディレクトリを作成してはいけません。 並行するコンテンツ配置を新設せず、確立されたコレクション境界を維持します。 ページを移動する場合は、そのページへのリンク、ナビゲーションメタデータ、リダイレクト、関連するパーシャルの参照を更新します。 ## ページ先頭の設定欄（frontmatter）を、サイトの決まりどおりに書く すべてのドキュメントページに、そのコレクションスキーマを満たすフロントマターブロックを設けます。 簡潔なページタイトルを指定します。 選択したコンテンツ型で必要な場合は、検索用の説明を指定します。 リポジトリで許可された列挙値からページ型を選びます。 一般的な型には、`concept`、`configuration`、`example`、`FAQ`、`getting started`、`how-to`、`integration`、`implementation`、`overview`、`reference`、`release notes`、`solution`、`troubleshooting`、`tutorial`があります。 スキーマで提供されている場合は、`design guide`、`learning unit`、`navigation`、`reference architecture`、`video`などの専用型を使います。 サイドバーの順序は、明示的な並び順が必要な場合に限って使います。 ナビゲーションの文言をページタイトルと異ならせる場合に限り、サイドバーラベルを使います。 既存のメタデータキーを通じて製品または主題を参照します。 チュートリアルコンテンツには、文書化された難易度の列挙値を使います。 レビュー日を必須の年月日形式で記録します。 スキーマフィールドや列挙値を新たに作り出してはいけません。 YAMLのインデントとリスト構造を有効な状態に保ちます。 コレクション定義またはスキーマを変更した後は、コンテンツコレクションの型を再生成します。 目視確認に頼らず、データファイルをスキーマに照らして検証します。 ページの目的、製品、タイトル、レビュー状態が変わった場合は、ページメタデータを同期させます。 ## MDXの書き間違いでエラーにならないように本文を書く リポジトリの正本となる執筆・書式ガイドに従います。 MDXを、Markdownに埋め込みコンポーネント言語を加えた、より厳密な解析を行う形式として扱います。 波括弧や山括弧を文章として使う場合は、エスケープするかコード書式にします。 MDXは文章内であっても、それらの文字を式またはコンポーネントとして解釈することを忘れないでください。 ページで使うすべてのコンポーネントをインポートします。 インポートはフロントマターの直後、ページ本文の前に置きます。 サポートされている構文強調表示の言語識別子だけを使います。 一般的な端末の出力には、リポジトリで指定されたプレーンテキスト言語識別子を使います。 コードフェンスでは、小文字の言語識別子を使います。 サイト内部のリンクには、ルートからの絶対パスを使います。 内部のリンク先に本番環境の完全なURLを使ってはいけません。 サポート対象外の相対ページリンクを使ってはいけません。 見出しレベルを順番どおりに保ち、途中のレベルを飛ばしてはいけません。 コピー可能なコマンドには、シェルのプロンプト記号を含めません。 操作、場所、期待される結果が明確な簡潔な手順を書きます。 複数のページで同じ保守対象の説明が必要な場合は、再利用可能な説明をパーシャルに置きます。 コード例を、文書化されたAPIと現在の製品動作に照らして検証します。 ## コンポーネントと画像を決まりどおりに使い、転送の設定は必要な時だけ変える MDXコンポーネントは、リポジトリ中央のコンポーネント一括エクスポートからのみインポートします。 必須プロパティと使用上の制約について、コンポーネントのドキュメントを参照します。 サポートされる公開コンポーネントがある場合は、その内部実装をコンテンツへコピーしてはいけません。 新しいコンポーネントコードは、指定されたコンポーネントディレクトリに置きます。 必須のカスタム要素プレフィックスとケバブケースの命名規則を使います。 各コンポーネントを、そのコンポーネント名と同じディレクトリに置きます。 必須の接尾辞を付けたパスカルケースのクラス名を使います。 新しいプレフィックス規則を適用するためだけに、適用除外のレガシー要素の名前を変更してはいけません。 元画像は、その製品または主題用に最適化されたアセットディレクトリに保ちます。 ローカルでの完全ビルドを通じて画像パスを検証します。 リダイレクトは、ページ移動またはURL移行で必要な場合に限って変更します。 リダイレクト元のパスは、必須のスラッシュ、または許可されたファイル接尾辞かワイルドカード接尾辞で終えます。 リダイレクト元のURLにフラグメントを含めてはいけません。 レビュー前にリダイレクトループを検出します。 リダイレクトファイルを変更した場合は、必ず専用のリダイレクト検証ツールを実行します。 コンポーネント、画像、リンク、リダイレクトの変更を、ページの意図した範囲内に保ちます。 ## 手元と自動チェック（CI）で必要な確認を通してから、仕上がりを伝える コンテンツを変更するたびに、スキーマ検査と型検査を実行します。 ローカルで完全ビルドを行い、MDXの解析、画像パス、内部リンクを検証します。 ローカルで完全検証ビルドを行う際は、内部リンク検査を有効にします。 制約のあるCI内では、タイムアウトすることが既知の完全ビルドを実行してはいけません。 CIでは、安全性を保った縮小セットとして、型検査、リンティング、書式検査を実行します。 コードを変更した場合は、リポジトリの完全なテストスイートも実行します。 コミットする前に、編集したすべてのファイルを書式設定します。 自動修正後に、リポジトリの書式検査を実行します。 リダイレクト設定を変更した場合に限り、リダイレクト検証を実行します。 スキーマまたはコレクションを変更した後は、コレクション型の同期を実行します。 実用的な範囲で、ローカルの完全検証手順をCIパイプラインと一致させます。 CIでは、ファイル拡張子、型、リンティング、書式、ビルドとリンク、リダイレクト、テストが検査されるものと想定します。 スタイルスキャナーの警告は、重大な失敗でない場合でもレビューの証拠として扱います。 直接関連する検証ゲートが欠けている間は、ページの準備が完了したと報告してはいけません。 CI環境の制約と実際のコンテンツ障害を区別します。 修正のために編集するたび、直接影響を受ける検査を再実行します。 ## 一覧のデータファイルに、ツールで作ったIDを付けて変えずに保つ すべてのディレクトリエントリーデータファイルに、必須の先頭行位置で一意かつ安定した識別子を指定します。 リポジトリで厳密に定められた識別子の長さと、混同を減らした文字集合を使います。 6文字方式では、生成されたすべての値が正確に6文字であることを検証します。 方式で求められる場合は、見た目が紛らわしい文字を除外します。 識別子を名前から導出せず、ランダムに生成します。 識別子を手作業で作成、推測、コピーしてはいけません。 リポジトリの識別子ツールを使って、コレクション全体を検査します。 識別子の欠落、形式不正、重複には、そのツールの修正モードを使います。 表示名またはファイル名が変わっても、既存の有効な識別子を維持します。 確認済みの検証エラーを修復する場合に限り、既存の識別子を変更します。 必須のYAML拡張子を1種類だけ一貫して使います。 識別子の生成を編集上の選択ではなく、自動処理として扱います。 ディレクトリコレクション全体で一意性を確認します。 識別子の生成とスキーマ検証をCIに組み込みます。 生成された変更をコミットする前に、ツールの差分をレビューします。 ツールが成功した後に、生成済みの識別子を手動調整してはいけません。 ## 作業ごとの手引きとコミットの決まりに従って、変更を出す 執筆、編集、例のレビュー、変更履歴の追加、プルリクエストの準備を行う前に、リポジトリの貢献ルーターを使います。 そのルーターが選択したタスク固有の参照資料に従います。 専門ボットのコード、ワークフローのルーティング、状態、デプロイを変更する前に、そのボットのローカル指示を読みます。 ツール固有のシンボリックリンクが、コミット済みの共有エージェント設定を指す状態に保ちます。 説明がタスクと一致する場合に限り、リポジトリスキルを読み込みます。 文章と書式の判断には、正本のスタイルガイドを使います。 プロパティ、例、必須パターンについては、コンポーネントカタログを使います。 段階的な手順には、手順ガイドを使います。 コード変更の影響を受ける各ランタイムワークスペースでテストを実行します。 ワーカー、サーバーランタイム、サイトジェネレーターのテストを区別します。 リポジトリで受け付けられる、製品名または型を接頭辞にした形式でコミットを書きます。 コミットの説明を、ユーザーから見える修正または技術的修正に特化させます。 無関係な書式変更、生成コンテンツ、製品変更を含めてはいけません。 コンテンツ、スキーマ、インポート、アセット、リンク、リダイレクト、テスト、貢献規則が一致する場合に限り承認します。