用語集リンクとツールチップ：ライティングルール

用語集リンクとは、用語が最初に意味を持つ形で登場した箇所を、その完全な定義を所有する1つのページに結び付けるリンクです。このリンクにより、読者は記事を中断することなく馴染みのない用語を理解でき、クローラーには用語とその正規エンティティページとの一貫した関係が示されます。

canonical URL（正規URL） とは、複数のURLに同一または実質的に類似したコンテンツが含まれる場合の、優先バージョンのページです。

この文が実際の要素です。アンカーは正確な用語であり、リンク先はその正規の用語集エントリであり、周囲の文はリンクを開かなくても理解できます。対応するシステムでは、同じリンクがホバー時やキーボードフォーカス時に短い定義のツールチップを表示する場合があります。ツールチップではなく、リンク先のページが信頼できる情報源です。

この要素が重要な理由

読者は同じ語彙を持って訪れるわけではありません。専門家は「canonical URL」をすぐに理解するかもしれませんが、バイヤーや新しいチームメンバーは定義を必要とする場合があります。すべての用語を括弧書きで説明すると、専門家向けの文章が読みづらくなります。何も説明しないと、初心者は置き去りにされます。用語集リンクは静かな逃げ口を作ります。用語に馴染みがあればそのまま読み進め、馴染みがなければ定義を開くことができます。

初出ルールが重要なのは、不確かさが積み重なるからです。読者が第2パラグラフで用語を誤解すると、その用語に基づく後の主張はすべて評価が難しくなります。最初の意味のある出現箇所をリンクすることで、不確かさが広がる前に解消します。このルールは「最初に文字列一致した箇所をリンクする」という意味ではありません。タイトル、ナビゲーションラベル、コードサンプル、ティーザー内の用語は、説明で使用される意味をまだ持っていない可能性があります。

機械抽出可能性とは、プレゼンテーションが除去された後もソフトウェアが関係性を保持できる能力です。説明的なアンカーと安定したリンク先によって明示的なエッジが作成されます。つまり、このページはその概念を使用しており、あの用語集ページがそれを定義しているということです。一貫したエッジは、どのURLが定義を所有しているかを強化します。形式的なナレッジグラフを作成したり、可視性を保証したりするわけではありませんが、クローラーが近接性のみから解決する曖昧さを軽減します。

過剰なリンクはこれらの利点を逆転させます。繰り返される用語すべてにリンクすると、ページは優先順位を示せなくなります。読者は競合する出口のフィールドに直面し、支援技術ユーザーは同じリンク先を繰り返し聞くことになり、機械は意図的な関係の小さなセットではなく、多くの冗長なエッジを受け取ることになります。したがって、最初の意味のある言及における1つの正規リンクがデフォルトであり、すべてのセクションで繰り返す最低限ではありません。

使用すべきタイミング

以下の3つの条件がすべて満たされる場合にこの要素を使用します。

1. その用語に、複数の類似した定義ではなく、正規の用語集ページが存在する。
2. その用語を理解することが、読者が現在のページを理解するのに実質的に役立つ。
3. 最初の意味のある使用箇所で、文を歪めることなく説明的なアンカーを設定できる。

有力な候補としては、専門用語、最初の展開時に使用される頭字語、命名された標準、メトリクス、日常的な使用と分野内での意味が異なる単語などがあります。ツールチップは1つの短い定義をプレビューできます。完全な用語集ページは、境界、例、ソース、関連用語を扱います。

ニアミスケースは、この要素が最も誤用されやすい箇所です。

• 通常の語彙： 用語集エントリが存在するという理由だけで馴染みのある単語をリンクしないでください。
• 付随的な言及： 記事が概念に言及しているが、それに依存していない場合、リンクは不要な出口を作ります。
• 繰り返しの言及： 最初のリンク以降は、長く複数パートからなるページで真に独立した読書コンテキストが作成されない限り、用語はテキストのままにします。
• 曖昧なアンカーテキスト： 「このアプローチ」「詳細はこちら」「その指標」は用語集エンティティを識別しません。用語自体をリンクします。
• 正規のリンク先がない： 検索結果、タグアーカイブ、関連性の低い記事で代用しないでください。正規の定義が存在するまで、プレーンな散文を使用します。
• 定義がすでに完全に提供されている： 用語集が有用な深みを追加しない場合、2つ目の定義の寄り道は不要かもしれません。
• 商業的な誘導： 用語集リンクは製品の行動喚起を偽装したものではありません。製品ページ、サインアップフロー、価格ページは異なる読者の意図に応えます。

即興で作成する前に、共有の要素ライティングルール を適用してください。その優先順位ルールでは、作成者は目的に応じて要素を選択する必要があります。目的が名前付き用語をその正規定義に接続することであれば、同様に見えるようにスタイル設定された汎用インラインリンクではなく、この型付き関係を使用します。

配置場所

最初の意味のある散文での言及にリンクを配置します。つまり、リンク先の意味での概念を使用する最初の文です。用語がタイトルやH2に最初に登場する場合は、次のパラグラフでの最初の使用箇所をリンクします。見出しは、大きなナビゲーションターゲットではなく、安定したセクションラベルであるべきです。

頭字語の場合は、完全な用語の後に略語を記述し、完全な用語をリンクします：retrieval-augmented generation（RAG）。以降の出現では、リンクなしでRAGを使用できます。

用語集リンクを配置してはいけない場所：

• 別のリンク、ボタン、またはクリック可能なカードの中
• 同じアンカーテキストに2つ目のリンクを隣接して配置
• コード、URL、メールアドレス、またはユーザーが入力したリテラルテキスト内
• 初出ルールを満たすためだけに見出し内に配置
• 導入部で1つのリンク付き定義が用語を確立できるのに、テーブルのすべての行に配置
• 2つのターゲットが視覚的または操作的に区別できなくなる場合の、引用マーカーのすぐ隣
• 実際のリンクとは別のツールチップトリガー内

1つの文に複数の馴染みのない用語が含まれる場合は、その文を理解するために必要な用語のみをリンクします。1つの文に3つ以上の用語集リンクがある場合は、散文が想定する語彙が多すぎるという警告です。文を書き直すか、1つの概念をその場で定義するか、より多くの出口を追加する前に説明を分割します。

構成

ラベル付き標本には6つの領域があります：

1. 用語アンカー： 「詳細はこちら」ではなく、表示される用語または完全な展開名。
2. 正規リンク先： 定義を所有する1つの安定した用語集URL。
3. コンテキスト文： リンクが開かれなくても、用語が出現する理由を理解するのに十分な散文。
4. リンクスタイリング： サイトの標準的なインラインリンク処理。色だけが手がかりではありません。
5. フォーカスインジケーター： パラグラフやツールチップでクリップされない、可視のキーボード状態。
6. オプションのツールチップ： リンク自体に結び付けられた短いプレビュー。アイコンのみの別個のコントロールではありません。

アンカー、リンク先、初出動作を変更しない限り、表示は変更される可能性があります。

デザイン例

すべてのバリエーションは同じ意味のリンクを保持します。

デフォルトのインラインリンク： 必須のベースライン。JavaScriptが無効な状態、リーダーモード、印刷注釈、ホバーのないデバイスでも機能します。

フォーカス時またはホバー時の定義ツールチップ： 密度の高い教育コンテンツのための拡張機能。プレビューは1〜2文で、リンク、ボタン、引用、書式設定コントロールは含みません。

モバイルとタッチ： プロダクトに確立されたアクセシブルな開示パターンがない限り、最初のタップはリンクを辿ります。1回のタップでプレビューが開き、2回目のタップで移動するという操作を、そのインタラクションがサイト全体で一貫して明確に伝えられていない限り、ユーザーに発見させるべきではありません。

ダーク背景： リンク、フォーカスリング、ツールチップテキスト、ツールチップ境界は明確なコントラストを保持します。アクセントカラーが明るいという理由だけで下線を削除しないでください。

パラメーター

正規URLと可視アンカーはコンテンツの決定事項です。ツールチップの動作はレンダラーに属します。これらのソースを分離することで、オプションのインターフェース機能がリンクの意味を変更することを防ぎます。

hrefをtermから推測しないでください。同音異義語は同じ綴りでも異なるリンク先を必要とする場合があります。ツールチップは、その短い定義がページ外での使用のためにレビューされている場合にのみ、用語集レコードから取得します。

構文とコード例

3つの形式すべてが通常のリンクをコアとして保持します。名前付きフィールドはポータブルな契約です。プラットフォームは、ネイティブブロック、プラグイン、またはプリプロセッシングステップでレンダリングできます。

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

The :::glossary-link{href="/glossary/canonical-url/" definition="A canonical URL is the preferred version of a page when duplicate or similar URLs exist." tooltip="true"}canonical URL::: consolidates signals on the preferred page.

公開パイプラインがインラインディレクティブをサポートしていない場合は、通常のMarkdownを使用し、ツールチップを省略します：

The [canonical URL](/glossary/canonical-url/) consolidates signals on the preferred page.

Hugoショートコード

The {{< glossary-term-link href="/glossary/canonical-url/" definition="A canonical URL is the preferred version of a page when duplicate or similar URLs exist." tooltip="true" >}}canonical URL{{< /glossary-term-link >}} consolidates signals on the preferred page.

この表記は必要なマッピングを指定するものであり、作成者がMarkdownレンダリングやコンテンツプリプロセッシングを通じて既に用語集リンクを処理しているプロジェクトに新しいショートコードを導入することを要求するものではありません。レンダリングされたフォールバックは常に通常の<a href>要素でなければなりません。

WordPress

<!-- wp:amicited/glossary-link {"href":"/glossary/canonical-url/","definition":"A canonical URL is the preferred version of a page when duplicate or similar URLs exist.","tooltip":true} -->
<a href="/glossary/canonical-url/">canonical URL</a>
<!-- /wp:amicited/glossary-link -->

エクスポートされたコンテンツは、ツールチップメタデータが利用できない場合でも、アンカーとhrefを保持する必要があります。

例

良い例

実質的に類似したページには1つのcanonical URL（正規URL） を選択し、インデックスシグナルが優先バージョンを指すようにします。

レンダリングされた記事では、「canonical URL」が最初の意味のある使用箇所で/glossary/canonical-url/にリンクされています。アンカーはエンティティを正確に名指しし、文は読み続けるのに十分なローカルコンテキストを提供し、以降の出現はプレーンテキストのままです。読者は完全な定義が必要かどうかを選択できます。

悪い例

類似したページには1つの優先ページ を選択します。その後、すべてのセクションでcanonical URLをcanonical URLに参照させる必要があります。

これは2つの点で失敗しています。「優先ページ」は関連する表現ですが、リンク先が定義する正確な用語ではないため、関係性の明示性が低くなります。すべてのセクションでcanonical URLリンクを繰り返すと、意味を追加することなく出口が増えます。正しい修正は、「canonical URL」を最初の意味のある使用箇所で1回リンクし、以降の使用はリンクしないことです。

もう1つの悪いパターンは、リンクされていない用語の後の情報アイコンです。アイコンはリンクテキストをスキャンしている読者からリンク先を隠し、小さなタッチターゲットを作成し、ツールチップをナビゲーション可能な用語集関係から分離する可能性があります。

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

用語集リンクには独立したSchema.orgタイプは必要ありません。これは、それを囲むArticle、TechArticle、またはWebPage内のリンクのままです。すべてのインラインリンクに対してDefinedTerm、mentions、aboutマークアップを生成しないでください。そのような関係は、可視コンテンツによって正当化される一貫したページレベルのデータモデルを通じてのみ追加します。

アクセシビリティは実際のアンカーから始まります。コンテキスト内で理解可能であり、色だけで区別可能ではなく、キーボードで到達可能であり、可視的にフォーカスされている必要があります。重要な情報がツールチップのみに存在してはいけません。

ツールチップが実装されている場合は、表示中にaria-describedbyを使用してアンカーに関連付けます。ポインターホバーと同様にキーボードフォーカスでも開き、ポインターがツールチップ上に移動している間は開いたままにし、Escapeキーでフォーカスを移動せずに閉じることができるようにします。フォーカス可能なコントロールをツールチップ内に配置しないでください。HTMLのtitle属性を定義インターフェースとして依存しないでください。そのタイミング、表示、タッチサポート、支援技術への公開は一貫していません。titleは補足的であっても、アクセシブルな名前、説明、または正規の定義ではありません。

リンクはスクリプトが失敗した場合でも移動できなければなりません。タッチデバイスでは、ホバーの模倣よりも直接ナビゲーションを優先します。拡張機能がこれらの要件を満たせない場合は、プレーンなリンクを提供します。

ライティングルール

正確な用語またはその曖昧さのない完全な形式をリンクします。アンカーは1〜8語、80文字以内に抑えます。「a」や「the」などの冠詞は、固有名詞の一部である場合のみ含めます。すべての用語集アンカーを太字にしないでください。標準のリンクスタイリングが既にインタラクティブ性を伝えており、強調の重ね付けは技術的な散文をうるさくします。

デフォルトでは、用語ごとにページごとに1つの用語集リンクを使用します。2つ目のリンクは、長い付録、独立したFAQ回答、埋め込みモジュールなど、独立して消費されるコンテンツがなければ関係性が失われる場合にのみ許容されます。固定された最小数の用語集リンクを設定しないでください。10個の装飾的な出口があるページよりも、必要な用語が2つで明確なページの方が優れています。

ツールチップの定義は40〜180文字、最大2文とします。用語が何であるかを述べ、なぜクリックすべきかは述べません。中立的で宣言的な言葉を使用します。プレビューはリンク先の現在の定義と一致する必要があり、可能な場合は用語集レコードからソースを取得して、更新が乖離しないようにします。

リンクやツールチップの中に以下のものを絶対に入れないでください：

• 別のリンク、ボタン、フォームコントロール、またはインタラクティブアイコン
• セールスクレームや行動喚起
• 引用リストやソースノート
• 画像、動画、テーブル、コードブロック、または複数ステップの手順
• 正規ページと矛盾したり、正規ページを超えて拡張されたりする定義
• 読者のタスクを完了するために必須の指示

同音異義語は手動でレビューします。「Java」「conversion」「agent」は異なるエンティティを指すことがあります。文とリンク先は同じ意味を解決する必要があります。リンク配布のためにリンク先をローテーションしないでください。正規性がポイントです。

使用する投稿タイプ

postTypes[]フロントマターは、この要素がコンテンツシステムの文書化された一部であるフォーマットを識別します。以下の表は、各フォーマットが同じ初出契約をどのように適用するかを示しています。

QAチェックリスト

• 正規リンク先： パスは定義を所有する1つの用語集ページであり、検索、タグ、製品、関連記事のURLではありません。
• リンク先が存在する： コンテンツファイルが現在存在するか、パスが承認された正規レジストリに同一リリース内で存在します。
• 意味が一致する： アンカーとリンク先は、曖昧な頭字語や同音異義語を含め、同じ意味の用語を参照しています。
• 最初の意味のある言及： リンクは後の使用箇所よりも先に散文内に出現しており、ソース順で先に出現したという理由だけで見出しやコードサンプル内にあるわけではありません。
• 正確なアンカー： リンクされた語句は用語またはその曖昧さのない完全な形式を示しており、「ここをクリック」や曖昧な代替表現はありません。
• ローカル文が機能する： 読者はリンク先を開いたりツールチップをトリガーしたりせずに文を理解できます。
• 用語ごとに1つのデフォルト： 文書化された独立した読書コンテキストが別のリンクを正当化しない限り、繰り返しの出現はリンクされません。
• リンククラスターなし： 文とパラグラフは読みやすく保たれ、過度に馴染みのない用語はリンクで覆うのではなく書き直されます。
• ツールチップの同等性： プレビューは正規の定義と一致し、40〜180文字以内に収まります。
• プログレッシブエンハンスメント： アンカーはスクリプト、ホバー、ツールチップスタイリングが利用できない場合でも機能します。
• キーボード動作： フォーカスが可視であること。ツールチップはフォーカス時に表示され、Escapeで解除でき、フォーカス可能なコントロールを含みません。
• タッチ動作： リンクは通常のターゲットサイズを持ち、ホバーや説明のない2タップ操作を必要としません。
• 構造化データの抑制： サポートされていないスキーマ関係や発明された要素タイプは出力されません。
• ポータブルな出力： Markdown、Hugo、WordPressは、ツールチップメタデータが削除された場合でも、同じ用語と正規のhrefを保持します。
• スクリーンショットステータス： 名前付きアセットが存在するまで、キャプチャコメントはレンダリングしない指示のままです。存在しない画像は参照されません。

FAQ

アカデミーテンプレートは、対象資格、初出、ツールチップ範囲、正規の一貫性、リンク制限をカバーする、レビュー済みのフロントマター質問をレンダリングします。