## 概要

`DocCardNav` は、明示的に並べた文書スラッグの一覧からカードグリッドを描画します。「まずはここから」のように、いくつかの選んだページへ読者を案内したいときに使います（あるカテゴリの子ページをすべて並べる場合は [`CategoryNav`](https://zudo-doc.takazudomodular.com/ja/docs/components/category-nav/) を使います）。

各スラッグは、サイドバーと同じロケール・バージョン・ベースパスに対応したナビゲーションデータで解決されます。タイトルと説明はリンク先ページのフロントマターから取得するため、内容を重複して書く必要はありません。

**Info**

`DocCardNav` と `WideSectionHeading` は MDX のドキュメントページでグローバルに使え、インポートは不要です。現在のロケールとバージョンは自動で渡されます。



## 実例

- [はじめに](https://zudo-doc.takazudomodular.com/ja/docs/getting-started/introduction/): zudo-doc とは何か、その機能、そしてどのように動作するかを学びましょう。
- [インストール](https://zudo-doc.takazudomodular.com/ja/docs/getting-started/installation/): zudo-doc のインストールとローカル開発環境のセットアップ方法。
- [設定](https://zudo-doc.takazudomodular.com/ja/docs/guides/configuration/): 唯一の zudoDoc() 設定リファレンス — 全フィールドとそのデフォルト。

## 使い方

```mdx
<WideSectionHeading>Start here</WideSectionHeading>

<DocCardNav
  docs={[
    "getting-started/introduction",
    "getting-started/installation",
    "guides/configuration",
  ]}
/>
```

`DocCardNav` はすべてサーバー側で描画され、クライアント側の JavaScript は使いません。

## プロパティ

| プロパティ | 型 | デフォルト | 説明 |
|------|------|---------|-------------|
| `docs` | `string[]` | — | 表示順に並べた正規の文書スラッグ（例: `"guides/configuration"`。先頭のスラッシュ、ロケール接頭辞、拡張子は付けない） |
| `ariaLabel` | `string` | `"Selected documents"` | カードナビゲーションのアクセシブルな名前 |
| `layout` | `"auto" \| "default"` | `"auto"` | `"auto"` は利用できる幅に合わせて最大 3 列で並べ、`"default"` は `DocCardGrid` 従来の 1〜2 列レイアウトを使う |

## 解決のルール

- カードは `docs` の順に並びます。同じスラッグが複数回あるときは、最初の位置だけに表示されます。
- 独自の URL を持つ公開ページに解決できないスラッグは、リンクになりません。存在しないページ、下書き、不正なスラッグ、インデックスページのないカテゴリは省かれ、ビルド時にスラッグと理由を示す `[zudo-doc]` の警告が出ます。
- 解決できるスラッグが 1 つもないときは、何も描画されません。

## WideSectionHeading

`WideSectionHeading` は、本文の見出しと同じタイポグラフィとグラデーションの上罫線を持つ、意味的な `h2` です。外側の余白を持たないため、間隔は周囲のレイアウトが決めます。`id` を含め、通常の見出しの属性を受け付けます。

```mdx
<WideSectionHeading id="start-here">Start here</WideSectionHeading>
```

## カードのレイアウト

内部で使う `DocCardGrid` コンポーネント（`@takazudo/zudo-doc/nav-indexing`）に、`DocCardNav` が使う `layout="auto"` を任意で指定できるようになりました。指定しない場合、`DocCardGrid` は従来どおり 1〜2 列のレイアウトです。

## ホームページでの利用

ホームページの紹介文 Markdown では、これらのコンポーネントは使えません。ホームページに選んだ文書を表示するには、[ナビゲーションセクションの構成](https://zudo-doc.takazudomodular.com/ja/docs/guides/configuration/#%E3%83%9B%E3%83%BC%E3%83%A0%E3%83%9A%E3%83%BC%E3%82%B8-home-%E3%83%8A%E3%83%93%E3%82%B2%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E3%82%BB%E3%82%AF%E3%82%B7%E3%83%A7%E3%83%B3%E3%81%AE%E6%A7%8B%E6%88%90)で説明している `home.sections` を使います。同じ見出しとカードが描画されます。カードをサイトインデックスの前や後ろに置く完全なホーム設定は、[ホームページの構成例](https://zudo-doc.takazudomodular.com/ja/docs/components/home-hero/#%E3%83%9B%E3%83%BC%E3%83%A0%E3%83%9A%E3%83%BC%E3%82%B8%E3%81%AE%E6%A7%8B%E6%88%90%E4%BE%8B)にあります。

## パッケージ API

ページモジュールでは、`@takazudo/zudo-doc/doc-card-nav` の `createDocCardNavWrapper` で同じコンポーネントを作れます。このサブパスは `resolveDocCards`（項目と診断結果を返す純粋な解決関数）、`reportDocCardDiagnostics`、`isCanonicalDocSlug` も公開しています。