リンク切れチェック

TRACERYのページに記載されたURLが正しくアクセスできるかをチェックし、リンク切れを修正する方法を説明します。

Sphinx linkcheckでリンク切れを確認する

TRACERYは Sphinx を使ったドキュメントエクスポート機能を提供しています。 Sphinxには linkcheck ビルダーが組み込まれており、ドキュメント内のリンクが有効かどうかを自動的に検証できます。

エクスポートについては、下記リンク先を参照してください。

👉 プロジェクトをエクスポートする

準備

TRACERYからダウンロードしたZIPファイルを展開します。

unzip myproject.zip -d myproject
cd myproject

展開したディレクトリーには以下のファイルが含まれています。

myproject/
├── Makefile          # Sphinxビルド用
├── README.md
├── requirements.txt  # Sphinx依存パッケージ
├── source/           # Markdownソースファイル
│   ├── conf.py
│   ├── index.md
│   ├── page_XXXXX.md
│   └── ...
└── build/            # ビルド成果物（最初は空）

Sphinxと必要なパッケージをインストールします。

pip install -r requirements.txt

実行方法

Makefile のあるディレクトリーで以下のコマンドを実行します。

make linkcheck

実行すると、ソースファイルを1つずつ読み込みながらリンクをチェックします。

Running Sphinx v9.1.0
...
building [linkcheck]: targets for 36 source files that are out of date
updating environment: [new config] 36 added, 0 changed, 0 removed
reading sources... [  3%] category_0
reading sources... [  6%] page_xxxxx
...
(page_xxxxx: line 10) broken    https://example.com/old-page - 404 Client Error
build finished with problems, N warnings.

チェックが完了すると build/linkcheck/ に結果ファイルが生成されます。

結果の確認

output.txt

問題のあるリンクだけが1行ずつ出力されます。リンク切れがなければファイルは空になります。

source/page_xxxxx.md:10: [broken] https://example.com/old-page - 404 Client Error: Not Found
source/page_yyyyy.md:55: [broken] https://example.com/moved-page - 404 Client Error: Not Found

各行の形式は以下の通りです。

<ファイル名>:<行番号>: [<ステータス>] <URL> - <詳細メッセージ>

output.json

全リンクの結果がJSON Lines形式（1行1レコード）で出力されます。スクリプトで処理する場合に便利です。

{"filename": "page_xxxxx.md", "lineno": 10, "status": "broken", "code": 0, "uri": "https://example.com/old-page", "info": "404 Client Error: Not Found"}
{"filename": "page_yyyyy.md", "lineno": 3,  "status": "working", "code": 200, "uri": "https://example.com/valid", "info": ""}

ステータスの種類

ステータス

意味

working

リンクが正常にアクセスできる

broken

リンク先にアクセスできない（404など）

redirected

リンク先がリダイレクトされている

timeout

アクセスがタイムアウトした

ignored

チェック対象外に設定されている

unchecked

ページ内アンカー（#始まり）などチェック対象外

修正が必要なのは主に broken のリンクです。output.txt に [broken] として記録されます。

broken と判定されやすいケース

  • 削除・移転されたページ: リンク先のURLが404や410を返す

  • 誤記: URLのタイポや不完全なURL

  • 内部リンクの誤記: <int:id> のようなパスパラメーターがURLとして誤認識される場合がある

このようなケースは output.txt の内容を見て、実際にブラウザーで確認してから修正してください。

TRACERY上でリンク切れを修正する（LLM + MCP活用）

linkcheckで検出したリンク切れを、LLMとTRACERY MCPを使って効率よく修正できます。

前提

修正の流れ

  1. make linkcheck を実行し、build/linkcheck/output.txt を確認する

  2. output.txt の内容をAIエージェントに渡し、リンク切れの修正を依頼する

  3. AIエージェントがTRACERY MCPを通じてページを検索・更新する

  4. 修正後に再度 make linkcheck を実行して確認する

プロンプト例

AIエージェントのチャットに output.txt を添付して、以下のようなプロンプトを送ります。

linkcheckの結果ファイル output.txt を添付します。
broken となっているリンクを、#tracery のMCPツールを使って修正してください。
リンク先のページをWeb検索で調べ、正しいURLに更新してください。
修正前に、変更内容を確認させてください。

AIエージェントは以下の手順で修正を進めます。

  1. output.txt から broken ステータスのURLを抽出する

  2. 現在有効なURLをWeb検索などで調査する

  3. TRACERY MCPのツール（#search_text でページを特定し、#update_page で更新する）を使って修正する

注意事項

  • AIが提案する修正URLは必ず人間が確認してください（ハルシネーションの可能性があります）

  • timeout ステータスのリンクは、ネットワーク環境やサーバー側の一時的な問題の場合があるため、時間をおいて再実行して確認することをお勧めします

  • redirected ステータスのリンクは必ずしも修正が必要ではありませんが、リダイレクト先のURLに更新しておくと将来的なリンク切れを防げます