開発ワークフロー
zudo-docの開発コマンド、ビルドツール、コンポーネント開発パターン。
開発コマンド
ローカル開発サーバーを起動するコマンドです。
| コマンド | 説明 |
|---|---|
pnpm dev | zfb開発サーバー（ポート4321）とdoc-history-server（ポート4322）を同時に起動 |
pnpm dev:zfb | zfb開発サーバーのみ（ポート4321） |
pnpm dev:history | docヒストリーAPIサーバーのみ（ポート4322） |
pnpm dev:zudo-doc | @takazudo/zudo-docパッケージのtsup --watch |
pnpm dev:stable | ビルドしてからサーブする代替モード（コンテンツファイルの追加・削除時のHMRクラッシュを回避） |
pnpm dev:network | --host 0.0.0.0でzfb開発サーバーを起動（LAN経由アクセス用） |
Tip
コンテンツファイルを頻繁に追加・削除する場合はpnpm dev:stableを使用してください。通常のpnpm devはVite HMRのファイルシステム変更でクラッシュすることがあります。
ビルド・品質コマンド
| コマンド | 説明 |
|---|---|
pnpm build | 静的HTMLをdist/にエクスポート |
pnpm check | TypeScript型チェック |
pnpm b4push | プッシュ前の検証：19ステップのパイプライン（フォーマットチェック → … → ビルド → リンクチェック → HTML検証 → プレビュースモーク）。E2Eはパーク中 |
pnpm format | MDXファイルのフォーマット |
pnpm test:unit | ユニットテストを実行（Vitest） |
pnpm test:e2e | E2Eテストを実行（Playwright） |
Note
プッシュ前にpnpm b4pushを実行して、サイト全体のビルドとすべてのリンクの解決を確認してください。19ステップ（フォーマットチェックからプレビュースモークまで）を実行します。E2Eテストは意図的にパークされており、このパイプラインには含まれていません。
b4pushのステップ一覧の正式・権威的な定義はscripts/の冒頭コメントにあります。このスクリプトを唯一の信頼できる情報源として扱い、ステップに食い違いがあるように見える場合は、インラインの要約ではなくスクリプトを参照してください。
コンポーネント開発
zudo-docはzfb上で動作するPreact専用プロジェクトです。すべてのコンポーネントは.tsxファイルです。区別すべき点は、コンポーネントがサーバーのみで動作するか、クライアントでもハイドレートされるかです。
サーバーレンダリングPreactコンポーネント
デフォルトでは、すべての.tsxコンポーネントはビルド時にHTMLにレンダリングされ、クライアント側のJavaScriptはゼロです。次の用途に最適です：
レイアウトラッパー
静的なUI要素（ヘッダー、フッター、インタラクティビティのないサイドバー）
実行時の状態やDOMイベントが不要なもの全般
クライアントハイドレートアイランド
コンポーネントがインタラクティビティを必要とする場合 — ローカル状態、イベントハンドラ、アニメーションなど — 自身のuseEffectやイベントバインディングコードを通じて、zfbのアイランドランタイムに登録します。サーバーレンダリングの出力はそのまま使われ、インタラクティブな部分のみがハイドレートされます。
プロジェクトの現在のアイランド：toc.tsx、mobile-toc.tsx、sidebar-toggle.tsx、sidebar-tree.tsx、theme-toggle.tsx、doc-history.tsx、zdtpパネル（Design Token Panel — @takazudo/zdtpパッケージのconfigurePanel()によるサイドエフェクトで自己マウントされ、アイランドレジストリへの登録は不要）、ai-chat-modal。
クライアントハイドレートアイランドの用途：
スクロールスパイ（TOCのハイライト）
トグル・ドロワーコンポーネント
ライブ編集パネル
コンテンツタイポグラフィコンポーネント
src/に配置されたPreact関数コンポーネントで、サーバー側でのみレンダリングされます — クライアントへのハイドレートはありません。doc-pageルートが利用する_mdx-components.tsマッピングを通じて、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ファイルをフォーマットします。pnpm buildを実行してサイトが正常にビルドされることを確認します。
Tip
フロントマターには必ずsidebar_positionを設定してください。設定しないとページがアルファベット順に並び、意図した順序にならないことがほとんどです。
利用可能なフロントマターフィールドの一覧についてはフロントマターリファレンスを参照してください。