リンク検証

Opt-in

作成 2026年6月24日Takeshi Takatsudo

ビルド時に内部リンクとアンカーフラグメントを検証し、壊れた参照が本番環境に届く前に検出する。

linkValidation 機能は、ビルド内のすべての <a href> と <img src> をたどり、内部リンクとアンカーフラグメントが正しく解決されるかを検証します。壊れたリンクはビルド診断を生成します — デフォルトでは警告、failOnBroken: true を設定するとエラーになります。

外部 URL（http://、https://、mailto: など）はデフォルトで黙ってスキップされます。

有効化

// zfb.config.ts
export default defineConfig({
  markdown: {
    features: {
      linkValidation: {},   // デフォルト: 警告のみ、外部 URL はスキップ
    },
  },
});

壊れたリンクでビルドを失敗させるには:

linkValidation: { failOnBroken: true },

検証される対象

素のアンカーフラグメント — #section-id は、現在のファイル内の見出し ID に一致しなければなりません。
アンカーなしのファイルリンク — ./other.md は、プロジェクトルート以下に存在するファイルへ解決されなければなりません。
アンカー付きのファイルリンク — ./other.md#section-id は、解決可能なファイルと、そのファイル内の一致する見出し ID の両方を必要とします。

見出し ID は HeadingLinksPlugin に由来します。これは同じ hast フェーズ内でより早く実行されます。ファイル横断の見出し ID レジストリはビルド中に構築されるため、アンカー検証はファイルをまたいで機能します。トランスクルージョン経由で取り込まれた見出しもレジストリに含まれるため、./target.mdx#transcluded-heading も正しく検証されます。

スキップされる対象

http://、https://、mailto:、tel: で始まる外部 URL。
BuildContext なしで描画されたファイル内のリンク（例: コンテキストを伴わない単純なインメモリのパイプライン呼び出し）。
対象ファイルがバンドラーの走査対象ディレクトリ（pages、コンテンツコレクション、components、layouts）の外にある、ファイル横断のアンカーリンク。これらは存在チェックのみの検証に格下げされます。ファイルはディスク上に存在しなければなりませんが、フラグメントはチェックされません。対象ファイルがビルドに含まれている場合は、フラグメントも常に検証されます。

オプション

failOnBroken — true のとき、壊れたリンクは Error 診断を出力します（ビルドが失敗します）。デフォルト: false（警告のみ）。

診断フォーマット

診断は MarkdownDiagnostic の共有 BrokenLink バリアントに従います:

severity — failOnBroken に応じて Warning または Error。
url — 著者が記述したままの生の href または src の値。
location.path — 壊れたリンクを含むソースファイルの絶対パス。

980 での挙動変更

#980 以前は、ファイル横断のアンカーフラグメント（./other.md#section）は存在のみが検証され、フラグメント自体は対象ファイルの見出しに対してチェックされていませんでした。#980 以降は、ビルド内のすべてのファイルについて、コンパイル後にフラグメントが検証されます。failOnBroken: true のもとで壊れたファイル横断アンカーを含みながら以前は通過していたビルドは、今後は失敗します。

フェーズ

2 つのフェーズで実行されます:

コンパイルごとの hast フェーズ — LinkValidationPlugin が同一ファイル内のアンカー（#section-id）を即座に検証し、コンパイル後に解決するファイル横断フラグメントの候補を記録します。
コンパイル後のバンドラーパス — すべてのファイルがコンパイルされた後、バンドラーは各ファイルの記録済み見出しから見出しマップを構築し、記録済みのファイル横断候補をそれぞれ検証します。検出結果は、他の Markdown 診断と同じ severity ゲートを通じて振り分けられます。