リンクチェッカー

ビルド後の内部リンクを検証するリンクチェッカー。ビルド済みHTMLとMDXソースファイルを対象にします。

リンクチェッカー

zudo-docには、サイトビルド後に2種類の検証を行う組み込みリンクチェッカー（scripts/check-links.js）が含まれています。

チェック内容

モード1: ビルド済みHTMLスキャン

dist/内のすべての.htmlファイルをスキャンし、内部<a href="...">リンクの各ターゲットがディスク上に存在するかを検証します。以下を処理します：

• ベースパスの除去（例：/my-docs/docs/foo → docs/foo）

• 末尾スラッシュの解決（docs/foo/ → docs/foo/index.html）

• 拡張子の解決（docs/foo → docs/foo/index.htmlまたはdocs/foo.html）

• 解決前のクエリ文字列とフラグメントの除去

• ファイルのディレクトリに対する相対リンクの解決

• パフォーマンスのための解決済みパスのキャッシュ

スキップされるリンク（チェック対象外）：

• 外部URL（https://、http://）

• アンカーのみのリンク（#section）

• mailto:、javascript:、data:、tel: URI

• バージョン付きドキュメントリンク（/v/*/） — バージョンコンテンツが不完全な場合があるため

モード2: MDXソーススキャン

設定されたコンテンツディレクトリ内のすべての.mdxおよび.mdファイルをスキャンし、ベースパスをバイパスする絶対リンクを検出します。以下のようなリンクが対象です：

<!-- これらはフラグされます — ベースパスをバイパスしています -->
[guide](/docs/guides/foo)
<a href="/ja/docs/guides/foo">link</a>

<!-- これらは問題ありません — 相対パスを使用しています -->
[guide](./foo.mdx)
[guide](../other/bar.mdx)

ベースパスが設定されている場合（例：/my-docs/）、/docs/や/ja/docs/で始まる絶対リンクはベースパスのプレフィックスが欠けているため壊れます。MDXソーススキャンは、これらが本番環境で壊れたリンクになる前に検出します。

フェンスドコードブロック内のリンクは無視されます。

リンクチェッカーの実行

単独実行

まずサイトをビルドし、チェッカーを実行します：

pnpm build && pnpm check:links

失敗対象カテゴリのフラグ

デフォルトでは、問題が見つかってもチェッカーは終了コード0で終了します。コマンドを失敗させるカテゴリは、--strict-broken、--strict-absolute、--strict-trailingで明示的に選択します。b4pushとCIのワークフローでは、末尾スラッシュの指摘を情報扱いのままにし、リンク切れとMDX内の絶対リンクを失敗対象にしています：

pnpm check:links -- --strict-broken --strict-absolute --allowlist=.check-links-allowlist

現在のCLIオプションはpnpm check:links -- --helpで確認できます。

アローリスト

--allowlist=PATHは、厳格モードの失敗カウントから正確な<file>:<line>:<href>のエントリを除外します。ソース側で修正できない問題向けです。例えば、JAページが意図的にEN専用の姉妹ページにリンクしている場合や、対応するMDXファイルが存在しないランタイム生成ルートを指す絶対hrefなどです。リポジトリには実際のアローリストが.check-links-allowlistとして同梱されています：1行につき1つの<file>:<line>:<href>エントリで、#コメントと空行は無視されます。各エントリは出力されるレポートと完全一致する必要があります — リポジトリルートからの相対ファイルパス、1始まりの行番号、ソースまたはビルド済みHTMLに現れたとおりのhrefです。根本原因が修正されたら、そのエントリを削除してください。そうすることで、厳格ゲートが同種の回帰を今後検出できるようになります。

b4pushの一部として

リンクチェッカーはプッシュ前検証（pnpm b4push）の23ステップ中ステップ20で、ビルドステップの直後に実行されます：

19. Build
20. **Link check**
21. HTML validation

b4pushのステップ一覧の正式・権威的な定義はscripts/run-b4push.shの冒頭コメントにあります。このスクリプトを、23ステップ全体の唯一の信頼できる情報源として扱ってください。

CI内での実行

リンクチェッカーはPRチェックワークフロー（pr-checks.yml）のbuild-siteジョブで、pnpm buildの直後に実行されます。

出力

問題がない場合：

Checking links (base: /my-docs/)...

✓ No broken links or absolute path issues found

問題がある場合：

Checking links (base: /my-docs/)...

=== Broken Links in Built HTML ===
  dist/docs/page/index.html:42  /my-docs/docs/missing-page

=== Absolute Links Bypassing Base Path (MDX Source) ===
  src/content/docs/guides/test.mdx:15  /docs/guides/foo

✗ Found 1 broken link and 1 absolute path warning

各エントリはファイルパス、行番号、問題のあるhrefを表示します。

設定

リンクチェッカーは解決済みの設定（zfb.config.tsでzudoDoc({...})に渡すフィールド）から設定を読み取ります：

• base — サイトのベースパス。リンク解決時のプレフィックス除去に使用

• docsDir — MDXソーススキャンのプライマリコンテンツディレクトリ

• locales — ロケール設定。dirフィールドでMDXソーススキャンの追加コンテンツディレクトリを指定（例：locales: { ja: { dir: "src/content/docs-ja" } }）