## 前提条件 - **Node.js 22+** — zfbおよびツールチェーンに必要 - **pnpm** — 推奨パッケージマネージャー [Dynamic content unavailable in text export] npm、yarn、bun も使用できますが、このガイドでは pnpm を使用します。 ## 新規プロジェクトの作成 `create-zudo-doc` CLI を使うと、対話式のセットアップウィザードで新規プロジェクトをすばやく作成できます。 ```bash pnpm create zudo-doc ``` 他のパッケージマネージャーの場合: ```bash npm create zudo-doc yarn create zudo-doc bunx create-zudo-doc ``` 非対話的な使用（CI、自動化、AI エージェント）では、`--yes` でデフォルトを使用するか、フラグを直接指定できます: ```bash pnpm create zudo-doc my-docs --yes pnpm create zudo-doc my-docs --lang ja --scheme "Default Dark" --no-i18n --pm pnpm --install ``` すべてのフラグについては [CLI リファレンス](https://zudo-doc.takazudomodular.com/ja/docs/reference/create-zudo-doc) を参照してください。 CLI では以下のオプションを順番に設定します。 ### プロジェクト名 プロジェクトディレクトリの名前を入力します（デフォルト: `my-docs`）。 ### デフォルト言語 ドキュメントサイトのデフォルト言語を選択します。英語、日本語、中国語（簡体字/繁体字）、韓国語、スペイン語、フランス語、ドイツ語、ポルトガル語がサポートされています。 選択した言語がプライマリロケールです。コンテンツは`src/content/docs/`に置かれ、ルートはプレフィックスなし（`/docs/...`）で配信されます。追加ロケールはPreset Generatorの**Additional language codes**にカンマ区切りの順序付きリストで入力するか、CLIに直接渡します。 ```ts title="zfb.config.ts" export default defineConfig( zudoDoc({ defaultLocale: "en", locales: { ja: { label: "JA", dir: "src/content/docs-ja" }, de: { label: "DE", dir: "src/content/docs-de" }, }, }), ); ``` ```bash pnpm create zudo-doc my-docs --lang en --additional-langs ja,de --yes ``` リストを省略または空欄にすると単一言語のスキャフォールドになります。空でない明示リストは安全なロケールパスセグメントとして正規化・検証され、自動的にi18nを有効にします。固定数の追加ロケールを指定する仕組みではなく、これが完全なロケール一覧です。日本語以外の任意のロケールには英語のプレースホルダー文章が配置されるため、インストール後に翻訳してください。 ### カラースキームモード サイトのカラースキーム設定を選択します。 - **Light & Dark（トグル）** — ユーザーがライトとダークテーマを切り替え可能。同梱の `Default Light` / `Default Dark` ペアを使用します。 - **Single scheme** — サイト全体で1つの固定カラースキーム。`Default Light` または `Default Dark` のいずれかです。 Light/Dark モードでは、デフォルトモード（ライトまたはダーク）の設定や、ユーザーのシステムカラースキーム設定を尊重するかどうかも選択できます。 zudo-doc が同梱するのはこの 2 つのスキームだけで、両者は 1 セットの OKLCH ランプを共有しています。ブラウズできるコミュニティ製やターミナル由来のプリセットカタログはありません。デフォルトはパッケージが所有しており、新しいスキャフォールドにはカラースキームモジュールがありません。パレットをカスタマイズするには独自のスキームモジュールを作成し、`zfb.config.ts` の `zudoDoc({ ... })` の `colorSchemes` フィールドで渡します（[カラーガイド](https://zudo-doc.takazudomodular.com/ja/docs/reference/color#%E3%82%AB%E3%82%B9%E3%82%BF%E3%83%A0%E3%82%AB%E3%83%A9%E3%83%BC%E3%82%B9%E3%82%AD%E3%83%BC%E3%83%A0%E3%81%AE%E8%BF%BD%E5%8A%A0)を参照）。その後、[Design Token Panel](https://zudo-doc.takazudomodular.com/ja/docs/reference/design-token-panel) の Palette タブで変更をライブプレビューできます（[カラースキームプレビュー](https://zudo-doc.takazudomodular.com/ja/docs/guides/color-scheme-preview)を参照）。 ### 機能選択 対話式ピッカーで、検索とサイドバーツール、Claude / Codex リソースとスキル、デザインとナビゲーションの操作、バージョニングとドキュメント履歴、タグと変更履歴、デスクトップラッパー、インデックス制御のオプションモジュールを選択します。国際化はプライマリ言語と**Additional language codes**で設定し、追加リストが空でなければ自動的に有効になります。組み込みの全文/ワードマッチ検索、サイドバーフィルター、画像拡大、動的ページ遷移、フッター著作権表示はデフォルトで選択されています。 機能の完全な一覧、デフォルト、非対話的なフラグは [CLI リファレンス](https://zudo-doc.takazudomodular.com/ja/docs/reference/create-zudo-doc#%E3%82%AA%E3%83%97%E3%82%B7%E3%83%A7%E3%83%B3-%E6%A9%9F%E8%83%BD) を参照してください。 ### パッケージマネージャー 使用するパッケージマネージャーを選択します: pnpm（推奨）、npm、yarn、bun。スキャフォールディング後に依存関係をインストールするか確認されます。 [Dynamic content unavailable in text export] インストーラーは選択内容を単一の `zfb.config.ts` に書き込みます。これはデフォルトと異なるフィールドだけを持つ `zudoDoc({ … })` 呼び出しです。プロジェクト作成後にいつでも設定を変更できます。全フィールドのリファレンスは [設定](https://zudo-doc.takazudomodular.com/ja/docs/guides/configuration) を参照してください。 ## 代替方法: リポジトリのクローン リポジトリを直接クローンして始めることもできます。 ```bash git clone https://github.com/zudolab/zudo-doc.git my-docs cd my-docs pnpm install ``` [Dynamic content unavailable in text export] リポジトリのクローンでは、ドキュメントソースとすべての機能が含まれた完全なプロジェクトが取得できます。コードベース全体を確認したい場合や、zudo-doc 自体に貢献したい場合にこの方法を使用してください。 ## 開発 ```bash pnpm dev ``` zfb 開発サーバーがインスタントなホットモジュールリプレースメントとともにポート4321で起動します。 [Dynamic content unavailable in text export] ポート4321が使用可能であることを確認してください。別のプロセスがすでに使用中の場合、`pnpm dev`は`EADDRINUSE`で失敗します。競合するプロセスを終了してから再試行してください。 ## ビルド ```bash pnpm build ``` `dist/` ディレクトリに静的HTMLが生成されます。任意の静的ホスティングサービスにデプロイできます。 ## 型チェック ```bash pnpm check ``` プロジェクトのTypeScript型チェッカーをstrictモードで実行します。 [Dynamic content unavailable in text export] `dist/` ディレクトリはソース管理にコミットしないでください。`.gitignore` で除外済みです。 ## プロジェクト構成 新しくスキャフォールドされたプロジェクトは意図的に小さく、ファイル数はおよそ12個です: ``` my-docs/ ├── .gitignore # node_modules, dist, .zfb ├── .npmrc # trust-policy-exclude[]=undici-types@6.21.0 ├── pnpm-workspace.yaml # minimumReleaseAge: 0 (disables pnpm 11's release-age gate) ├── CLAUDE.md # project notes for Claude Code ├── package.json # deps + dev/build/preview/check scripts ├── tsconfig.json # 5-line extends of the package base config ├── zfb.config.ts # the ONE config file — a zudoDoc({ … }) call ├── pages/ │ ├── index.tsx # home route (1-line re-export) │ └── docs/ │ └── [[...slug]].tsx # doc-route stub (see the callout below) └── src/ ├── content/ │ └── docs/ │ └── getting-started/ │ ├── index.mdx │ ├── installation.mdx │ └── introduction.mdx └── styles/ └── global.css # ~20-line @import chain + your token overrides ``` 追加ロケールを設定すると、`src/content/`にはエントリごとに`docs-/`ディレクトリも作成されます（例: `docs-ja/`と`docs-de/`）。翻訳時もファイル名とコードブロックを各ツリーで揃えてください。フォールバック、検証、デフォルトロケール専用ルールは[国際化](https://zudo-doc.takazudomodular.com/ja/docs/guides/i18n)を参照してください。 | ファイル | 役割 | | --- | --- | | `zfb.config.ts` | プロジェクト全体の設定。`@takazudo/zudo-doc/config` から `zudoDoc` をインポートし、選んだフィールドを渡します。それ以外はすべて文書化されたデフォルトにフォールバックします。 | | `tsconfig.json` | `@takazudo/zudo-doc/tsconfig.base.json`をextendsし、JSX sourceは`@takazudo/zfb/zudo-react`です。React/Preact互換エイリアスはありません。 | | `src/styles/global.css` | パッケージの `theme.css` / `content.css` / `features.css` を `@import` し、トークン上書き用に `:root { … }` ブロックを残します。 | | `src/content/docs/` | MDX で書くドキュメント本体。スキャフォールドは差し替え用に `getting-started/` ページをいくつかシードします。 | | `pages/index.tsx`, `pages/docs/[[...slug]].tsx` | 薄いルートスタブ — 下記を参照。 | ### なぜこんなに少ないのか プロジェクトが以前は自身にコピーしていたもの — レイアウト、ヘッダー、サイドバー、TOC、ナビゲーションビルダー、URL ヘルパー、カラースキームユーティリティ、フロントマタースキーマ — は、いまや `@takazudo/zudo-doc` から出荷され、`node_modules` から直接消費されます。ドキュメントルートはパッケージによって注入され（`packageOwnedRoutes` はデフォルトで `true`）、そのため `pages/` ディレクトリには一式のレイアウトファイルではなく下記の2つのスタブだけが残ります。新しいプロジェクトが持つのは、本当に固有のものだけ — 設定、コンテンツ、そしていくつかのルートシームです。 [Dynamic content unavailable in text export] ホームルートは、パッケージ所有の静的インデックスルートを1行で re-export したものです: ```tsx title="pages/index.tsx" export { default } from "@takazudo/zudo-doc/routes/index"; ``` 静的な `/` ルートはビルド時の `paths()` 抽出を必要としないため、この re-export 形式が使えます。 [Dynamic content unavailable in text export] zfb 2.13.1 では、パッケージのルート注入が **build** と **dev** の両方でドキュメントページをレンダリングします。この小さな自己完結型スタブは、明示的なホスト所有のルートシームとして残っています。パッケージの認可されたエントリーポイント（`@takazudo/zudo-doc/route-context` + `/chrome` + `virtual:zudo-doc-route-context` モジュール）からルートを再構築し、生成されたプロジェクトがパッケージ注入をシャドーしながらこのルートをカスタマイズできるようにします。これにより `/docs/…` は `zfb dev` と `zfb build` の両方で 200 を返します。 ドキュメントページの作成と整理方法については [ドキュメントの書き方](https://zudo-doc.takazudomodular.com/ja/docs/getting-started/writing-docs) ガイドを、設定の微調整から完全なソース制御までのはしごについては [zudo-doc のカスタマイズ](https://zudo-doc.takazudomodular.com/ja/docs/reference/customizing) を参照してください。