## 新しいscaffoldのコマンド

`create-zudo-doc`で作成したプロジェクトには、最初から次のスクリプトがあります：

| コマンド | 説明 |
|---|---|
| `pnpm dev` | zfb開発サーバーを起動 |
| `pnpm build` | 静的HTMLを`dist/`にエクスポート |
| `pnpm preview` | ビルド済みの`dist/`出力をローカルでサーブ |
| `pnpm check` | TypeScript型チェックを実行 |

[Dynamic content unavailable in text export]

選択した機能によって、生成される`package.json`にスクリプトが追加されることがあります。プロジェクトで使えるコマンドはそのファイルを正としてください。



## このリポジトリへのコントリビュート

このリポジトリはzudo-docのショーケースも兼ねています。そのため、パッケージ開発、doc-historyデータ、CI用ツールなど、新しいscaffoldには含まれないコマンドがあります。

### 開発コマンド

| コマンド | 説明 |
|---|---|
| `pnpm dev` | zfb開発サーバー（ポート4321）、doc-history-server（ポート4322）、パッケージwatch、ショーケース開発用ヘルパーを同時に起動 |
| `pnpm dev:zfb` | zfb開発サーバーのみ（ポート4321） |
| `pnpm dev:history` | docヒストリーAPIサーバーのみ（ポート4322） |
| `pnpm dev:zudo-doc` | `@takazudo/zudo-doc`パッケージのwatch。JSのtsup `--watch`と型定義のtsc `--watch`を並列実行 |
| `pnpm dev:stable` | ビルドしてからサーブする代替モード（コンテンツファイルの追加・削除時のHMRクラッシュを回避） |
| `pnpm dev:network` | `--host 0.0.0.0`でzfb開発サーバーを起動（LAN経由アクセス用） |

[Dynamic content unavailable in text export]

ショーケースのコンテンツファイルを頻繁に追加・削除する場合は`pnpm dev:stable`を使用してください。通常の`pnpm dev`はVite HMRのファイルシステム変更でクラッシュすることがあります。



### ビルド・品質コマンド

| コマンド | 説明 |
|---|---|
| `pnpm build` | 静的HTMLを`dist/`にエクスポート |
| `pnpm check` | TypeScript型チェック |
| `pnpm b4push` | プッシュ前の検証：検証のパイプライン（フォーマットチェック → … → Worker contract proof → ビルド → リンクチェック → HTML検証 → プレビュースモーク）。正確なステップ数は`scripts/run-b4push.sh`を正とする。E2Eは時間予算の都合でこのパイプラインには含まれず、CI（pr-checks）側で実行される |
| `pnpm format` | MDXファイルのフォーマット |
| `pnpm test:unit` | ユニットテストを実行（Vitest） |
| `pnpm test:e2e` | E2Eテストを実行（Playwright） |

[Dynamic content unavailable in text export]

プッシュ前に`pnpm b4push`を実行して、サイト全体のビルドとすべてのリンクの解決を確認してください。フォーマットチェックからプレビュースモークまでの一連のステップを実行します。E2Eテストは時間予算の都合でCI（pr-checks）側で実行され、このパイプラインには含まれていません。

b4pushのステップ一覧の正式・権威的な定義は`scripts/run-b4push.sh`の冒頭コメントにあります。このスクリプトを唯一の信頼できる情報源として扱い、ステップに食い違いがあるように見える場合は、インラインの要約ではなくスクリプトを参照してください。



## コンポーネント開発

zudo-docはzfbのzudo-reactランタイムを使用します。すべてのコンポーネントは`.tsx`ファイルです。区別すべき点は、**コンポーネントがサーバーのみで動作するか、クライアントでもハイドレートされるか**です。



### サーバーレンダリングzudo-reactコンポーネント

デフォルトでは、すべての`.tsx`コンポーネントはビルド時にHTMLにレンダリングされ、クライアント側のJavaScriptはゼロです。次の用途に最適です：

- レイアウトラッパー
- 静的なUI要素（ヘッダー、フッター、インタラクティビティのないサイドバー）
- 実行時の状態やDOMイベントが不要なもの全般

### クライアントハイドレートアイランド

コンポーネントがインタラクティビティを必要とする場合 — ローカル状態、イベントハンドラ、アニメーションなど — レンダリングする箇所でzfbの`Island()`ヘルパーでラップします。サーバーレンダリングの出力はそのまま使われ、インタラクティブな部分のみがハイドレートされます。

目次、モバイルTOC、サイドバーツリーとトグル、外観メニュー、doc-historyを含む標準のクロームアイランドは、`@takazudo/zudo-doc`が実装します。新しいscaffoldはこれらのパッケージコンポーネントを利用するため、ソースファイルのコピーは含まれません。

このショーケースには、`client-router-bootstrap`と`preset-generator`アイランドという、2つのプロジェクト固有の統合が残っています。Design Token Panel のブートストラップはパッケージ所有であり、静的な package route → chrome → derive のインポートチェーンを通じてアイランドスキャナーに到達します。これらは新しいプロジェクトの開始時に必要な一覧ではなく、ショーケースの実装詳細です。

scaffoldにプロジェクト所有の表示用コンポーネントまたはインタラクティブアイランドを追加する場合は、[カスタムコンポーネントガイド](https://zudo-doc.takazudomodular.com/ja/docs/guides/custom-components)に従ってください。`mdxExtras`による登録経路と、アイランド検出に必要な静的インポートのルートを説明しています。

クライアントハイドレートアイランドの用途：

- スクロールスパイ（TOCのハイライト）
- トグル・ドロワーコンポーネント
- ライブ編集パネル

### コンテンツタイポグラフィコンポーネント

コンテンツタイポグラフィはパッケージが所有します。`@takazudo/zudo-doc/content.css`が共有の`.zd-content`スタイルシートを提供し、パッケージのzudo-reactコンポーネントが主要なMDX HTMLオーバーライドをクライアントへのハイドレートなしにサーバーでレンダリングします。

デフォルトのコンポーネントマップは、見出し（h2〜h4）、段落、リンク、strong、ブロッククォート、リスト（ul/ol）、テーブルを対象にします。プロジェクトは`mdxExtras`を通じてこれらのbindingsをオーバーライドしたり、他のMDXコンポーネントを追加したりできます。

意図的にMDXレンダリングを変更する必要がある場合は`mdxExtras`を使います。共有のタイポグラフィ修正は、プロジェクトの`global.css`へ`.zd-content`ルールをコピーするのではなく、パッケージに置いてください。

## コンテンツ開発サイクル

新しいドキュメントページを追加する際は以下の手順に従ってください：

1. `src/content/docs/`以下に`title`と`sidebar_position`をフロントマターに含む`.mdx`ファイルを作成します。
2. `## h2`見出しからコンテンツを書き始めます。`# h1`は追加しません — フロントマターの`title`がページのh1としてレンダリングされます。
3. 設定した各追加ロケールディレクトリ（例: `src/content/docs-ja/` と `src/content/docs-de/`）以下に翻訳した対応ファイルを作成します。
4. プライマリと設定した各ロケールツリーのコードブロックは同一に保ちます — 翻訳するのは周囲のプロズのみです。
5. `pnpm format`を実行してMDXファイルをフォーマットします。
6. `pnpm build`を実行してサイトが正常にビルドされることを確認します。

[Dynamic content unavailable in text export]

フロントマターには必ず`sidebar_position`を設定してください。設定しないとページがアルファベット順に並び、意図した順序にならないことがほとんどです。



利用可能なフロントマターフィールドの一覧については[フロントマターリファレンス](https://zudo-doc.takazudomodular.com/ja/docs/guides/frontmatter)を参照してください。