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