開発ワークフロー
zudo-docの開発コマンド、ビルドツール、コンポーネント開発パターン。
新しいscaffoldのコマンド
create-zudo-docで作成したプロジェクトには、最初から次のスクリプトがあります：
| コマンド | 説明 |
|---|---|
pnpm dev | zfb開発サーバーを起動 |
pnpm build | 静的HTMLをdist/にエクスポート |
pnpm preview | ビルド済みのdist/出力をローカルでサーブ |
pnpm check | TypeScript型チェックを実行 |
Tip
選択した機能によって、生成される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経由アクセス用） |
Tip
ショーケースのコンテンツファイルを頻繁に追加・削除する場合はpnpm dev:stableを使用してください。通常のpnpm devはVite HMRのファイルシステム変更でクラッシュすることがあります。
ビルド・品質コマンド
| コマンド | 説明 |
|---|---|
pnpm build | 静的HTMLをdist/にエクスポート |
pnpm check | TypeScript型チェック |
pnpm b4push | プッシュ前の検証：23ステップのパイプライン（フォーマットチェック → … → Worker contract proof → ビルド → リンクチェック → HTML検証 → プレビュースモーク）。正確なステップ数はscripts/を正とする。E2Eは時間予算の都合でこのパイプラインには含まれず、CI（pr-checks）側で実行される |
pnpm format | MDXファイルのフォーマット |
pnpm test:unit | ユニットテストを実行（Vitest） |
pnpm test:e2e | E2Eテストを実行（Playwright） |
Note
プッシュ前にpnpm b4pushを実行して、サイト全体のビルドとすべてのリンクの解決を確認してください。フォーマットチェックからプレビュースモークまでの一連のステップを実行します。E2Eテストは時間予算の都合でCI（pr-checks）側で実行され、このパイプラインには含まれていません。
b4pushのステップ一覧の正式・権威的な定義はscripts/の冒頭コメントにあります。このスクリプトを唯一の信頼できる情報源として扱い、ステップに食い違いがあるように見える場合は、インラインの要約ではなくスクリプトを参照してください。
コンポーネント開発
zudo-docはzfb上で動作するPreact専用プロジェクトです。すべてのコンポーネントは.tsxファイルです。区別すべき点は、コンポーネントがサーバーのみで動作するか、クライアントでもハイドレートされるかです。
サーバーレンダリングPreactコンポーネント
デフォルトでは、すべての.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にプロジェクト所有の表示用コンポーネントまたはインタラクティブアイランドを追加する場合は、カスタムコンポーネントガイドに従ってください。mdxExtrasによる登録経路と、アイランド検出に必要な静的インポートのルートを説明しています。
クライアントハイドレートアイランドの用途：
スクロールスパイ（TOCのハイライト）
トグル・ドロワーコンポーネント
ライブ編集パネル
コンテンツタイポグラフィコンポーネント
コンテンツタイポグラフィはパッケージが所有します。@takazudo/が共有の.zd-contentスタイルシートを提供し、パッケージのPreactコンポーネントが主要なMDX HTMLオーバーライドをクライアントへのハイドレートなしにサーバーでレンダリングします。
デフォルトのコンポーネントマップは、見出し（h2〜h4）、段落、リンク、strong、ブロッククォート、リスト（ul/ol）、テーブルを対象にします。プロジェクトはmdxExtrasを通じてこれらのbindingsをオーバーライドしたり、他のMDXコンポーネントを追加したりできます。
意図的にMDXレンダリングを変更する必要がある場合はmdxExtrasを使います。共有のタイポグラフィ修正は、プロジェクトのglobal.cssへ.zd-contentルールをコピーするのではなく、パッケージに置いてください。
コンテンツ開発サイクル
新しいドキュメントページを追加する際は以下の手順に従ってください：
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を設定してください。設定しないとページがアルファベット順に並び、意図した順序にならないことがほとんどです。
利用可能なフロントマターフィールドの一覧についてはフロントマターリファレンスを参照してください。