見出しシステム：H1、H2、H3のルール

見出しシステムとは、1つのページタイトルとそのセクションラベルの順序付けられたセットです。長いページを、人にとっては読みやすい経路に、検索エンジン、支援技術、AI回答システムにとっては機械可読なアウトラインに変換します。

上記のページタイトルは、このページの唯一のH1です。以下にある各主要仕様はH2であり、主要セクション内の細分化はH3です。この実際のアウトラインがレンダリングされた要素です。そのレベルはフォントサイズではなく関係性を表現しています。

この要素が重要な理由

読者が長いページを一度の中断なく読了することは稀です。読者は認識可能な質問をスキャンし、セクションラベルを現在のニーズと比較し、どこでじっくり読むかを決定します。説明的な見出しはその労力を軽減します。なぜなら、各見出しはその後に続く内容について小さな約束をするからです。「安定した見出しIDが引用を保存する仕組み」は一目で有用ですが、「いくつかの追加の考え」はそうではありません。

同じ階層は機械による抽出可能性もサポートします。つまり、自動化されたシステムがセクションを識別し、それがページトピックにどのように関連するかを理解し、隣接するセクションと混同することなく取得できることを意味します。H1はページの主題を確立します。H2はその主題を主要な関心事に分割します。H3は1つのH2を方法、事例、基準、または例外に絞り込みます。レベルをスキップするとその関係性が隠され、パーサーはサブセクションが兄弟なのか、子なのか、無関係なブロックなのかを推測せざるを得なくなります。

見出しはまた、アドレス指定可能なセクションを作成します。フラグメント識別子とは、URLの#以降の部分、たとえば#qa-checklistのことです。検索結果、内部リンク、ブラウザのブックマーク、AI回答はその正確な宛先を指すことができます。そのため、自動生成されたIDを軽率に変更すると、ページ自体が存在していてもURLが壊れる可能性があります。見出しは装飾ではありません。そのテキストはセクションを定義し、そのIDは耐久性のある公開アドレスになります。

セクションの目的が型付き要素に一致する場合は、要素執筆ルール に従ってください。「警告」というH2は警告ボックスに代わるものではなく、「比較」というH2は比較表に代わるものではありません。見出しはドキュメントの階層を提供し、型付き要素は目的固有の構造を提供します。両方が必要な場合もあります。

使用すべき場合

実質的なインデックス可能なすべてのページで見出しシステムを使用してください。短いページでも1つのH1が必要です。読者が異なる質問、段階、基準、またはエビデンスグループ間を移動する必要がある場合は、H2セクションを追加します。H2に、個別のナビゲーションが有益な少なくとも2つの明確に異なる部分が含まれる場合にのみ、H3サブセクションを追加してください。

見出しのように見えるが記事のアウトラインに属さない視覚的なラベルは、ほぼ該当するケースです：

• カードタイトルは繰り返されるカードの1つに名前を付けます。自動的にドキュメントセクションにはなりません。
• 「ヒント」や「重要」などのコールアウトラベルはボックスタイプを識別します。太字だからといってH2になるわけではありません。
• チャートタイトルは図を識別します。チャートが完全なセクションを開始する場合を除き、図のキャプションまたはアクセシブルな名前に属します。
• ナビゲーションメニューラベル、パンくずリスト、タブ、アコーディオンコントロール、フッター見出し、モーダルタイトルにはコンポーネントのセマンティクスが必要な場合がありますが、メインの記事階層には入りません。
• 大きなプロモーションスローガンは表示用コピーです。フォントサイズがそれをドキュメントのH1に昇格させることはできません。

1文を紹介するためだけ、連続した説明を分割するため、または視覚的な余白を作るために見出しを追加しないでください。そのような目的には段落の間隔や編集を使用してください。有用な見出しは、明確な読者のニーズに応えるのに十分な実質を持つセクションを示します。

見出しの配置場所

位置は親子関係を表現します。H1をメインコンテンツの先頭、パンくずリストやその他のサイトナビゲーションの後、導入の前に配置してください。各H2をプライマリセクションの前に配置します。H3は、その親H2と親の方向付けコンテンツの後にのみ配置し、最初のH2より前や、視覚的な外観のために選択された同列の要素として決して配置しないでください。

執筆された記事コンテンツでは、2つの見出しが隣接してはいけません。すべての見出しは、同じまたはより深いレベルの次の見出しの前に、有用なコンテンツを所有していなければなりません。このルールは空のセクションラベルを防ぎ、サブセクションリストの前に読者にコンテキストを与え、素のアウトラインではなく抽出可能なパッセージを作成します。

構成要素

ラベル付きの構成要素には5つの部分があります：

1. H1： 一意のページ主題であり、コンテンツアウトラインの最上位。
2. H2： その主題内のプライマリな質問、段階、または側面。
3. H3： 親H2なしでは正しく理解できない子トピック。
4. 所有コンテンツ： 1つの見出しから同じまたは上位レベルの次の見出しまでの間にある回答、エビデンス、指示、または説明。
5. 安定したID： 見出しに付加され、公開後も保存されるフラグメントの宛先。

タイポグラフィが変更されても、この関係は有効なままです。テーマはモバイルでH2を小さいフォントでレンダリングするかもしれませんが、HTMLではH2のままである必要があります。逆に、段落を大きく太字にしても、見出しのセマンティクスやフラグメントの宛先は与えられません。

デザイン例

デザインのバリエーションは、任意の色オプションではなく、セマンティックレベルと実際の折り返し状態に対応します。

H1ページタイトル： メインコンテンツの先頭に一意の主題を表示します。補足的な説明が続くことはありますが、アイブロウ、ロゴ、ヒーロースローガンが別のH1になることはありません。

H2プライマリセクション： 目次からセクションが理解可能であるようにし、その後に範囲を確立するコンテンツを続けます。

H3サブセクション： デザイナーがより小さいテキストを望んだからではなく、トピックが従属的であるためにより低いレベルを使用します。

折り返された見出し： 狭い画面では自然な2行の折り返しを許可します。1行に収めるためだけに明確な見出しを曖昧なラベルに短縮しないでください。

アンカー状態： アンカーが宛先を理解する唯一の方法にならないように、ホバーとキーボードフォーカスを表示します。直接ナビゲーションでは、見出しが隠れないようにスティッキーヘッダーをオフセットする必要があります。

パラメータ

見出しシステムは装飾的なコンポーネントではなく、ドキュメントの契約です。そのパラメータは、アウトライン、読者が見るテキスト、各ノードが所有するコンテンツ、およびそのノードに到達できるURLを定義します。

文字数と語数の制限は編集上の範囲であり、必要な具体性を省略する理由にはなりません。類似した2つの手順を区別する94文字の見出しは、短くても誤解を招く見出しより優れています。構造上の制限は厳格です：1つのH1、スキップされたレベルなし、重複IDなし、空のセクションなし。

構文とコード例

標準的なポータブル形式は、ネイティブのアウトラインをheading-systemディレクティブでラップします。最初の見出しがドキュメントタイトルにマッピングされ、後続の見出しは順序付けられたコンテンツノードのままです。明示的なIDは、見出しが公開された後に追加されます。

ポータブルMarkdownディレクティブ

:::heading-system
# ダウンタイムなしでAPIキーをローテーションする

古いキーを失効させる前に、依存するすべてのサービスで認証情報を置き換えてください。

## 置き換えの準備

現在認証情報を読み取っているすべてのサービスを記録します。

### 隠れたコンシューマを特定する

スケジュールされたジョブ、デプロイメントシークレット、ローカル統合を確認します。

## 検証と失効

置き換えをテストし、露出したキーを失効させます。
:::

公開時には、将来のテキスト編集で再生成されないように、安定したIDを固定します：

## Prepare the replacement {#prepare-replacement}
### Identify hidden consumers {#identify-hidden-consumers}

Hugoショートコード

{{< heading-system h1="Rotate an API key without downtime" >}}
## Prepare the replacement {#prepare-replacement}

Record every service that currently reads the credential.

### Identify hidden consumers {#identify-hidden-consumers}

Check scheduled jobs, deployment secrets, and local integrations.
{{< /heading-system >}}

これはHugoアダプター契約であり、このリポジトリがheading-systemショートコードを登録しているという主張ではありません。Hugoの実装は、このページが行うように、同じ階層を検証し明示的なIDを保持する限り、フロントマターからH1を、Markdownを通じて本文見出しをレンダリングし続けることができます。

WordPressブロック

<!-- wp:heading {"level":2,"anchor":"prepare-replacement"} -->
<h2 id="prepare-replacement">Prepare the replacement</h2>
<!-- /wp:heading -->

<p>Record every service that currently reads the credential.</p>

<!-- wp:heading {"level":3,"anchor":"identify-hidden-consumers"} -->
<h3 id="identify-hidden-consumers">Identify hidden consumers</h3>
<!-- /wp:heading -->

WordPressはH1をページタイトルフィールドまたは承認されたヒーローブロックに保存し、記事本文の2番目の見出しブロックとしては保存しないでください。公開された各見出しのHTMLアンカーを明示的に設定して、後での文言編集がURLを黙って変更しないようにしてください。

例

良い例：アウトラインが完全な回答を予測する

# How to choose an invoice approval workflow

## Define the approval risk
Explain which invoice values, vendors, and exceptions need review.

### Set value thresholds
Assign a named approver to each threshold and document what happens at the boundary.

### Route policy exceptions
Send missing purchase orders and changed bank details to a separate review path.

## Test the workflow
Run ordinary and exceptional invoices through the complete route before launch.

これが機能する理由は、H1が1つのタスクを述べ、各H2が主要な段階に名前を付け、各H3がその親に属し、すべてのラベルにその約束を果たすコンテンツが続くからです。読者はアウトラインをスキャンして、しきい値、例外、テストがどこでカバーされているかを予測できます。

悪い例：スタイリングが階層の代わりになっている

# Invoice approval

### Things to think about
## More information
### Exceptions
### Other

これは4つの独立した理由で失敗します。H1からH3にスキップし、回答を予測しないラベルを使用し、所有コンテンツなしで見出しを隣接させ、次の見出しの前に説明のない「例外」を残しています。結果のアウトラインは、ページが提供していないカバレッジを示唆しています。また、#otherのような弱い自動生成IDを作成し、ページ外で引用された場合に曖昧になります。

スキーママークアップとアクセシビリティ

見出しに独立したSchema.orgタイプは必要ありません。H1は通常、Article、TechArticle、またはその他の適切なページエンティティのheadlineを提供またはミラーリングしますが、表示される文言とJSON-LDは同じ主題を説明する必要があります。H2およびH3セクションはHTML構造のままです。すべての見出しに対してスキーマエンティティを作成しないでください。「よくある質問」というタイトルの見出しも、それだけでFAQPageマークアップを作成するわけではありません。表示される質疑応答データがFAQ要素契約を満たす必要があります。

アクセシビリティはセマンティックHTMLと論理的な順序に依存します。スクリーンリーダーユーザーは見出しでナビゲートし、見出しリストを検査し、セクション間を直接ジャンプできます。このワークフローは、ページがスタイリングのためにレベルをスキップしたり、太字の段落を偽の見出しとして使用したり、ユーティリティと記事の見出しを1つの一貫性のない階層に含めたりすると壊れます。

実際の<h1>、<h2>、<h3>要素を使用してください。見出しテキストは表示可能に保ってください。aria-labelが画面上の明確な文言を置き換えてはいけません。アンカーコントロールには、説明的なアクセシブルな名前、表示可能なキーボードフォーカス、そして見出し全体のリンクが選択を混乱させる場合には見出しテキストとは別のクリックターゲットが必要です。フラグメントURLが読み込まれたとき、キーボードフォーカスは自動的に移動する必要はありませんが、宛先の見出しは表示可能であり、スティッキーヘッダーで覆われていない必要があります。

見出しIDはページ内で一意でなければならず、文字で始める必要があります。小文字、ハイフン区切り、読みやすいものにし、一時的な日付や位置番号を避けてください。表示される見出しが「結果を検証する」から「新しい認証情報が機能することを検証する」に改善されても、安定したIDは#verify-resultsのままで構いません。セクションの意味が完全に変わった場合は、新しいIDを作成し、プラットフォームがサポートする場合にはエイリアスまたは文書化されたリダイレクト動作を通じて古いフラグメントを保持してください。別個のアンカーリンク 仕様がアンカーナビゲーションとインタラクションの詳細を規定しています。

執筆ルール

個々のラベルを洗練する前に、ページのアウトラインを書いてください。各見出しは「ここで何を学び、決定し、行うのか？」に具体的な言葉で答えるべきです。「価格に関する考慮事項」よりも「年間請求と月間請求のコストを比較する」を、「トラブルシューティング」よりも「インポートが重複IDを拒否する理由」を優先してください。説明的であることは冗長であることを意味しません。ラベルがセクションの実際のコンテンツを予測することを意味します。

20～80文字のH1を1つ使用してください。H2およびH3の見出しは2～12語、90文字以内を推奨します。長いガイドには通常3～12のH2セクションがあります。H2は、H3の前に少なくとも1つの範囲または回答の文が必要です。親の下で2つ以上のH3セクションを使用すると細分化が役立ちます。1つのH3だけでは、そのコンテンツをH2に統合すべきであることを示していることがよくあります。

固有名詞や製品名で大文字が必要な場合を除き、文の先頭だけを大文字にするスタイル（sentence case）を使用してください。セクションが正確な質問に即座に答える場合、質問形式が適切です。宣言型のラベルは、段階、基準、発見事項、仕様に適しています。並列セクションは文法的に並列にしてください：プロセスシーケンスには動詞、比較基準には名詞、FAQセットには質問を使用します。

見出しテキスト内に以下を決して入れないでください：

• Markdownリンクまたは生のURL。競合する宛先と不安定なアクセシブル名を作成します。
• 脚注マーカーまたはソース引用。エビデンスは所有コンテンツに配置してください。
• 構造ラベル、ステータスバッジ、または装飾的な接頭辞として使用される絵文字。
• 投稿タイプが安定した順序付けられたシーケンスを定義している場合を除く手動番号付け。
• 「今すぐ購入」などのCTA言語、価格主張、緊急性、またはプロモーションバッジ。
• スタイリング指示、HTML改行、またはデバイス固有の略語。
• 下の段落に属する2番目の文。

周囲のコピーに依存して意味をなす巧妙なラベルを書かないでください。「話が複雑になってきた」はエッセイのトーンに適しているかもしれませんが、検索結果、目次、スクリーンリーダーの見出しリスト、AI引用に有用なコンテキストを提供しません。正確な見出しの後の説明で個性を保持してください。

使用する投稿タイプ

フロントマターのpostTypes配列がこれらの関係を駆動します。リストされているすべての投稿タイプは同じ階層契約を使用しますが、それぞれの構成要素が正確なセクション名と順序を決定します。

QAチェックリスト

• ページが表示可能なH1を正確に1つレンダリングし、それがページの実際の主題に名前を付けている。
• アウトラインがH1からH2へ、H3へとレベルをスキップせずに進む。
• すべてのH3に明確な直前のH2の親が1つある。
• すべての見出しの後に、次の見出しの前に意味のある所有コンテンツがある。
• すべてのH2に、最初のH3の前に方向付けまたは回答の文が含まれている。
• 見出しテキストが目次やスクリーンリーダーの見出しリストで単独で読んだときに説明的である。
• 並列セクションが並列な文法と同等のレベルを使用している。
• 見出しレベルがフォントサイズや希望する視覚的な重みではなく関係性を反映している。
• 型付き目的はまだ必要な要素を使用しており、見出しがコンポーネントを模倣していない。
• 公開されたすべての見出しに1つの一意で読みやすい安定したフラグメントIDがある。
• 表示される文言がセクションの意味を変えずに編集された場合、既存のフラグメントIDは変更されない。
• 直接フラグメントナビゲーションにより、宛先がスティッキーヘッダーの下に表示されたままになる。
• 見出しテキストにリンク、引用、絵文字ラベル、プロモーションバッジ、手動改行が含まれていない。
• HTMLアウトラインがメニュー、カード、アコーディオン、モーダル、その他のページコンポーネントと共に一貫性を保っている。
• レンダリングされたページが狭い幅で機能し、2行の見出しがクリッピングやオーバーラップなく折り返される。

ビジュアルデザインが洗練されていてもアウトラインが失敗する場合は、ページを拒否してください。見出しの欠陥は累積します。1つのスキップされたレベルや空のセクションがあるだけで、下流のすべてのコンシューマが、ソースが直接述べるべきだった関係を再構築するためにより多くの労力を費やすことになります。

FAQ

以下の質問は、エディターやプラットフォーム間で一貫性のないアウトラインを作成する可能性が最も高いケースを解決します。その信頼できる値は上記の構造化された[[faq]]フロントマターにあり、表示される出力と該当するスキーマ出力が1つのソースを共有できるようになっています。