リンク解決

コンテンツのソースマップを使って内部リンクの参照先を書き換え、ビルドを通してリンクを維持する。

ResolveLinksPlugin は、起動時に構築されたコンテンツのソースマップを使って、内部 Markdown リンク（[text](./page.mdx)、[text](../other/page)）を正規化します。この機能はオプトインです — 有効化の方法は下記の設定を参照してください。

何をするか

mdast フェーズで、HTML が生成される前に、プラグインはすべての Link ノードをたどります。各相対リンクに対して:

現在のソースファイルを基準にパスを解決する。
解決したパスをコンテンツのソースマップで照合する。
見つかった場合は、url をそのエントリの最終出力 URL に書き換える。
見つからない場合は、警告診断を出力してリンクをそのまま残す。

これにより、相対ファイルパスとして記述されたリンクの参照先（ローカルで編集しながらコンテンツを相互リンクする際の自然な書き方）は、ファイルから URL へのマッピングがどう設定されていても、ビルド後のサイトで正しい出力 URL を生成します。

設定

リンク解決は、zfb.config.ts で resolveMarkdownLinks: { enabled: true } を指定してオプトインしない限り、何も行いません:

zfb.config.ts

export default defineConfig({
  resolveMarkdownLinks: {
    enabled: true,
    docsDir: "src/content/docs",
  },
});

オプション	デフォルト	説明
`enabled`	`false`	プラグインを有効にします。これが `true` になるまで、以下の他のオプションはすべて効果を持ちません。
`docsDir`	`""`	レガシーな単一ディレクトリ指定。このディレクトリを、ハードコードされた `/docs/` ルートプレフィックスに対してスキャンします。`dirs` が空でない場合は無視されます。
`dirs`	`[]`	ソースコレクションごとの `{ dir, routePrefix }` エントリを明示的に列挙します。空でない場合は `docsDir` より優先されます — `docsDir` は単一の `/docs/` プレフィックスしか表現できないため、複数のドキュメントルートを持つプロジェクト（ロケールミラーなど）では必須です。
`onBrokenLinks`	`"warn"`	`.md`/`.mdx` リンクが解決できなかった場合の挙動: `"warn"` はログを出力して続行し、`"error"` は走査中に見つかった壊れたリンクをすべて報告したうえでビルドを失敗させ、`"ignore"` はどちらも行いません。

EN・JA のように複数のドキュメントコレクションを持つプロジェクトでは、各コレクションをそれぞれのルートプレフィックスにマッピングするため dirs を使用します:

zfb.config.ts

export default defineConfig({
  resolveMarkdownLinks: {
    enabled: true,
    dirs: [
      { dir: "src/content/docs", routePrefix: "/docs/" },
      { dir: "src/content/docs-ja", routePrefix: "/ja/docs/" },
    ],
  },
});

リンク解決

何をするか

設定

関連項目

Revision History