**Core 機能** — 常に有効です。設定は不要です。

## 概要

markdown 内でファイルパスを使った相対リンク（例: `[link](./other-page.mdx)`）を記述すると、zfb はそのパスをページが配信される最終 URL に書き換えます。これにより、ファイル相対パスでリンクを記述しながら、ビルド後のサイトでは `.mdx` 拡張子のないクリーンな URL が提供されます。

mdast フェーズでの書き換えプロセスは以下のとおりです。

1. 現在のソースファイルからの相対パスを解決する。
2. 解決されたパスを、起動時に構築されたコンテンツソースマップで検索する。
3. リンクターゲットをマップされた出力 URL で置き換える。
4. ターゲットファイルがソースマップに存在しない場合は警告を出力する。

## 例

```md
詳細は [設定オプション](./resolve-links.mdx) を参照してください。
```

`/docs/markdown-features/resolve-links` を指すリンクとして出力されます（生のファイルパスではありません）。

## 壊れたリンクの警告

ターゲットファイルがソースマップに存在しない場合、zfb は診断警告を出力します。デフォルトでは壊れたリンクによってビルドは失敗しません。警告をエラーにエスカレートするには、オプトインの [Link Validation](https://zudo-doc.takazudomodular.com/ja/docs/markdown-features/link-validation) 機能を有効にしてください。

## 上級: 複数ディレクトリ、ロケール、バージョン

Resolve Links は各コンテンツディレクトリをルートプレフィックスにマッピングします。zfb はディレクトリごとに 1 つのエントリを登録し、リライターが各ソースツリーに対応する URL プレフィックスを特定できるようにします。

デフォルトのシングルロケール構成では、1 つのディレクトリが登録されます。

```ts
resolveMarkdownLinks: {
  enabled: true,
  dirs: [
    { dir: settings.docsDir, routePrefix: "/docs/" },
  ],
}
```

ロケールが設定されている場合、各ロケールのコンテンツディレクトリにはロケールプレフィックス付きのルートエントリが追加されます。

```ts
resolveMarkdownLinks: {
  enabled: true,
  dirs: [
    { dir: settings.docsDir, routePrefix: "/docs/" },
    // ロケールごと: 各ロケールディレクトリを /<code>/docs/ にマッピング
    { dir: settings.locales.ja.dir, routePrefix: "/ja/docs/" },
  ],
}
```

日本語ソースファイル内の相対リンク（例: `[page](./other.mdx)`）が `/docs/...` ではなく `/ja/docs/...` に解決されるのはこのためです。リライターはファイルのソースディレクトリを正しいプレフィックスに照合します。

バージョン管理されたコレクションも有効な場合、同じパターンが各バージョンの英語ディレクトリおよびそのロケールごとのミラーにも適用されます。

```ts
resolveMarkdownLinks: {
  enabled: true,
  dirs: [
    { dir: settings.docsDir, routePrefix: "/docs/" },
    { dir: settings.locales.ja.dir, routePrefix: "/ja/docs/" },
    // バージョン管理: バージョンごとに英語ディレクトリ + ロケールディレクトリ
    { dir: version.docsDir, routePrefix: "/v/1.0/docs/" },
    { dir: version.locales.ja.dir, routePrefix: "/v/1.0/ja/docs/" },
  ],
}
```

このプロジェクトの実際の `zfb.config.ts` では、`dirs` 配列が `settings.locales` および `settings.versions` から動的に構築されます。そのため、新しいロケールやバージョンを追加しても `dirs` を手動で編集する必要はありません。

## 補足

- このプラグインは hast 処理の前、mdast フェーズで動作します。
- [Strip .md Extension](https://zudo-doc.takazudomodular.com/ja/docs/markdown-features/strip-md-ext) 機能は Resolve Links の後に実行され、最終出力のリンク href に残っている `.md` または `.mdx` サフィックスを除去します。
- 絶対 URL はこのプラグインで処理されません。