メインコンテンツまでスキップ

内部リンクの貼り方ガイドライン

新規記事を書くとき・既存記事を更新するときに、内部リンクをどう張るかの基準をまとめたガイドラインです。SEO クローラビリティを底上げしつつ、読者が関連トピックを発見しやすいサイトに育てるための運用ルールとして使ってください。

Why — なぜ内部リンクが大事か​

内部リンク (同じサイト内の記事から記事へのリンク) は、3 つの観点で価値があります。

1. 検索エンジンのクローラビリティ​

Google のクローラは内部リンクを辿ってサイトを発見します。記事間にリンクがなく sidebar だけで連結されていると、深い階層の記事ほどクロール頻度が落ちる傾向があります。本文中のリンクがあれば「重要な記事 = 他から多く参照されている記事」と認識されやすくなります。

2. アンカーテキストの多様化​

Docusaurus 標準の「前 / 次の記事」ナビゲーション (Paginator) は「Previous」「Next」のような 機械的なアンカーテキスト です。本文中のリンクなら「命名規則を確認するときは」のように、自然な日本語コンテキストでアンカーテキストを多様化 できます。これは検索エンジンにとって品質シグナルになります。

3. 読者の発見性​

「この記事を読んだ人はこの記事も気に入るかも」を本文に明示することで、滞在時間 + セッション内ページビュー が伸びます。これは検索エンジンの「ユーザー満足度」シグナルにも、読者の学習体験にもプラスです。

What — 用語の定義​

用語意味このサイトでの例
ハブ記事1 つのテーマの 入り口、複数のスポーク記事に向けて分岐するインデックスdocs/intro、docs/clean-code
スポーク記事ハブから派生する 個別トピック、深掘り記事docs/clean-code/naming、docs/clean-code/functions
相互リンクBlog ↔ Docs などの 双方向参照、文脈の補完Blog の実例記事 ↔ Docs の規範記事

ハブ&スポーク構造のメンタルモデルで、サイト全体は 「ハブから派生するスポーク群」+「Blog ↔ Docs の相互リンク」 で繋がるイメージです。

How — 推奨 3 パターン​

パターン 1: 本文中の文脈リンク (最優先)​

本文を読んでいる流れの中で「ここで関連トピックを参照させたい」という箇所に、自然な日本語をアンカーテキスト化 してリンクを貼ります。

TypeScript の[命名規則](../clean-code/naming.md)を踏まえると、この変数は `userCount` のように意味のある名前を付けるべきです。

優先度が一番高いのは、これが アンカーテキスト多様化 + 自然な読者導線 の両方を満たすからです。

パターン 2: 末尾の「次に読む」セクション​

章の最後に 明示的な誘導ブロック を置きます。ハブ記事や、シリーズものの最終回で特に有効です。

## 次に読む

- [はじめに](../intro.md) — クリーンコード入門の全体像に戻る
- [命名規則](./naming.md) — 個別トピックの最初の章

末尾の手動誘導は、関連記事 plugin (タグ一致度ベースの自動算出、記事末尾に最大 4 件表示) を補完するものです。手動で「ここを読んでほしい」を明示 できる点が違い。

パターン 3: mermaid 図でのリンク埋め込み​

mermaid のノードに click で外部リンクを張ると、図がそのまま ビジュアル目次 として機能します。

シリーズ全体を俯瞰させたいときに使います。

Example — Bad と Good の比較​

Bad: 内部リンクなしの章​

---
title: 関数設計
---

関数は単一責任にしましょう。早期リターンでネストを浅く保ちます。

(本文中に他章へのリンク 0 件、末尾も Paginator 任せ)

→ 読者は sidebar を自分で辿る 必要がある。Google から見ても クロール経路が薄い。

Good: 本文文脈リンク + 末尾誘導​

---
title: 関数設計
---

関数は単一責任にしましょう。[命名規則](./naming.md) と組み合わせると意図がさらに明確になります。
[早期リターン](./conditionals.md#早期リターン) でネストを浅く保ちます。

## 次に読む

- [繰り返し処理](./loops.md) — 関数の中でループをどう書くか
- [TypeScript Tips](./typescript-tips.md) — 関数シグネチャの型設計

→ 本文文脈で 2 リンク + 末尾誘導 2 リンクで、読者が次に読むべき記事へ自然に流れる。

Summary — 新規記事を書くときのチェックリスト​

新規記事を書く・既存記事を更新するときに、以下のチェックリストでセルフレビューしてください。

  • 本文中に最低 1 件の内部リンク が含まれているか (パターン 1)
  • ハブ記事に新しいスポーク を追加した場合、ハブ側にも逆方向リンクを追加したか
  • Blog ↔ Docs の相互参照 が必要な場面 (Blog で Docs の規範を引用、Docs で Blog の実例を紹介) を見落としていないか
  • アンカーテキストが「ここをクリック」「詳細」のような 無意味な表現 になっていないか (自然な日本語にする)
  • 末尾に「次に読む」セクションが必要な記事 (シリーズ物 / ハブ記事 / 最終回) で省略していないか

最後に VERIFY_LINKS=1 yarn build を実行してください。broken link があれば build が exit 非 0 で失敗します (通常 build は onBrokenLinks: 'warn' のため警告を見逃しやすく、検証には throw 化した本コマンドを使います)。textlint / typecheck も含めて一括検証するなら yarn verify が使えます。

関連記事 plugin との使い分け

本サイトには関連記事 plugin (記事末尾に自動で関連 4 件を表示) があり、これは タグ一致度ベースの自動算出 です。本ガイドラインの内部リンクは 手動 + 文脈に応じた自然な日本語アンカー で、自動算出を補完します。両者は併用が前提です。