目次：フォーマットとルール

要素ライブラリ において、クイック概要と目次は、読者にページの内容、判断の助けとなること、そして必要なセクションにジャンプする方法を知らせます。

クイック概要。 長いまたは構造的に複雑なページでは、このペアになった冒頭要素を使用します。40〜90語の概要を作成し、範囲と期待される成果を設定した後、安定したH2見出しと有用なH3見出しのみから作成された目次リストを提供します。このサイトでは、以下のライブ目次コントロールは、読者が300ピクセル以上スクロールするまで非表示のままであり、その後サイトヘッダーの下に固定されたデスクトップドロップダウンとして表示されます。

この要素が重要な理由

読者はすべての長いページを同じ地点から読み始めるわけではありません。ある人は定義を必要とし、別の人は実装手順を求め、さらに別の人は承認作業の前に単一の制約を確認しています。短い概要は、読者が注意を注ぐ前に「自分は正しい場所にいるのか？」という問いに答えます。目次リストは「必要な部分はどこにあるのか？」という問いに答え、直線的な読み取りを強制しません。

この2つの部分は、隣接しながらも異なる方向性の問題を解決するため、一緒に指定されています。概要は、ページの約束、境界、および有用な成果を文章で説明します。目次リストは、その約束を通るルートを目的地として公開します。概要なしの目次リストは、「設定」や「アクセシビリティ」というセクションがあることを示せても、そのページが概念的な紹介なのか、実稼働仕様なのかを説明できません。ナビゲーションなしの概要は、範囲を確立できても、読者に3,000語を探し回らせる可能性があります。

この要素は機械による抽出可能性も向上させます。つまり、ソフトウェアが一節を切り出し、その目的を全ページの外部でも保持できる能力のことです。概要は、タイトルと説明に次ぐ、2つ目の簡潔で自己完結した要約です。Hugoのソース目次は、ページのカバレッジと階層のリンク付き機械可読アウトラインです。現在の固定レンダラーは、これらのリンクを、URLの#section部分であるフラグメント値を保持するオプションに変換します。検索システム、検索ツール、ブラウザ拡張機能、AIエージェントは、すべての段落を処理する前に関連回答領域を特定するために、ドキュメントアウトラインを使用できます。これは、検索機能やAI引用を保証するものではありませんが、主題がどこから始まり、どのように関連しているかについての曖昧さを減らします。

このペアリングは重複を生み出してはいけません。概要は範囲と成果を述べます。直接回答ブロック は主要な質問に答え、重要ポイント は記憶に値する結論を示します。3つすべてが異なるボックスで同じことを言う場合、冒頭は助けではなく障害になります。

いつ使用するか

目次リストは、ジャンプが読者の行動として想定される場合にその価値を発揮します。語数は有用な指標ですが、構造が決定要因です。

タイトルが広く解釈される可能性がある場合、ページが意図的に隣接する主題を除外している場合、または読者が進む前に期待される成果を知る必要がある場合は、概要のみを使用します。900語のポリシーページは、ナビゲーションを必要としなくても、2文の概要を必要とする場合があります。

タイトルと冒頭がすでに範囲を明白にしている場合にのみ、目次リストのみを使用します。このニアミスはリファレンスページでよく見られます。冒頭に方向性の役割を果たす直接的な定義が含まれている一方で、長い独立したフィールドのセットは依然としてナビゲーションを必要とする場合です。

どちらの部分も装飾として使用しないでください。700語の記事に6項目のTOCを追加すると、回答の前に余分な判断を強います。「このガイドは知っておくべきすべてを探求します」という概要は、範囲、成果、除外事項を定義していません。弱い見出し構造を隠すためにペアを使用しないでください。見出しが重複している、文法が一貫していない、または1つのアイデアを多数の小さなセクションに分割している場合は、アウトラインを公開する前にドキュメントを修正してください。

配置場所

位置は要素の意味の一部です。概要は、ヒーローまたは冒頭の直接回答の後、最初のH2の前に配置する必要があります。短い段落またはコンパクトなリストにすることができますが、読者が本文に取り組む前に目にする必要があります。TOCの呼び出しは、概要の直後に配置し、作成元で方向性とナビゲーションを一緒に保つようにします。このサイトの固定コントロールは300ピクセルスクロール後にのみ表示されますが、これにより作成元では方向性とナビゲーションを一緒に保てます。

このペアは、定義を中断したり、主張とその証拠を分離したり、ドキュメントの途中で初めて表示されたりしてはいけません。見出しとその見出しの冒頭段落の間に配置しないでください。見出しと説明の関係は直接的であるべきです。別の概要スタイルのコンポーネントをその隣に配置しないでください。直接回答や重要ポイントブロックが必要な場合は、異なる役割を割り当て、次の順序を使用します：直接回答、簡潔な範囲概要、TOC呼び出し、最初の本文セクション。文言がまだ重複する場合は、いずれかの要約を省略します。

ショートコードはページごとに1回使用します。そのレンダリングされるID（tocDropdown、tocSelect、selectTrigger、および関連コントロール）は固定されているため、2つ目のインスタンスは重複したドキュメントIDと予測不能なスクリプトを生成します。

構成

この要素には6つの意味のある領域があります。最初の5つはコンテンツまたは動作であり、進捗インジケーターはステータスです。スクリーンショットのサイズ変更や置換が行われた場合でも読み取り可能なように、凡例はページ内に保持されます。

1. 概要本文： 範囲、意図された成果、および重要な境界を述べる40〜90語。
2. 固定ラッパータイトル： デフォルトではページタイトル。より短いラベルの方が明確な場合は、作成されたtitle属性。
3. 現在のセクションラベル： 「セクションを選択…」で始まり、ブラウザのIntersectionObserver（定義されたビューポート領域に入る要素を検出するAPI）がセクションをアクティブとしてマークすると変化します。
4. ドロップダウントリガー： 現在の実装では、クリック時に生成されたセクション移動先のリストを開きます。
5. 見出しオプション： Hugoのページ目次から派生したリンク。markup.tomlの設定により、現在はH2とH3。
6. 進捗バー： スクロール可能なドキュメント全体のうち移動した割合を示します。セクションの完了を識別するものではありません。

デザイン例

ギャラリーは装飾的なテーマではなく、動作状態をカバーしています。基礎となるコンテンツは同じままなので、レビュー担当者はタイミング、階層、クリッピング、インタラクションを比較できます。

Markdownを通じて作成される代替ビジュアルバリアントはありません。titleはラベルを変更し、classはラッパークラスを追加しますが、意味的に異なる要素を作成するものではありません。新しいカラー、カード、サイドバー、またはインラインリストの処理には、コンテンツに任意のクラスを追加するのではなく、コンポーネントの決定が必要です。

パラメータ

概要とTOCは1つの編集契約を共有しますが、現在のショートコードでレンダリングされるのは固定TOCのみです。作成者は呼び出しごとに設定できなくても、出力が変わるため設定値が含まれています。

見逃しやすい依存関係があります。H2見出しのないページは、Hugoが使用可能なアウトラインを生成せず、部分テンプレートがヘッダーがある場合のみマークアップを出力するため、静かに固定TOCをレンダリングしません。現在の設定では、H2とそのH3子孫が該当し、H4以上の見出しは除外されます。部分テンプレートは通常、Hugoの.TableOfContentsを解析します。そのHTMLフォールバックはレンダリングされたH2要素のみをスキャンするため、作成者はH3ナビゲーションを維持するためにフォールバック動作に依存してはいけません。

構文とコード例

ポータブルな記法では、概要を要素本文として、ナビゲーション設定を属性として保持します。見出しリンクは、作成者が複製するのではなく、周囲のドキュメントから生成されたままです。

:::quick-overview-and-toc{title="このページについて" class=""}
このガイドでは、要素を使用するタイミング、固定Hugoコントロールの動作、公開後にアクセシブルで安定したセクション移動先を維持する方法について説明します。
:::

現在のHugoマッピングは、概要を通常のMarkdownとして書き、出荷されたショートコードを1回呼び出します。JSON本文はありません。

このガイドでは、要素を使用するタイミング、固定Hugoコントロールの動作、公開後にアクセシブルで安定したセクション移動先を維持する方法について説明します。

{{< table-of-contents title="このページについて" class="" >}}

WordPressブロックマッピングは、同じ本文と属性を保存します。ブロックを登録していないサイトは、同等のショートコード形式を使用できます。見出しリンクを手動で作成してはいけません。

<!-- wp:amicited/quick-overview-and-toc {"title":"このページについて","className":""} -->
<p>このガイドでは、要素を使用するタイミング、固定コントロールの動作、公開後にアクセシブルで安定したセクション移動先を維持する方法について説明します。</p>
<!-- /wp:amicited/quick-overview-and-toc -->

[amicited_quick_overview_toc title="このページについて" class=""]
このガイドでは、要素の範囲、動作、アンカーポリシーについて説明します。
[/amicited_quick_overview_toc]

3つのシステムすべてにおいて、真実のソースはドキュメントの実際の見出し階層です。手動で維持されたリストは、見出しが変更されるにつれてズレが生じ、存在しなくなったIDを指す可能性があります。

例

良い例

クイック概要。 このガイドは、コンテンツチームが比較ページを計画、執筆、レビュー、および維持する方法を示します。証拠基準、比較基準、製品クレーム、アクセシブルな表、公開後のチェックをカバーします。有料掲載やアフィリエイトコミッション条件はカバーしません。

このページについて： 判断の定義 · 比較基準の選択 · 証拠の収集 · ページのドラフト作成 · クレームのレビュー · 測定と維持

これが機能する理由は、概要が48語で読者、成果、カバレッジ、境界を明確にしているからです。6つの移動先は、読者が個別に再訪問する可能性のある明確なタスクです。それらのラベルは並列的な動詞フレーズを使用しているため、人間と機械の両方がプロセスを推測できます。どのエントリもページタイトルを繰り返したり、些細なサブセクションを公開したりしていません。

悪い例

概要： 私たちの完全ガイドへようこそ。今日の変化する世界では、知っておくべきことがたくさんあります。すべてを学ぶために読み進めてください。

目次： はじめに · 詳細情報 · 重要なこと · その他のこと · 結論

これは2つの理由で失敗しています。概要は22語を使って範囲、読者、成果、除外事項を定義していません。エントリは主題ではなく修辞的なコンテナにラベルを付けているため、読者が答えがどこにあるかを予測するのに役立ちません。見出しを増やしても修正にはなりません。ドキュメントにはまず意味のあるセクション境界が必要です。

2つ目のニアミスは、目次に「概要」「背景」「詳細」「ヒント」「結論」がある600語の回答です。すべてのアンカーが機能しても、リストはナビゲーション価値よりもインターフェースを増やしています。直接的な冒頭を維持し、TOCを削除してください。

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

ここで、スキーママークアップ とは、エンティティとプロパティを識別する標準化された機械可読コードを意味します。この要素には、Schema.orgボキャブラリに専用のタイプやプロパティはなく、HugoショートコードはJSON-LD（そのボキャブラリを公開するために一般的に使用されるスクリプトベースの記法）を出力しません。リストであるという理由だけでTOCをItemListとしてマークしないでください。それはナビゲーションではなく、主題項目のリストを示唆することになります。概要は、文言が独立して適切な場合にのみ、ページのdescriptionに情報を提供することがありますが、自動的に構造化データにコピーされるわけではありません。

ここではHTMLとARIAの動作がより重要です。ARIA（Accessible Rich Internet Applications標準）は、ネイティブHTMLでは不十分な場合に、ロール、名前、状態を提供します。ランドマークとは、支援技術ユーザーがジャンプできる名前付きページ領域です。フォーカスは現在のキーボードインタラクションターゲットです。

これらは実装上の事実であり、アクセシビリティを無視する許可ではありません。コンテンツレビュー担当者は、今日の時点で見出しの明確さ、一意のID、論理的な順序を確認できます。コンポーネント所有者は、固定バリアントをキーボードアクセシブルとして説明する前に、トリガー、ランドマーク、フォーカス、URL、および減少モーションの動作を解決する必要があります。

作成ルール

概要は、ページ構造が安定した後に作成してください。これにより、初期の約束が完成したカバレッジから乖離するのを防ぎます。40〜90語に抑えます。2〜3文が望ましく、ページに複数の真に並列な成果が含まれる場合にのみ3〜5の箇条書きを使用します。ページが読者の理解、判断、または行動に役立つ内容を記述します。タイトルがページの提供内容以上を合理的に約束する可能性がある場合は、除外事項を明記します。

H2はページの主要な質問、段階、または判断領域に使用します。H3は、重要なH2の下で有用な独立した目的地となる場合にのみ、ナビゲーションに含めます。このサイトでは、設定がすべてのH2とH3を自動的に含めるため、実践的なポリシーはより厳格です：ナビゲーションに表示される価値がない見出しは作成しないでください。合計5〜18エントリを目指します。生成されたリストが18を超える場合は、重複するセクションを結合するか、不要なH3見出しを削除するか、ページを分割します。TOCから見出しを隠すために、H2から直接H4にスキップしないでください。見出しレベルは階層を表現するものであり、スタイリングやナビゲーションの好みではありません。

簡潔で説明的な見出しテキストを使用します。読者は親段落を読まなくても各目的地を理解できる必要があります。シーケンス内では並列形式を優先します：「基準を選択」「証拠を収集」「クレームをレビュー」は、名詞、疑問文、曖昧なラベルの混合よりもスキャンしやすいです。TOCに影響を与えるためだけに、引用、宣伝文句、絵文字、ステータスバッジ、完全な文を見出しに配置しないでください。

概要には、2つ目のミニチュア目次リスト、根拠のないパフォーマンスの主張、または本文のどこにも表示されない指示を含めてはいけません。TOCには、手動で入力されたアンカー、現在のページ外の移動先、または空のセクションへのリンクを含めてはいけません。

アンカー安定性ポリシー

見出しIDは、#anchor-stability-policyなどのURLのフラグメント部分です。公開されたフラグメントURLは公開インターフェースです。ブックマーク、キャンペーンリンク、サポートドキュメント、検索結果、AI生成回答が直接それらを指す可能性があります。見出しテキストを変更すると、Hugoの生成IDが変わり、ページURLが同じでもすべてのインバウンドアンカーが壊れる可能性があります。

公開後は、すべてのH2およびH3見出しのIDを固定してください。見出しの名前を変更するよりも、見出しの下の段落を編集することを優先します。名前変更が必要な場合は、公開システムがサポートする明示的アンカーメカニズムを使用して古いIDを保持し、古いインバウンドフラグメントと新しいTOC選択の両方を確認します。古いIDを異なる主題に再利用したり、ページ上でIDを重複させたり、移行計画なしに既存のローカライズURLのIDを翻訳したりしないでください。意図的なアンカー変更はリリースノートまたはコンテンツ変更ログに記録し、既知のインバウンドリンクの所有者が更新できるようにします。

使用する投稿タイプ

postTypesフロントマターは、この要素が制作パターンの一部であるフォーマットをリストします。それでも条件付きです：通常は長いフォーマットの短いインスタンスがTOCしきい値を下回る場合があります。

製品、カテゴリ、ユースケースページは、主要なユーザージャーニーがページレベルのナビゲーションとコールトゥアクションで処理されることが多いため、デフォルトでは含まれません。この要素は、ページがたまたま長いからではなく、文書化されたテンプレートの決定を通じてのみ追加してください。

QAチェックリスト

• ページがしきい値を満たしていることを確認：少なくとも1,800語、7つのH2セクション、または文書化された非線形ナビゲーションの必要性。
• 概要が40〜90語で、範囲、意図された成果、および必要な除外事項を述べていることを確認。
• 概要が直接回答や重要ポイントを繰り返していないことを確認。
• ショートコードが1回、概要の直後、最初のH2の前に表示されることを確認。
• すべてのH2が意味のある主要な目的地であり、すべてのH3がナビゲーションに表示する価値があることを確認。
• 生成されたリストに5〜18エントリが含まれ、論理的な順序であり、現在の設定でH4項目が含まれていないことを確認。
• config/_default/markup.tomlが引き続きstartLevel = 2、endLevel = 3、ordered = falseを使用しているか、またはコンポーネントの変更に合わせてこの仕様を更新。
• 該当するH2がないページがTOCを含むと主張していないことを確認。ショートコードは静かに何もレンダリングしません。
• すべての生成されたフラグメントが一意で、意図された見出しに到達することを確認。
• H2またはH3の文言を変更する前に、公開されたインバウンドアンカーURLをテスト。見出しを変更する必要がある場合は古いIDを保持。
• デスクトップで、固定ラッパーが300ピクセル以下で非表示になり、スクロール位置が300ピクセルを超えると表示されることを確認。
• 固定ラッパーが実際のヘッダーの下に配置され、進捗バーが進み、アクティブラベルがセクション変更に追従することを確認。
• 狭いビューポートで現在のコントロールが表示されないことを確認し、これを壊れたスクリーンショットではなく、期待される現在の動作として記録。
• 現在のアクセシビリティの制限事項を記録：ナビゲーションランドマークなし、キーボードフォーカス可能な表示トリガーなし、フォーカス転送なし、フラグメント更新なし、減少モーションブランチなし。
• 対応するアセットがディスク上に存在するまで、スクリーンショットパスがレンダリングされないことを確認。

FAQ

以下の質問は、この要素が早すぎる段階で追加されたり、深すぎる階層で作られたり、公開後に壊れたりする原因となる最も一般的な編集上の判断をカバーしています。