【ITニュース解説】Duplicate titles and meta descriptions on a docs site

ドキュメントサイトは、システムエンジニアが情報共有や製品説明のために作成するウェブサイトであり、その運用には独自の課題がある。特に頻繁に発生するのが、ページのタイトル（<title>タグ）やメタディスクリプション（<meta name="description">タグ）の重複問題だ。新しいセクションを作成する際に、既存のページをコピーして使い回すことはよくあるため、多くのページが同じ内容のタイトルや説明文を検索エンジンに伝えてしまう。これは、システムの効率化を目指すエンジニアにとって、見過ごせない問題となる。

Googleをはじめとする検索エンジンは、各ページが固有で、内容を正確に説明する簡潔なタイトルと、独自のディスクリプションを持つことを強く推奨している。これは、検索結果を見たユーザーが、数ある選択肢の中から自分にとって最も関連性の高いページを迅速に見つけ出す手助けをするためである。もし多数のページが同じ説明文を共有している場合、Googleはそれらのページを区別しにくく感じ、ページ本文から自動的にスニペット（検索結果に表示される説明文）を生成しようとする。しかし、それでも検索結果に表示されるリンクがどれも似たような見た目になってしまい、ユーザーはどのページをクリックすれば良いか迷ってしまう。結果として、せっかく作成した重要なドキュメントが、必要なユーザーに届きにくくなるという事態を招いてしまうのだ。

このような重複は、ドキュメントサイト構築に利用される主要なフレームワークの特性によって引き起こされることが多い。例えば、Docusaurus（ドクサウルス）では、各ドキュメントの説明文は「フロントマター」と呼ばれる、Markdownファイルの冒頭に記述される設定情報から取得される。もしフロントマターで説明文が指定されていない場合、DocusaurusはMarkdownコンテンツの最初の行を自動的に説明文として使用する。この時、コードブロックやタイトル見出しはスキップされるが、それ以外の内容が対象となるため、同じ見出し（例: ## Overview）や同じ注意書き（例: :::note This feature is in beta.）で始まる複数のページが、結果的に同一の説明文を持つことになってしまう。Docusaurusでバージョン管理されたドキュメントを運用している場合も、各バージョンで同じ内容のページが複数存在するため、タイトルと説明文がそのまま重複する原因となる。タイトルもフロントマターで指定されなければ、Markdownの#見出しやドキュメントID、サイトタイトルが組み合わされるため、異なるセクションに同じ名前のページが存在すると、例えば「Configuration | マイプロジェクト」のように全く同じタイトルが複数生成される可能性がある。

Starlight（スターライト）の場合、タイトルは必須だが説明文は任意設定だ。ページごとに説明文が設定されていないと、サイト全体の設定ファイルに記述された共通の説明文が、すべてのページに適用されてしまう。これにより、多くのページが同じサイト共通の説明文を共有し、重複が発生する。VitePress（バイトプレス）も同様に、.vitepress/configファイルに記述された説明文が全てのページにデフォルトで適用され、各ページのフロントマターで設定された説明文がこれを上書きする。Starlightと同じく、フロントマターで個別の説明文が設定されていないページが増えると、サイト共通の説明文が多数のページで使われることになる上、繰り返し使われる見出しがそのままタイトルとして使われることで重複タイトルが発生してしまう。

これらの重複問題を発見するためには、ドキュメントのソースファイル（Markdownなど）ではなく、実際にビルドされて生成されたHTMLファイルをチェックすることが不可欠である。検索エンジンのクローラーは、このビルドされたHTMLファイルを読み取るからだ。ドキュメントをビルドした後、出力フォルダ（Docusaurusならbuild、Starlightならdist、VitePressなら.vitepress/distなど）に対して、コマンドラインツールであるgrepを使うことで、重複する<meta name="description">タグや<title>タグを検出できる。例えば、grep -rhoE --include='*.html' '<meta name="description" content="[^"]*"' build | sort | uniq -cd | sort -rnといったコマンドを使えば、複数のページで使われている説明文とその回数を表示できる。同様に、タイトルについても同様のgrepコマンドで重複を検出できる。特定の文字列を持つ説明文を共有しているファイルを特定するには、grep -rlF --include='*.html' 'content="Overview"' buildのように実行すれば良い。これらのコマンドが期待通りに機能しない場合は、生成されたHTMLファイルを直接開き、タグの記述形式に合わせてパターンを調整すると良いだろう。また、公開済みのサイトであれば、無料のオンラインサイトチェッカーやSEOチェッカーを利用することで、サイトマップから重複しているタイトルや説明文、それらを共有するページを簡単にリストアップできる。

重複が見つかった場合、各フレームワークのルールに従って修正を行う。Docusaurusでは、各ドキュメントのフロントマターでtitleとdescriptionの両方を明示的に設定することが重要だ。このdescriptionは検索結果のスニペットだけでなく、SNS共有時のプレビュー表示にも利用される。例えば、

---
title: CLIの設定
description: headlark.config.json のすべてのオプションについて、デフォルト値とモノレポでの例を含めて解説します。
sidebar_label: 設定
---

のように記述する。sidebar_labelはサイドバーに表示される名前なので、titleとは異なる簡潔な内容で構わない。検索結果に表示したくない古いバージョンのドキュメントがある場合は、Docusaurusの設定ファイル（docusaurus.config.js）で、そのバージョンのdocsプラグインオプションにnoIndex: trueを設定することで、検索エンジンのインデックス登録から除外できる。

Starlightの場合も同様に、各ページのフロントマターでtitleとdescriptionを設定する。サイト全体の設定ファイル（astro.config.mjs）にある共通の説明文は、ホームページ専用として扱い、それ以外のページで共通説明文が表示されている場合は、個別の説明文が未設定のページと見なして修正を行うべきだ。Starlightはページタイトルとサイトタイトルを|（デフォルト）で結合するため、ページタイトル部分がユニークであることが求められる。

VitePressの場合も、各ページのフロントマターでtitleとdescriptionを設定する。サイト共通の説明文を継承しているページを見つけるには、VitePressの設定ファイル（.vitepress/config.mts）にtransformPageDataフックを追加することで、ビルド時に説明文が設定されていないページを警告として出力させることができ、設定漏れを防ぐのに役立つ。

ユニークで効果的なタイトルと説明文を作成するためのコツは、まずタイトルにページの主題を明確に含めることだ。「Configuration」のような一般的な単語ではなく、「CLIの設定」のように具体的な内容を示す方が、ユーザーにとって分かりやすい。説明文には、そのページを他のページと区別するための詳細情報を含める。例えば、具体的なオプション名、対応するプラットフォーム、ユーザーが検索しそうなエラーメッセージなどを盛り込むと良いだろう。文章の長さは1〜2文、約70文字から155文字程度が目安で、検索結果で途切れないように調整する。ただし、キーワードをただ羅列するだけでは検索エンジンの評価は上がらず、むしろ逆効果になることもあるため、自然で分かりやすい文章でページの核心を伝えることが最も重要だ。APIリファレンスや変更履歴など、自動生成されるページについては、そのページ固有のデータ（クラス名やバージョン番号など）を使って説明文を生成することで、重複を避けられる。また、この問題が再発しないように、新しいページをコピーして作成する際に、重複チェックを継続的インテグレーション（CI）などの自動化プロセスに組み込むことを推奨する。

大規模なドキュメントサイトでは、すべてのページに対して手動でタイトルや説明文を記述し、維持していくのは非常に手間がかかり、見落としも発生しがちだ。このような課題に対しては、Headlark（ヘッドラーク）のような自動化ツールが有効である。Headlarkは、ドキュメントフレームワークのビルドプロセス完了後に動作し、生成されたHTMLファイルの内容に基づいて、各ページに最適なタイトルと説明文を自動的に生成する。これにより、内容が全く同じでない限り、タイトルや説明文が重複することはなくなる。既存のcanonicalタグやrobotsディレクティブ、JSON-LDタイプは保持されるため、既存のSEO設定が損なわれる心配はない。また、変更されていないページはキャッシュから提供されるため、再ビルドも高速だ。一部のフレームワークでは、初回読み込み後にブラウザタブに元のタイトルが表示される場合があるが、検索エンジンのクローラーやSNSのリンクプレビューはHeadlarkが書き換えたタグを正確に読み込むため、SEO効果は問題ない。まずはアクセス数の多いページで自動生成された結果を確認し、必要に応じて調整することで、効率的にドキュメントサイトのSEOを最適化できる。Headlarkは無料プランも提供されており、1サイト25ページまで利用可能なので、試してみる価値はあるだろう。ドキュメントサイトの品質を高め、必要な情報がユーザーに確実に届くようにするためには、タイトルと説明文の最適化が重要な課題であると理解しておくべきだ。