## ドキュメントの作成
`src/content/docs/` に `.mdx` ファイルを作成します。フロントマターでメタデータを指定してください：
```mdx
---
title: My Page
description: A brief summary of this page.
sidebar_position: 1
---
Your content here.
```
### フロントマターフィールド
| フィールド | 型 | 必須 | 説明 |
|-------|------|----------|-------------|
| `title` | string | はい | ページタイトル（サイドバーとヘッダーに表示） |
| `description` | string | いいえ | タイトルの下に表示される説明文 |
| `sidebar_position` | number | いいえ | カテゴリ内の並び順（小さい値が先） |
| `sidebar_label` | string | いいえ | サイドバーの表示名を上書き |
[Dynamic content unavailable in text export]
ドキュメントのコンテンツ内で `# h1` 見出しを使用しないでください。フロントマターの `title` がページタイトル（h1）として自動的にレンダリングされます。コンテンツは `## h2` 見出しから始めてください。
[Dynamic content unavailable in text export]
利用可能なすべてのフィールドの完全なリファレンスは[フロントマターガイド](https://zudo-doc.takazudomodular.com/ja/docs/guides/frontmatter)をご覧ください。
## ディレクトリ構造
ディレクトリを使ってドキュメントをカテゴリに整理します：
```
src/content/docs/
getting-started/
introduction.mdx # sidebar_position: 1
installation.mdx # sidebar_position: 2
writing-docs.mdx # sidebar_position: 3
guides/
configuration.mdx # sidebar_position: 1
sidebar.mdx # sidebar_position: 2
```
各ディレクトリは自動的にサイドバーの折りたたみ可能なカテゴリになります。カテゴリ名はディレクトリ名から自動生成されます（ケバブケースからタイトルケースに変換）。
## ドキュメント間のリンク
**相対ファイルパス**を使って他のドキュメントにリンクできます：
```mdx
[Installation guide](./installation.mdx)
[Frontmatter reference](../guides/frontmatter.mdx)
[Back to index](./index.mdx)
```
これらの相対パスはビルド時に正しいURLに自動的に解決されます。リンクリゾルバーが動作するには `.md`/`.mdx` 拡張子が必要です。これによりファイルリンクとURLリンクを区別します。
アンカーやクエリ文字列も含めることができます：
```mdx
[Frontmatter fields](../guides/frontmatter.mdx#required-fields)
```
[Dynamic content unavailable in text export]
相対リンクはビルド時に検証されます。リンク先のファイルが存在しない場合、ビルド出力に警告が表示されます。これにより壊れたリンクを早期に検出できます。
外部リンクやドキュメント以外のページへのリンクには、通常のURLを使用してください：
```mdx
[External site](https://example.com)
[API reference](/api/v1)
```
## アドモニション
zudo-docはDocusaurusスタイルのアドモニションをサポートしています。グローバルに登録されているため、インポート不要です：
[Dynamic content unavailable in text export]
これは**ノート**です — 読者が知っておくべき一般的な情報に使用します。
[Dynamic content unavailable in text export]
これは**ヒント**です — 役立つ提案やベストプラクティスに使用します。
[Dynamic content unavailable in text export]
これは**情報**ブロックです — 追加のコンテキストや背景情報に使用します。
[Dynamic content unavailable in text export]
これは**警告**です — 潜在的な問題や注意点をフラグするために使用します。
[Dynamic content unavailable in text export]
これは**危険**アラートです — データ損失や破壊的変更に関する重大な警告に使用します。
[Dynamic content unavailable in text export]
これは**注意（caution）**アラートです — 高深刻度で danger に準じる位置づけです。GitHubスタイルの `[!CAUTION]` アラートもこの表示になります。
### カスタムタイトル
[Dynamic content unavailable in text export]
`title` プロップを使って、任意のアドモニションにカスタムタイトルを設定できます。
### アドモニションの構文
2つの構文がサポートされています。どちらもインポート不要です。
**ディレクティブ構文**（コンテンツ作成者向け推奨）：
```mdx
:::note[Optional Title]
Content here.
:::
```
**JSXコンポーネント構文**：
```mdx
Default note with auto-generated title.
Warning with a custom title.
```
各アドモニションタイプは、ボーダーとタイトルの色にセマンティックカラートークンがマッピングされています：
| タイプ | カラートークン | 一般的な色 |
|------|-------------|---------------|
| Note | accent | オレンジ |
| Tip | success | 緑 |
| Info | info | 青 |
| Warning | warning | 黄 |
| Danger | danger | 赤 |
| Caution | danger | 赤 |
[Dynamic content unavailable in text export]
アドモニションやコードブロックなど、利用可能なすべてのコンポーネントの一覧は[コンポーネント](https://zudo-doc.takazudomodular.com/ja/docs/components)リファレンスをご覧ください。
## i18n（国際化）
デフォルトのスキャフォールドは1つのプライマリロケールだけで、追加ロケール用ディレクトリもロケールルートもありません。`--additional-langs ja,de`（または同等のプリセット/APIフィールド）を指定すると、`src/content/docs-ja/` と `src/content/docs-de/`、および `/ja/docs/...` と `/de/docs/...` を配信する `pages/[locale]/docs/[[...slug]].tsx` が作成されます。プライマリコンテンツは `/docs/...` の `src/content/docs/` に残り、後から `zudoDoc({ ... })` の `locales` フィールドで追加ロケールを変更できます。
設定した各ツリーの構造を揃えます。相対ファイル名、フロントマター、コードブロック、JSX例を同じにし、各ロケールで文章を翻訳してください。`ja` のスターターは日本語、それ以外の任意のロケールツリーは英語のプレースホルダー文章から始まるため、公開前に翻訳が必要です。言語切り替えは設定したラベルと順序に従い、UI文字列は要求ロケール → デフォルトロケール → パッケージの英語 → 生のキーの順にフォールバックします。
[Dynamic content unavailable in text export]
翻訳と言語ルーティングの管理に関する詳しい手順は[i18nガイド](https://zudo-doc.takazudomodular.com/ja/docs/guides/i18n)をご覧ください。
## MDXの機能
ドキュメント内でzudo-reactコンポーネントを使用できます。素の MDX コンポーネントインポートはサーバーでレンダリングされ、JavaScriptゼロの HTML として配信されます。
新しくスキャフォールドされたプロジェクトには `src/components/` ディレクトリはありません — カスタムコンポーネントが必要になったら自分で作成します。`@/*` パスエイリアスは `src/*` にマップされるので、`src/components/my-component.tsx` のファイルは次のようにインポートします:
```mdx
import MyComponent from "@/components/my-component";
```
[Dynamic content unavailable in text export]
コンポーネントを単にインポートするだけではサーバー側でのみレンダリングされ、JavaScriptはゼロです。ドキュメント全体でコンポーネントを登録する場合やインタラクティブアイランドを追加する場合は、[カスタムコンポーネント](https://zudo-doc.takazudomodular.com/ja/docs/guides/custom-components) を参照してください。グローバル登録には `mdxExtras` を、クライアントハイドレーションには実験的な `Island()` レシピを使います。
## ナビゲーション
zudo-docは以下を自動生成します：
- **サイドバー** — `sidebar_position` でソートされたアイテムを持つ折りたたみ可能なカテゴリ
- **目次** — 右サイドバーにh2〜h4の見出し（ワイドスクリーンで表示）
- **前/次リンク** — ドキュメント間のボトムナビゲーション
- **パンくずリスト** — タイトルの上に表示されるカテゴリパス