リンクのメンテナンス

リンクはドキュメントの重要な一部ですが、メンテナンスコストもあります。

リンクのメンテナンスを楽にするために、いくつかの戦略を使っています。

リンクの種類

ドキュメントでは、リンクの 3 種類を使います。外部、内部、アンカーです。種類ごとに、体験のいくつかの側面を考えます。

外部:
- 正本: 別のサイト。
- 壊れる理由: 別のサイトがコンテンツを変更した。
- リンク切れ時の顧客体験: 別サイトの 404 ページ。
内部:
- 正本: 自サイト。
- 壊れる理由: 自サイトがコンテンツを変更した。
- リンク切れ時の顧客体験: 自サイトの 404 ページ。
アンカー:
- 正本: 自サイト。
- 壊れる理由: 自サイトがコンテンツを変更した。
- リンク切れ時の顧客体験: 自サイトでのページ読み込み。コンテンツがページのさらに下にある、または別ページへ移っていることがあります。

この 3 つのリンクの種類のうち、内部リンクだけが次に当てはまります。

このため、壊れた内部リンクがあるとビルドを失敗させます。実装では Nimbus ↗ の nimbus/internal-link lint ルール ↗ を使い、astro.config.ts ↗ で設定しています。

このリンク監査では、意図して次の 2 点も決めています。

相対リンクではなく絶対リンク: 絶対リンク（/style-guide/how-we-docs/metadata/）を必須にし、相対リンク（../metadata/）では失敗させます。将来の手間のかかるメンテナンスを避けるためです。この方針は、検索と置換や、将来のプラットフォーム移行にも役立ちます。
リダイレクトを考慮しない: リンク評価時にリダイレクトは考慮しません。いまの正本があるので、それを最大限使います（リダイレクトチェーンと将来のメンテナンスも避けられます）。

外部リンクは顧客体験として好ましくありませんが、自サイトのコンテンツ変更の文脈では変わりません。さらに、外部リンクチェックは時間がかかり、誤りも起きやすく、コントリビューションを遅くします。

壊れた外部リンクの検出は外部の SEO ツールに任せ、必要に応じて対応します（これらを理由にビルドを失敗させません）。

アンカーリンクが誤っていても、内部リンクほど深刻ではありません。アンカーリンクが壊れていると、顧客は見出しまで手動でスクロールするか、場合によっては別のページへ移動する必要があります。

こうした特性のため、壊れたアンカーリンクの検出は htmltest ライブラリを使った定期的なバックグラウンドチェック ↗ で行います。