開発ワークフロー
zudo-docの開発コマンド、ビルドツール、コンポーネント開発パターン。
開発コマンド
ローカル開発サーバーを起動するコマンドです。
| コマンド | 説明 |
|---|---|
pnpm dev | Astro開発サーバー（ポート4321）とdoc-history-server（ポート4322）を同時に起動 |
pnpm dev:astro | Astro開発サーバーのみ（ポート4321） |
pnpm dev:history | docヒストリーAPIサーバーのみ（ポート4322） |
pnpm dev:stable | ビルドしてからサーブする代替モード（コンテンツファイルの追加・削除時のHMRクラッシュを回避） |
pnpm dev:network | --host 0.0.0.0でAstro開発サーバーを起動（LAN経由アクセス用） |
💡 Tip
コンテンツファイルを頻繁に追加・削除する場合はpnpm dev:stableを使用してください。通常のpnpm devはVite HMRのファイルシステム変更でクラッシュすることがあります。
ビルド・品質コマンド
| コマンド | 説明 |
|---|---|
pnpm build | 静的HTMLをdist/にエクスポート |
pnpm check | Astro型チェック |
pnpm b4push | プッシュ前の検証：フォーマットチェック → 型チェック → ビルド → リンクチェック → E2Eテスト |
pnpm format | MDXおよびAstroファイルのフォーマット |
pnpm test:unit | ユニットテストを実行（Vitest） |
pnpm test:e2e | E2Eテストを実行（Playwright） |
📝 Note
プッシュ前にpnpm b4pushを実行して、サイト全体のビルド、すべてのリンクの解決、E2Eテストの通過を確認してください。開発サーバーが許容するドキュメント間の壊れたリンクやTypeScriptエラーを検出します。
コンポーネント開発
zudo-docは3つのコンポーネント階層を使用します。コンポーネントの要件に応じて適切な階層を選んでください。
Astroコンポーネント
.astroファイルはデフォルトの選択肢です — JavaScriptなし、ビルド時にサーバーレンダリングされます。
Astroコンポーネントの用途：
- レイアウトラッパー
- 静的なUI要素（ヘッダー、フッター、サイドバー）
- ユーザー操作が不要なもの全般
Preactアイランド
client:loadアイランドは、クライアントサイドのインタラクティビティが必要な場合にのみ使用します。Preactはcompatモード（@astrojs/preact with compat: true）で動作するため、コンポーネントはReact形式のインポートとAPIを使用できます。
プロジェクトの現在のアイランド：toc.tsx、mobile-toc.tsx、sidebar-toggle.tsx、sidebar-tree.tsx、theme-toggle.tsx、doc-history.tsx、color-tweak-panel.tsx、color-tweak-export-modal.tsx。
Preactアイランドの用途：
- スクロールスパイ（TOCのハイライト）
- トグル・ドロワーコンポーネント
- ライブ編集パネル
コンテンツタイポグラフィコンポーネント
src/に配置されたPreact関数コンポーネントで、client:ディレクティブを持ちません — クライアントJavaScriptなしでサーバーレンダリングされます。<Content components={...} />を通じてMDX内の標準HTMLエレメントをオーバーライドします。
現在のオーバーライド：見出し（h2〜h4）、段落、リンク、strong、ブロッククォート、リスト（ul/ol）、テーブル。
コンテンツタイポグラフィコンポーネントは、標準MDXのプロズ要素にプロジェクトのデザイントークンを適用したい場合に使用します。
コンテンツ開発サイクル
新しいドキュメントページを追加する際は以下の手順に従ってください：
src/以下にcontent/ docs/ titleとsidebar_positionをフロントマターに含む.mdxファイルを作成します。## h2見出しからコンテンツを書き始めます。# h1は追加しません — フロントマターのtitleがページのh1としてレンダリングされます。src/以下に日本語訳を含む対応ファイルを作成します。content/ docs- ja/ - ENとJAのコードブロックは同一に保ちます — 翻訳するのは周囲のプロズのみです。
pnpm format:mdxを実行してMDXファイルをフォーマットします。pnpm buildを実行してサイトが正常にビルドされることを確認します。
💡 Tip
フロントマターには必ずsidebar_positionを設定してください。設定しないとページがアルファベット順に並び、意図した順序にならないことがほとんどです。
利用可能なフロントマターフィールドの一覧についてはフロントマターリファレンスを参照してください。