コンテンツ要素ルール：各ブロックを使用するタイミング

SEOプレイブックのすべてのページは、ある区別に依存しています。それは、コンテンツには目的があり、見出しレベルや視覚的表現は単なるプレゼンテーションに過ぎないということです。これらの要素作成ルールは、その区別を制作契約に変えます。コンポーネントを適用する前、記事を公開システム間で変換する前、または公開済みページにすでに表示されている要素を変更する前に、これらのルールに従ってください。

クイック概要

• 目的で 要素ライブラリ を確認します（名前ではありません）。要素の目的がセクションの役割と一致する場合、その要素は必須です。
• 型付き要素がその文章の目的を表していないことを確認した後にのみ、プレーンMarkdownを使用します。自由テキストはフォールバックであり、デフォルトではありません。
• まず記事全体をプレーンテキストで書きます。別の上から下への構造化パスで要素を適用し、構成とマークアップが注意を競い合わないようにします。
• Markdownディレクティブを正規の作成コンテンツとして扱います。HugoとWordPressのレンダラーは、同じフィールドと本文をプラットフォームネイティブの出力にマッピングします。
• 既存の公開済みページは、レビューされた意味のまま維持します。重大な定義変更は新しいバージョンと明示的なマイグレーションを作成し、古いコンテンツを黙って再解釈することは決してありません。

優先順位の基本ルール

ライブラリはその文章が何をするかによって確認する必要があり、執筆者がたまたま何と呼んだかではありません。名前は異なります。ある執筆者は「チャーンとは？」というセクションを設け、別の執筆者は「チャーン解説」、さらにもう一人は「実用的な定義」とタイトルを付けるかもしれません。それらの目的は同一であり、3つすべてが同じ定義要素にマッピングされます。

この優先順位が存在するのは、自由テキストと型付き要素が画面上では同じに見えても、下流ではまったく異なる動作をする可能性があるからです。スタイル付き見出しの後に段落が続くものは、ブラウザでは定義ボックスのように見えるかもしれませんが、コンポーネントとしての識別性を持ちません。定義の構造化出力を確実に生成したり、そのフィールドを別のレンダラーに公開したり、マイグレーション中にセマンティクスを保持したり、ページに定義が含まれているかどうかを問い合わせる品質チェックで見つけられたりすることはできません。型付き要素はコンポーネントと既知のデータ形状にマッピングされますが、視覚的に類似した自由テキストは何にもマッピングされません。

したがって、ルールは厳格です：

見出しやコンテンツブロックを書いたり承認したりする前に、その目的を特定してください。その目的が要素定義と一致する場合は、要素を使用してください。視覚的な類似性、既存のH2、または段落で同じ言葉を表現できる能力は、自由テキストを同等にしません。

優先順位は視覚的ではなく意味的です。要素の定義がそれを許可する場合、ページは要素の中や周囲に通常の見出しを含めることができますが、見出しが要素タイプを置き換えることは決してありません。

自由テキストと型付き要素

共有ダイアグラムが利用可能になるまでは、この決定パスを使用します：

1. 文章の役割を一つの動詞で述べます。 例としては、定義する、警告する、要約する、比較する、証明する、指示する、行動を促すなどがあります。これにより、見出しのテキストが背後にある目的を隠してしまうことを防ぎます。
2. その目的とその同義語でライブラリを検索します。 文字通りの見出し「Xとは？」だけを探している執筆者は、「定義ボックス」という名前のページを持つ定義要素を見逃す可能性があります。
3. 一致する要素がある場合はそれを使用します。 見た目を比較したり、Markdownでデザインを模倣できるかどうかを尋ねたりしないでください。登録された動作が決定要因です。
4. 目的が一致しない場合は自由テキストを使用します。 これは、接続的な説明、議論、分析、ナラティブコンテキスト、および記事のメインフローに属し、個別のコンポーネント動作を必要としないトランジションに適切です。
5. 繰り返し発生するギャップを記録します。 同じ一致しない目的が複数のページにわたって現れる場合は、一回限りのディレクティブやCSS処理を記事内で発明する代わりに、ライブラリ要素を提案します。

プレーンMarkdownは、言葉が記事の連続的な推論を形成し、独立したラベル、データ契約、インタラクション、再利用パスを必要としない場合に真に適切です。例えば、推奨事項が先行する証拠からなぜ導かれるかを説明する2つの段落は通常の散文です。ページ上部のコンパクトな結論セットは、箇条書きとして書けるという理由だけで通常の散文にはなりません。それには概要またはテイクアウェイ要素という認識された目的があります。

誤ったマークアップを引き起こす一般的な混乱

これらのケースは、視覚的なレビューを容易に通過するため、明示的にリストされています。間違いが明らかになるのは、別のレンダラー、バリデーター、検索インデックス、または構造化出力コンシューマーがページを受け取ったときです。

キーテイクアウェイとクイック概要の区別は特に重要です。項目が読者が覚えておくべき結論である場合はテイクアウェイを使用します。つまり、これらは多くの場合、記事が存在した後にのみ書くことができます。項目が読書前に範囲や順序について読者の方向性を定める場合は概要を使用します。現在のテーマで両方のコンポーネントが同じように見えても、その編集上の役割に基づいて選択してください。

ディレクティブと属性の構文

正規のMarkdown形式は、名前付きブロックディレクティブを使用します。属性はディレクティブ名の後にブレース内に続きます：

:::element-name{key=value key2="value with spaces" .class}
本文コンテンツ
:::

属性は、要素の意味やサポートされるプレゼンテーションに影響を与える、小さく安定したプロパティを保持するために存在します。これらを機械可読に保つことで、執筆者が設定を散文に隠すことを防ぎます。スペースのない値には key=value を、スペースが存在する場合は key2="value with spaces" を使用します。引用符で囲まれていない属性値にスペースを含めることはできません。 先頭のドットは、.compact のようにサポートされるクラスを追加します。ページ固有のスタイリングを発明する場所ではありません。

属性キーは小文字で、要素ページで定義された正確なスペルを使用します。ブール値および列挙値もそのページの契約に従います。レンダラーがたまたま許容するからといって属性を作成しないでください。宣言されていない属性にはクロスプラットフォームの保証がありません。

閉じる ::: フェンスは外側の要素に属します。パーサーが本文と次の段落を区別できるよう、それらを独自の行に配置してください。ディレクティブを示すコードサンプルは、このページのように、コードフェンスブロック内に収める必要があります。そうすることで、Hugoがそれらをコンテンツとして解釈しません。

デフォルトの本文マッピング

ほとんどの要素は短いタイトルと長い本文を必要とします。これらを属性として繰り返すよう執筆者に要求すると、長いテキストの編集が難しくなり、エスケープを誤りやすくなるため、本文がデフォルトのマッピングを提供します：

:::example
## 具体的な見出し

本文の残りの部分には、要素定義で許可されている段落、リスト、リンク、その他のコンテンツを含めることができます。
:::

要素ページが明示的にルールを上書きしない限り、本文の最初の見出しは title にマッピングされ、その見出し以降のすべては content にマッピングされます。見出しマーカーは編集者のためのソース階層を表現し、マッピングされたフィールドにより各プラットフォームがコンテキストに応じて適切な意味的見出しレベルをレンダリングできます。

最初の本文見出しのみがこの特別な扱いを受けます。後続の見出しは content の一部のままです。本文に見出しがない場合、title は存在しません。これは要素定義がタイトルをオプションとしている場合にのみ有効です。要素が名前付きスロットや異なるマッピングを定義する場合、レンダラーが各フラグメントの正確な所属先を把握する必要があるため、その要素のページがこのデフォルトよりも優先されます。

ネストされた項目

一部の要素には、各エントリに属性と本文が必要な繰り返し可能なリストが含まれます（例：識別子付きのステップ、ラベル付きのカード、初期状態付きのチェックリスト項目）。これらのエントリを1つのMarkdownリストに平坦化すると個々のフィールドが失われるため、ネストされた項目は明示的なアイテムディレクティブを使用します：

:::parent-element{variant=compact}
::item{key=value}
### 最初の項目タイトル

最初の項目の説明。
::
::item{key2="value with spaces"}
### 2番目の項目タイトル

2番目の項目の説明。
::
:::

契約は ::item{key=value} … :: です。各項目を開くのは2つのコロン、単数名は item、閉じるのも2つのコロンです。親は3つのコロンの閉じフェンスを保持します。この視覚的な違いは重要です。なぜなら、インデントに依存せずにネストを明確にし、コピーアンドペーストで容易に損なわれないからです。

各項目は、親要素ページが別途指定しない限り、同じデフォルトの本文マッピングを適用します。最初の見出しがその項目の title になり、残りが content になります。属性はその項目のみを説明する場合は項目に配置し、コレクション全体に影響する場合は親に配置します。

リンク、画像、インラインボタン

ポータブルなソースには予測可能なパスが必要です。相対URLは、サイトルートからの相対パスである必要があり、現在のMarkdownファイルからの相対パスではありません。なぜなら、同じソースがHugoで異なるファイルシステムの深さでレンダリングされたり、WordPressにインポートされたりする可能性があるからです。

• 内部ページリンクは、要素ライブラリ のリンクのように、先頭と末尾にスラッシュを使用します。../ を使用したり、先頭のスラッシュを省略したり、内部ページのプロダクションドメインをハードコードしたりしないでください。
• 外部リンクは完全な https:// URLを使用します。スキームは宛先の一部であり、レンダラーによって推測されてはいけません。
• 画像ソースファイルは cdn-assets/seo-playbook/ 以下にあり、その公開パスは /cdn-assets/seo-playbook/ で始まります。アセットが存在した後にのみ、承認されたグループとファイル名を追加してください。
• 代替テキストは、画像のファイル名や装飾的な外観ではなく、画像が伝える情報を説明します。装飾的な画像は空の代替テキストを使用しますが、該当する要素ページが明示的に装飾を許可している必要があります。
• インラインのコールトゥアクションは :button[表示ラベル]{href="/target/"} を使用します。ブラケット内のテキストがアクセシブルなラベルであり、href は同じ内部または外部パスルールに従います。ボタンは、通常の参照リンクをより目立たせるためではなく、真の次のアクションにのみ使用してください。

画像はコンテンツであり、サポートされていないレイアウトの回避策ではありません。画像に重要なラベル、数字、または指示が含まれている場合は、その情報をアクセシブルなテキストで繰り返すか、それを公開する構造化要素を使用してください。スクリーンショットのキャプチャリクエストは、名前付きアセットが存在するまでHTMLコメントのままです。これらは公開された画像参照ではなく、フロントマターで screenshotsPending = true を設定する必要があります。

フロントマターとボディ要素は異なる役割を持つ

フロントマターは、ドキュメントをドキュメントとして説明します。ボディディレクティブは、読書体験内の意味のあるブロックを説明します。これらのレイヤーを分離することで、一覧ページ、スキーマ、ルーティング、公開ツールが、可視の散文を解析せずにメタデータを読み取ることができます。

したがって、メタデータ要素はフロントマターに配置します：ページタイトル、説明、キーワード、公開日と更新日、正規またはエイリアス情報、所有権、タクソノミー、プレイブック結合、およびページ契約がそこに配置するスキーマ指向のコレクション（アカデミーページのFAQエントリなど）。これらのフィールドは ::: ディレクティブとして記述されることは決してありません。一部のメタデータを繰り返す可視ブロックがあっても、権威のあるフィールドがフロントマターから移動することはありません。独立した読者向けの目的がある場合にのみ、独自のボディ要素を受け取ります。

コンテンツ要素はボディに配置します：定義、警告、ヒント、概要、テイクアウェイ、チェックリスト、比較、エビデンスブロック、例、ステップ、コールトゥアクションなどです。これらがディレクティブであるのは、ナラティブ内での位置が重要だからです。警告をフロントマターに移動すると、それが修飾する文章から切り離されてしまいます。メタデータをボディディレクティブに隠すと、ドキュメントレベルのシステムが確実にそれを見つけられなくなります。

メタデータはデフォルトで必須

メタデータは、誰かがボディを読む前に、ルート、プレビュー、発見、結合、構造化出力を駆動します。したがって、フィールドが欠落していると、記事をレンダリングしないコンシューマーに影響を与える可能性があります。そのため、各メタデータ要素は、その要素ページが明示的にオプションであると示さない限り必須です。

必須とは、単に空の文字列や空のコレクションとして存在するのではなく、有効な値が入力されていることを意味します。他のページの省略からオプション性を推測したり、バリデーションを満たすためにプレースホルダー値を追加したりしないでください。必要な値がまだ不明な場合、そのページは公開準備ができていません。ボディ要素は、このメタデータのデフォルトではなく、関連する投稿タイプと要素ページの要件ルールに従います。

最初に書き、次に要素を適用する

要素の選択は分類タスクであり、ドラフト作成は推論タスクです。両方を一文ごとに行おうとすると、執筆者はコンポーネント境界に対して早期に最適化してしまいます。その結果、トランジションが弱くなり、ボックスに合わせた浅い説明、マークアップを満たすために作成された繰り返しの見出し、目的が一致しているからではなく都合が良いから選ばれたディレクティブが生じることがよくあります。

したがって、制作は2つの明確なパスで行われます：

1. 記事全体をプレーンテキストとして書きます。 議論、例、限定条件、トランジション、結論を完成させます。この段階では、見出しはドラフトの論理を説明するかもしれませんが、最終的な要素タイプを確定するものではありません。
2. 別の上から下へのパスで要素を適用します。 各見出しとブロックについて、その目的を述べ、ライブラリを確認し、一致するセクションをラップし、宣言された属性を追加し、本文マッピングとネストを確認します。

この分離により、両方の出力が向上します。散文は現在のテーマのボックスサイズではなく読者の質問に応じて発展し、マークアップパスはドキュメント全体で類似したブロックを一貫して比較できます。また、省略も可視化されます。執筆者は、警告や定義をエンコードする方法を決定する前に、記事にそれが含まれていることを確認できます。

構造化パスの後、ディレクティブ名を見ずにページを一度読んでください。要素は首尾一貫した記事をサポートし、それを断片的なウィジェットの積み重ねにしてはいけません。その後、散文を判断せずにソースを一度検査し、フェンス、属性、ネストされた項目、パス、必須メタデータを確認します。

3つの表記法の契約

要素は、その目的、正規フィールド、許容値、本文マッピング、アクセシビリティ動作、構造化出力動作、およびバージョンによって一度定義されます。その定義が信頼できる情報源です。3つのプラットフォーム表記法はそれへのアダプターであり、3つの独立したコンポーネント設計ではありません。

代表的な形式はマッピングを説明します。個々の要素ページは、正確にサポートされる名前とフィールドを公開します。作成者は自身の公開ワークフローに必要な表記法で作業しますが、フィールドの名前を変更したり、プラットフォームのみの意味を追加したり、別のレンダラーのHTMLを手動で模倣したりしません。

要素所有者は正規の定義を維持し、提案された変更が互換性のあるものかバージョン付きのものかを判断します。HugoとWordPressの保守担当者は自身のアダプターを所有し、共有フィクスチャに対してテストします。同じタイトル、コンテンツ、属性、項目、リンク、アクセシビリティの期待が3つのパスすべてで生き残る必要があります。編集担当者は目的と例を検証します。プラットフォーム保守担当者がローカルで編集上の意味を再定義することはできません。プラットフォームが契約を表現できない場合、それはアダプターの欠陥または提案された契約変更です。

このモデルにより、プラットフォームが必要とする場合にプレゼンテーションを異ならせつつ、セマンティクスを安定させることができます。HugoはサーバーサイドHTMLをレンダリングし、WordPressはブロックコメントを保存するかもしれませんが、警告は警告のまま、チェックリスト項目は項目のままで、同じ必須フィールドが下流で利用可能なままです。

公開済み要素のバージョニング

公開済みコンテンツは、公開時点で存在していた要素の意味に対してレビューされました。その意味を黙って変更すると、編集者がページに触れることなく、警告、構造化データ、アクセシビリティ、またはインポートが変更される可能性があります。バージョニングはその編集上の承認を保護します。

以下の変更ポリシーを使用します：

• 互換性のあるレンダラー変更： 目的、フィールド、許容値、本文マッピング、出力の意味を保持する視覚的洗練、パフォーマンス改善、またはバグ修正は、現在のバージョン内で出荷できます。既存のページはレンダラーを通じてそれを受け取ります。
• 互換性のある追加変更： 新しいオプション属性は、その欠如が既存の出力を保持し、すべてのアダプターが安全に無視またはサポートできる場合にのみ、現在のバージョンに加わることができます。定義とプラットフォームテストは一緒に変更されます。
• 重大な変更： フィールドの名前変更または削除、新しい必須フィールド、本文マッピングの変更、目的の変更、意味的影響のあるデフォルトの変更、または互換性のないネスト構造は、新しいメジャー要素バージョンを作成します。
• 非推奨： 古いバージョンは公開済みページに対してレンダリング可能なままです。その要素ページは代替とマイグレーションパスを特定し、新しいページは現在のバージョンを使用します。
• マイグレーション： コンテンツのマイグレーションは、明示的で、スコープが定められ、Markdown、Hugo、WordPress全体でプレビューされ、公開前に編集的に検証されます。どのページが変更されたか、その理由を記録してください。レンダラーに古いソースをどのように再解釈すべきかを推測させないでください。

ソースにバージョンが記述されていない場合、要素はこの契約が採用された時点で定義されたベースラインバージョンを使用します。その暗黙のベースラインは安定していなければなりません。新しいメジャーバージョンは、要素ページで宣言されたバージョンメカニズムを使用して識別されます。バージョンなしの構文を流用することはありません。

ロールバックも重要です。マイグレーションされたページが構造的、視覚的、アクセシビリティ、構造化出力のチェックに合格するまで、以前のレンダラーとソース表現を利用可能にしておいてください。マイグレーションが失敗した場合は、要素を自由テキストに平坦化するのではなく、以前のバージョンマッピングに戻してください。自由テキストにすると、バージョニングが保護しようとするセマンティクスが破棄されます。

制作レビューチェックリスト

散文パスと要素パスの後、この最終レビューを使用します：

• 散文以外のすべてのブロックの目的を一つの動詞で述べることができますか？
• その目的と近い同義語でライブラリを検索しましたか？
• 一致するすべての目的について、H2と段落が似たように見えても、型付き要素を使用していますか？
• 残りのすべての自由テキストの文章は、記事の継続的な説明、分析、ナラティブ、またはトランジションの一部ですか？
• 属性は {key=value key2="value with spaces" .class} に従い、スペースは引用符で囲まれ、宣言されたキーのみを使用していますか？
• 最初の本文見出しは title に、残りは content にマッピングされていますか（要素ページが別のマッピングを宣言している場合を除く）？
• 繰り返し可能な子要素は ::item{key=value} … :: を使用し、親と項目の属性は正しいレベルに配置されていますか？
• 内部リンクは先頭と末尾のスラッシュ付きでルート相対、外部リンクは絶対パス、画像パスは承認された画像ルート内ですか？
• メタデータフィールドはフロントマターにあり（ボディディレクティブにはなし）、すべての必須メタデータ値が完了していますか？
• 同じ正規フィールドが損失なくMarkdown、Hugo、WordPressにマッピングできますか？
• 定義の変更は古いページを保存するか、明示的なバージョンとマイグレーションを導入していますか？

このページは、個々の要素ページすべての前提条件です。各要素定義はこれらの基本ルールにリンクバックし、その目的固有の例外（サポートされる属性、必須フィールド、本文または項目マッピングのオーバーライド、許可されるネスト、正確なプラットフォーム名、バージョン履歴）のみを文書化する必要があります。要素ページが黙示的な場合、このページのデフォルトが適用されます。