ドキュメントの書き方
zudo-docでのドキュメントページの作成と整理方法。
ドキュメントの作成
src/ に .mdx ファイルを作成します。フロントマターでメタデータを指定してください：
---
title: マイページ
description: このページの簡単な説明。
sidebar_position: 1
---
ここにコンテンツを記述します。フロントマターフィールド
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
title | string | はい | ページタイトル（サイドバーとヘッダーに表示） |
description | string | いいえ | タイトルの下に表示される説明文 |
sidebar_position | number | いいえ | カテゴリ内の並び順（小さい値が先） |
sidebar_label | string | いいえ | サイドバーの表示名を上書き |
Warning
ドキュメントのコンテンツ内で # h1 見出しを使用しないでください。フロントマターの title がページタイトル（h1）として自動的にレンダリングされます。コンテンツは ## h2 見出しから始めてください。
Note
利用可能なすべてのフィールドの完全なリファレンスはフロントマターガイドをご覧ください。
ディレクトリ構造
ディレクトリを使ってドキュメントをカテゴリに整理します：
src/各ディレクトリは自動的にサイドバーの折りたたみ可能なカテゴリになります。カテゴリ名はディレクトリ名から自動生成されます（ケバブケースからタイトルケースに変換）。
ドキュメント間のリンク
相対ファイルパスを使って他のドキュメントにリンクできます：
[インストールガイド](./installation.mdx)
[フロントマターリファレンス](../guides/frontmatter.mdx)
[インデックスに戻る](./index.mdx)これらの相対パスはビルド時に正しいURLに自動的に解決されます。リンクリゾルバーが動作するには .md/.mdx 拡張子が必要です。これによりファイルリンクとURLリンクを区別します。
アンカーやクエリ文字列も含めることができます：
[フロントマターフィールド](../guides/frontmatter.mdx#required-fields)Tip
相対リンクはビルド時に検証されます。リンク先のファイルが存在しない場合、ビルド出力に警告が表示されます。これにより壊れたリンクを早期に検出できます。
外部リンクやドキュメント以外のページへのリンクには、通常のURLを使用してください：
[外部サイト](https://example.com)
[APIリファレンス](/api/v1)アドモニション
zudo-docはDocusaurusスタイルのアドモニションをサポートしています。グローバルに登録されているため、インポート不要です：
Note
これはノートです — 読者が知っておくべき一般的な情報に使用します。
Tip
これはヒントです — 役立つ提案やベストプラクティスに使用します。
Info
これは情報ブロックです — 追加のコンテキストや背景情報に使用します。
Warning
これは警告です — 潜在的な問題や注意点をフラグするために使用します。
Danger
これは危険アラートです — データ損失や破壊的変更に関する重大な警告に使用します。
カスタムタイトル
カスタムタイトル
title プロップを使って、任意のアドモニションにカスタムタイトルを設定できます。
アドモニションの構文
2つの構文がサポートされています。どちらもインポート不要です。
ディレクティブ構文（コンテンツ作成者向け推奨）：
:::note[任意のタイトル]
ここにコンテンツを記述します。
:::JSXコンポーネント構文：
<Note>
自動生成タイトルのデフォルトノート。
</Note>
<Warning title="注意">
カスタムタイトルの警告。
</Warning>各アドモニションタイプは、ボーダーとタイトルの色にパレットスロットがマッピングされています：
| タイプ | パレットスロット | 一般的な色 |
|---|---|---|
| Note | p4 | 青 |
| Tip | p2 | 緑 |
| Info | p6 | シアン |
| Warning | p3 | 黄 |
| Danger | p1 | 赤 |
Tip
アドモニションやコードブロックなど、利用可能なすべてのコンポーネントの一覧はコンポーネントリファレンスをご覧ください。
i18n（国際化）
zudo-docは英語と日本語をすぐに使える状態でサポートしています。日本語ドキュメントは src/ で英語のディレクトリ構造をミラーリングします。
Tip
翻訳と言語ルーティングの管理に関する詳しい手順はi18nガイドをご覧ください。
MDXの機能
ドキュメント内でPreactコンポーネントを使用できます。インタラクティブなコンポーネントはzfbのアイランドランタイムを介してクライアント側でハイドレートされ、残りは純粋なHTMLとしてJavaScriptゼロで配信されます。
import MyComponent from "@/components/my-component";
<MyComponent />Info
コンポーネントを単にインポートするだけではサーバー側でのみレンダリングされ、JavaScriptはゼロです。インタラクティブアイランドはプロジェクトのアイランドランタイムを通じて登録されます — 単なるコンポーネントのインポートはクライアントでハイドレートされません。アイランドとして登録されたコンポーネントのみがハイドレートされます。
ナビゲーション
zudo-docは以下を自動生成します：
サイドバー —
sidebar_positionでソートされたアイテムを持つ折りたたみ可能なカテゴリ目次 — 右サイドバーにh2〜h4の見出し（ワイドスクリーンで表示）
前/次リンク — ドキュメント間のボトムナビゲーション
パンくずリスト — タイトルの上に表示されるカテゴリパス