ドキュメントの書き方
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/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各ディレクトリは自動的にサイドバーの折りたたみ可能なカテゴリになります。カテゴリ名はディレクトリ名から自動生成されます（ケバブケースからタイトルケースに変換）。
ドキュメント間のリンク
相対ファイルパスを使って他のドキュメントにリンクできます：
[インストールガイド](./installation.mdx)
[フロントマターリファレンス](../guides/frontmatter.mdx)
[インデックスに戻る](./index.mdx)これらの相対パスはビルド時に正しいURLに自動的に解決されます。リンクリゾルバーが動作するには .md/.mdx 拡張子が必要です。これによりファイルリンクとURLリンクを区別します。
アンカーやクエリ文字列も含めることができます：
[フロントマターフィールド](../guides/frontmatter.mdx#required-fields)💡 Tip
相対リンクはビルド時に検証されます。リンク先のファイルが存在しない場合、ビルド出力に警告が表示されます。これにより壊れたリンクを早期に検出できます。
外部リンクやドキュメント以外のページへのリンクには、通常のURLを使用してください：
[Astroドキュメント](https://docs.astro.build)
[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コンポーネントを使用できます。インタラクティブなコンポーネントはAstroアイランドとしてハイドレートされ、残りは純粋なHTMLとしてJavaScriptゼロで配信されます。
import MyComponent from "@/components/my-component";
<MyComponent client:load />ℹ️ Info
インタラクティブ性が必要なコンポーネントには client:load を使用してください。静的HTMLのみをレンダリングするコンポーネントでは省略します。
ナビゲーション
zudo-docは以下を自動生成します：
- サイドバー —
sidebar_positionでソートされたアイテムを持つ折りたたみ可能なカテゴリ - 目次 — 右サイドバーにh2〜h4の見出し（ワイドスクリーンで表示）
- 前/次リンク — ドキュメント間のボトムナビゲーション
- パンくずリスト — タイトルの上に表示されるカテゴリパス