## 使い方

```bash
create-zudo-doc [destination] [options]
```

フラグなしで実行すると、対話式ウィザードが起動します。すべてのオプションはフラグで指定でき、非対話的（CI/エージェント）に使用できます。

[セットアッププリセットジェネレーター](https://zudo-doc.takazudomodular.com/ja/docs/getting-started/setup-preset-generator)を使って、対話的に設定を構成し、JSON プリセットまたは CLI コマンドとしてコピーすることもできます。

### スキャフォールド先とプロジェクト名

最初の位置引数は**スキャフォールド先（destination）**、つまりプロジェクトを作成するディレクトリです。パスを渡すこともでき、その**最後のセグメント**が、生成される `package.json` に書き込まれるプロジェクト名になります。

```bash
# ./sub/ref-doc を作成し、パッケージ名は "ref-doc" になります
pnpm create zudo-doc sub/ref-doc --yes
```

プロジェクト名の文法（先頭は英小文字か数字、使えるのは英小文字・数字・ドット・アンダースコア・ハイフンのみ、最大 214 文字）が適用されるのは、この最後のセグメントだけです。その手前のディレクトリは単なるパスとして扱われるため、`Scratch-Dir/ref-doc` のような指定も通ります。

| destination | 作成されるディレクトリ | プロジェクト名 |
|-------------|----------------------|---------------|
| `my-docs` | `./my-docs` | `my-docs` |
| `sub/ref-doc` | `./sub/ref-doc` | `ref-doc` |
| `./sub/ref-doc/` | `./sub/ref-doc` | `ref-doc` |
| `../ref-doc` | `../ref-doc` | `ref-doc` |
| `/tmp/scratch/ref-doc` | `/tmp/scratch/ref-doc` | `ref-doc` |

上位ディレクトリへ遡る `../ref-doc` も、絶対パスも受け付けられます。拒否されるのは `.`、`..`、ファイルシステムのルート（`/`）で、プロジェクト名を導き出す最後のセグメントを持たないためです:

```text
Destination "." has no final path segment to name the project. Pass a destination whose last segment names the project, e.g. "sub/my-docs"
```

最後のセグメントがディレクトリ名としては妥当でも、パッケージ名の文法に反する場合は、そのセグメントを指すエラーになります:

```text
Invalid project name "My-Docs" — the last segment of destination "sub/My-Docs" is used as the package name. Project name must start with a lowercase letter or digit and contain only lowercase letters, digits, dots, underscores, and hyphens
```

`--name` を併用すると、ディレクトリは位置引数のまま、プロジェクト名だけを上書きできます。パッケージ名としては使えない名前のディレクトリにスキャフォールドしたい場合の手段です:

```bash
# ./sub/My-Docs を作成し、パッケージ名は "ref-doc" になります
pnpm create zudo-doc sub/My-Docs --name ref-doc --yes
```

`--name` に渡せるのは従来どおり素のパッケージ名だけで、パスを渡すと拒否されます。また `--name` を付けた場合でも、最後のセグメントを持たない destination は拒否されたままです。

## CLI が生成するもの

スキャフォールドは最小限で、ファイル数はおよそ12個です（[プロジェクト構成](https://zudo-doc.takazudomodular.com/ja/docs/getting-started/installation#%E3%83%97%E3%83%AD%E3%82%B8%E3%82%A7%E3%82%AF%E3%83%88%E6%A7%8B%E6%88%90)を参照）。レイアウト、クローム、スキーマはすべて `@takazudo/zudo-doc` から出荷され、`node_modules` から消費されるため、生成されるプロジェクトが持つのは本当に固有のものだけです。

機能の選択は**単一の `zfb.config.ts`** に `zudoDoc({ … })` 呼び出しとして書き込まれ、デフォルトと異なるフィールドだけを含みます（`siteName` は常に出力されます）。別個の `src/config/settings.ts` はありません — 唯一の設定ファイルが設定サーフェス全体です。各フィールドについては [設定](https://zudo-doc.takazudomodular.com/ja/docs/guides/configuration) を参照してください。

新しいスキャフォールドが意図的に**含まない**ものがいくつかあります:

- **`.zudo-doc.json` なし** — eject のプロベナンスファイルは最初の `zudo-doc eject` 時に遅延生成されるため、eject していないプロジェクトはこれを持ちません。
- **`check:html` / HTML バリデーション**ステップと **`gen:z-index` / `check:z-index`** コードジェネレーションなし — どちらも生成プロジェクトから削除されました。デフォルトの z-index ティアはパッケージから出荷され、HTML バリデーションと pre-push スイートはオプトインの追加項目です（[カスタマイズ](https://zudo-doc.takazudomodular.com/ja/docs/reference/customizing)の pre-push / HTML バリデーション復元の節を参照）。
- **デプロイアダプターや `wrangler.toml` なし** — デフォルトのビルドは純粋な静的エクスポートです。デプロイ（や AI アシスタントのような SSR 機能の有効化）は明示的な拡張ステップです。

[Dynamic content unavailable in text export]

`@takazudo/zdtp` は、**`designTokenPanel` を有効化した場合にのみ**追加されます。これは `@takazudo/zudo-doc` の*オプショナル*なピア依存であり、パネルを無効にしたプロジェクトにはインストールされません。パッケージのクロームは引き続きパネルのブートストラップ*モジュール*をモジュールスコープでインポートしますが（zfb のアイランドスキャナーがそれを見つけられるようにするためです）、そのモジュールが `@takazudo/zdtp` に到達する経路は、最初の利用時の拒否ハンドリング付き動的 `import()` だけです（[遅延読み込み](https://zudo-doc.takazudomodular.com/ja/docs/reference/design-token-panel#%E5%AE%9F%E8%A3%85-%E9%81%85%E5%BB%B6%E8%AA%AD%E3%81%BF%E8%BE%BC%E3%81%BF)を参照）。この動的インポートはパッケージが存在しなくてもバンドラーが許容するため、パネルなしのプロジェクトはインストールせずにビルドできます。パネルなしでスキャフォールドしたプロジェクトで後から `designTokenPanel` を有効化する場合は、`@takazudo/zdtp` を自分でインストールし、`src/styles/global.css` に `@import "@takazudo/zdtp/styles.css";` を追加してください。



## カラースキーム

zudo-doc が同梱するカラースキームは `Default Light` と `Default Dark` の 2 つだけで、両者は 1 セットの OKLCH ランプを共有しています。`--scheme` の値として選べる、コミュニティ製やターミナル由来のプリセットカタログはバンドルされていません。

カスタマイズはもう一段深いレイヤー、`zfb.config.ts` の `colorSchemes` エスケープハッチフィールドで行います。独自の `{ ramps, map }` パレットマップを `zudoDoc({ colorSchemes: { … } })` に渡します（[Color](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#ai%E3%83%AF%E3%83%BC%E3%82%AF%E3%83%95%E3%83%AD%E3%83%BC) の Palette タブで結果をライブプレビューできます（[カラースキームプレビュー](https://zudo-doc.takazudomodular.com/ja/docs/guides/color-scheme-preview)を参照）。

## テーマパック

カラースキームとは独立に、スキャフォールドは同梱の[テーマパック](https://zudo-doc.takazudomodular.com/ja/docs/reference/theme-packs) — スキームシステムの上に重なる完成済みデザインバンドル — を起点にしたプロジェクトを生成できます。`--theme-pack <slug>` を渡すか、対話式の「Theme pack:」プロンプト（カラースキームの質問と機能のマルチセレクトの間に表示されます）で答えます。選んだスラッグは生成される `zfb.config.ts` の `themePack` に書き込まれます（デフォルト差分のみ出力する規則に従い、`default` と異なる場合のみ）。ページ内のスイッチャー UI は独立した機能トグル `--theme-pack-switcher` です。

## オプション

### プロジェクト

| フラグ | 説明 | デフォルト |
|--------|------|-----------|
| `[destination]` | スキャフォールド先のディレクトリ（最初の位置引数）。パスも指定でき、その最後のセグメントがプロジェクト名になる | `my-docs` |
| `--name <name>` | 生成される `package.json` に書き込まれるプロジェクト名。destination の最後のセグメントから導出される名前を上書きする | destination の最後のセグメント |
| `--lang <code>` | デフォルト言語コード | `en` |
| `--additional-langs <a,b>` | 追加ロケールコード（順序付き）。i18n を有効にし、プリセットのリストを置き換える | — |
| `--changelog-packages <a,b>` | ネストした変更履歴ランディングページと、カンマ区切りの各スラッグに対応するパッケージインデックスを生成 | — |
| `--github-url <url>` | GitHub リポジトリ URL（ヘッダーリンク + ソースリンクに使用） | — |
| `--pm <manager>` | パッケージマネージャー: `pnpm`, `npm`, `yarn`, `bun` | `pnpm` |
| `--[no-]install` | スキャフォールディング後に依存関係をインストール | プロンプト |
| `--[no-]git` | git リポジトリと初回コミットを初期化（doc-history メタデータを有効化） | オン |

`--changelog-packages core,cli`は`--changelog`を暗黙的に有効にし、マルチパッケージ用の変更履歴レイアウトを生成します。

### カラースキーム

| フラグ | 説明 | デフォルト |
|--------|------|-----------|
| `--color-scheme-mode <mode>` | `single` または `light-dark` | `light-dark` |
| `--scheme <name>` | カラースキーム（single モード） | `Default Dark` |
| `--light-scheme <name>` | ライトスキーム（light-dark モード） | `Default Light` |
| `--dark-scheme <name>` | ダークスキーム（light-dark モード） | `Default Dark` |
| `--default-mode <mode>` | `light` または `dark`（light-dark モード） | `dark` |
| `--[no-]respect-system-preference` | OS のカラースキーム設定を尊重 | `true` |

デフォルトで有効な `--respect-system-preference` では、保存済みの選択がない初回訪問時に System が選ばれ、デバイス設定に従います。System に従わない場合も、`defaultMode` はライト/ダークのフォールバックとして維持されます。選択の保存方法と外観メニューについては [Color リファレンス](https://zudo-doc.takazudomodular.com/ja/docs/reference/color) を参照してください。

### テーマパック

| フラグ | 説明 | デフォルト |
|--------|------|-----------|
| `--theme-pack <slug>` | 生成プロジェクトに適用するテーマパック — 指定できるスラッグは[テーマギャラリー](https://zudo-doc.takazudomodular.com/ja/docs/reference/theme-gallery)を参照 | `default` |

### 機能

| フラグ | 説明 | デフォルト |
|--------|------|-----------|
| `--[no-]i18n` | 旧来の多言語トグル。リストがない場合は追加ロケールを1つ推論 | オフ |
| `--[no-]search` | 生成された `search-index.json` を使った組み込みの全文/ワードマッチ検索 | オン |
| `--[no-]sidebar-filter` | サイドバーのリアルタイムフィルタリング | オン |
| `--[no-]claude-resources` | Claude Code ドキュメント生成 | オフ |
| `--[no-]codex-resources` | Codex ドキュメント生成 | オフ |
| `--[no-]claude-skills` | zudo-doc-* Claude Code スキルを同梱（design-system、translate、version-bump） | オフ |
| `--[no-]claude-skills-writing` | zudo-doc-writing スキルを同梱（AI 支援執筆向けのドキュメント執筆 + ナビゲーション構造ガイド） | オフ |
| `--[no-]design-token-panel` | スペーシング・フォント・サイズ・カラーの各トークンを編集するタブ型パネル | オフ |
| `--[no-]theme-pack-switcher` | インストール済みテーマパックを切り替える右下のフライアウト（と一覧ダイアログ） | オフ |
| `--[no-]sidebar-resizer` | ドラッグでサイドバー幅を変更 | オン |
| `--[no-]sidebar-toggle` | デスクトップサイドバーの表示/非表示 | オン |
| `--[no-]toc-toggle` | デスクトップ目次の表示/非表示（xl 画面の端のシェブロン） | オン |
| `--[no-]versioning` | 複数バージョンのドキュメント対応 | オフ |
| `--[no-]doc-history` | ドキュメント編集履歴 | オン |
| `--[no-]body-foot-util` | ドキュメント下部の右寄せストリップ: ドキュメント履歴トリガー + GitHub でソースを表示リンク | オフ |
| `--[no-]llms-txt` | LLM 向け llms.txt を生成 | オン |
| `--[no-]agent-export` | バージョン付きの静的なエージェント向けコーパスを公開 | オフ |
| `--[no-]mcp` | 読み取り専用のMCP `search`と`fetch`ツールを追加 | オフ |
| `--mcp-deploy cloudflare` | MCP用のCloudflare Workersデプロイ設定。MCPが必要 | — |
| `--[no-]skill-symlinker` | ドキュメントスキルをClaude CodeまたはCodexへシンボリックリンク | オフ |
| `--[no-]tauri` | Tauri デスクトップアプリ（Mode 1）— ページ内検索付き macOS オフラインリーダー | オフ |
| `--[no-]tauri-dev` | Tauri 開発ラッパー（Mode 2）— 任意プロジェクト向けの設定可能なデスクトップ開発ラッパー | オフ |
| `--[no-]footer-nav-group` | フッターのナビゲーションリンク | オフ |
| `--[no-]image-enlarge` | マークダウン画像のクリック拡大表示 | オン |
| `--[no-]asset-viewer` | public/assets 配下のファイル向けの閲覧ページ | オン |
| `--[no-]dynamic-page-transition` | 履歴管理付きのSPA風ページ遷移 | オン |
| `--[no-]footer-copyright` | フッターの著作権表示 | オン |
| `--[no-]changelog` | 変更履歴ページ | オフ |
| `--[no-]tag-governance` | 語彙対応タグ監査・サジェストスクリプト | オフ |
| `--[no-]doc-tags` | タグ別・タグ一覧の閲覧ルート（docs/tags/...） | オフ |
| `--[no-]footer-taglist` | フッターのグループ化されたタグ一覧（tagGovernance が必要） | オフ |
| `--[no-]noindex` | ロボットによるインデックスを回避 — noindex メタ + robots.txt | オフ |

### プリセット

| フラグ | 説明 |
|--------|------|
| `--preset <path>` | JSON プリセットファイルから設定を読み込み（`"-"` で標準入力） |

`--preset` フラグは[セットアッププリセットジェネレーター](https://zudo-doc.takazudomodular.com/ja/docs/getting-started/setup-preset-generator)の JSON 出力を受け付けます。プリセットを読み込むと、すべてのプロンプトがスキップされます（`--yes` と同様）。個別の CLI フラグはプリセットの値を上書きします。特に `--additional-langs ja,de` はプリセットの `additionalLangs` リストに追加するのではなく置き換えます。空でない明示リストは、プリセットまたは CLI に `--no-i18n` が含まれていても i18n を有効にします。明示的な無効化を上書きする場合、CLI は警告を表示します。

### エージェント向けエクスポートとMCPの選択肢

JSONプリセットとプログラムAPIでは、`agentExport`と`mcp`を機能キーとして指定します。`mcpDeploy`はイニシャライザー専用のトップレベルのプロパティで、対応する値は`"cloudflare"`だけです。`zudoDoc`のパッケージ設定ではありません。対話式プロンプトとCLIフラグでも同じ選択ができます。MCPを指定してエクスポートを省略すると自動的に有効になり、デプロイ先を省略するとCloudflareが選ばれます。生成される設定には両方が明示されます。`--yes`、barebone、従来の簡易プリセットでは、指定しない限り両機能は無効です。イニシャライザーの`llmsTxt`既定値は引き続き有効です。

```json
{
  "features": ["agentExport", "mcp"],
  "mcpDeploy": "cloudflare"
}
```

```bash
pnpm create zudo-doc my-docs --mcp --mcp-deploy cloudflare --yes
```

プログラムAPIの`createZudoDoc`でも、`features: ["agentExport", "mcp"]`と`mcpDeploy: "cloudflare"`を同じ検証規則で指定できます。エクスポートを明示的に無効化しながらMCPを有効化すると、ファイル書き込み前に拒否されます。MCPなしのデプロイ先指定も拒否され、未対応の値はMCPが無効でも拒否されます。エラーは次のとおりです。

```text
MCP requires agentExport: true. Remove the explicit agent export disable or disable MCP.
Unsupported mcpDeploy value. Supported value: cloudflare.
mcpDeploy requires mcp: true. Enable MCP or remove mcpDeploy.
```

ビルド成果物、デプロイ、既存プロジェクトへの追加方法は[エージェント向けエクスポート](https://zudo-doc.takazudomodular.com/ja/docs/guides/agent-export)と[MCPサーバー](https://zudo-doc.takazudomodular.com/ja/docs/guides/mcp-server)を参照してください。

### 一般

| フラグ | 説明 |
|--------|------|
| `-y, --yes` | 未指定オプションにデフォルトを使用し、プロンプトをスキップ |
| `-h, --help` | ヘルプメッセージを表示 |

## サポート言語

`--lang` フラグは以下の言語コードを受け付けます:

| コード | 言語 |
|--------|------|
| `en` | 英語 |
| `ja` | 日本語 |
| `zh-cn` | 中国語（簡体字） |
| `zh-tw` | 中国語（繁体字） |
| `ko` | 韓国語 |
| `es` | スペイン語 |
| `fr` | フランス語 |
| `de` | ドイツ語 |
| `pt` | ポルトガル語 |

`--lang` はルートページ（`/docs/...`）で使用するプライマリロケールを選択します。`--lang en --additional-langs ja,de` のように任意の数の追加ロケールコードを渡せます。それぞれに `src/content/docs-<code>/` ツリーと `/<code>/docs/...` ルートが作成されます。順序は生成される設定と言語切り替えで保持され、ラベルは `JP`/`JA` のような固定値ではなく設定したロケールマップから取得されます。

`--additional-langs` を省略する、対話 UI で空欄にする、またはプリセットで `additionalLangs` を省略すると単一ロケールのプロジェクトになります。`i18n: true` だけを指定する旧来のプリセットまたは API 呼び出しでは互換推論が残り、プライマリが `en` なら `ja`、それ以外なら `en` が推論されます。明示したロケールコードは小文字化され、パス/URL で安全に使える形式に検証されます。無効なコード、区切り文字、トラバーサル要素、重複、プライマリコードはファイル書き込み前に拒否されます。

`ja` ツリーには日本語のスターター文章が配置されます。それ以外の任意の追加ロケールには、公開前に翻訳すべき英語のプレースホルダー文章が配置されます。組み込み UI 翻訳は `要求されたロケール → 設定済みデフォルトロケール → パッケージの英語 → 生の UI 文字列キー` の順に解決されます。

## 使用例

### 対話モード

```bash
pnpm create zudo-doc
```

### すべてデフォルトで非対話的に実行

```bash
pnpm create zudo-doc my-docs --yes
```

### サブディレクトリへのスキャフォールド

```bash
pnpm create zudo-doc sub/ref-doc --yes
```

`sub/ref-doc/` を作成し、パッケージ名は `ref-doc` になります。1 つの作業用ディレクトリの下に複数のプロジェクトを並べて生成したいとき（たとえば 2 つのテンプレートバージョンを diff で比較したいとき）に便利です。

### 日本語サイト、単一ダークスキーム

```bash
pnpm create zudo-doc my-docs --lang ja --scheme "Default Dark" --no-i18n --pm pnpm --install
```

### 明示的なデフォルトモードを指定した Light/Dark モード

```bash
pnpm create zudo-doc my-docs \
  --color-scheme-mode light-dark \
  --default-mode light \
  --no-respect-system-preference \
  --yes
```

### プリセットファイルの使用

[セットアッププリセットジェネレーター](https://zudo-doc.takazudomodular.com/ja/docs/getting-started/setup-preset-generator)で JSON プリセットを生成し、ファイルに保存してから CLI に渡します:

```bash
pnpm create zudo-doc --preset setup.json --install
```

標準入力から JSON を直接パイプすることもできます:

```bash
cat setup.json | pnpm create zudo-doc --preset - --install
```

### CI/自動化での使用

```bash
pnpm create zudo-doc my-docs \
  --lang en \
  --scheme "Default Dark" \
  --no-i18n \
  --search \
  --no-claude-resources \
  --no-codex-resources \
  --pm pnpm \
  --install \
  --yes
```

## プログラム API

パッケージはプログラム API もエクスポートしています。オプションオブジェクトは JSON プリセットと同じフィールドに加え、`install` と `git` オプションを受け付けます。プログラム API ではどちらもデフォルトで `false` です。`destination` オプションはありません。スキャフォールド先のパスは CLI レベルの概念であり、プログラム API ではカレントディレクトリを基準に `projectName` がそのままディレクトリ名を兼ねます:

```ts
import { createZudoDoc } from "create-zudo-doc";

await createZudoDoc({
  projectName: "my-docs",
  defaultLang: "en",
  colorSchemeMode: "light-dark",
  lightScheme: "Default Light",
  darkScheme: "Default Dark",
  defaultMode: "dark",
  respectPrefersColorScheme: true,
  themePack: "foundry",
  features: [
    "search",
    "sidebarFilter",
    "sidebarResizer",
    "sidebarToggle",
    "tocToggle",
    "docHistory",
    "footerCopyright",
  ],
  cjkFriendly: false,
  minifyHtml: true,
  headerRightItems: [
    { type: "component", component: "theme-toggle" },
    { type: "component", component: "github-link" },
  ],
  metaTags: {
    description: true,
    ogImage: "/img/ogp.png",
  },
  packageManager: "pnpm",
  install: true,
  git: true,
});
```

`headerRightItems`（[Header Right Items ガイド](https://zudo-doc.takazudomodular.com/ja/docs/guides/header-right-items)を参照）と `metaTags`（[設定](https://zudo-doc.takazudomodular.com/ja/docs/guides/configuration#%E3%82%A2%E3%82%A4%E3%83%87%E3%83%B3%E3%83%86%E3%82%A3%E3%83%86%E3%82%A3%E3%81%A8-url-metatags)を参照）は、同名の JSON プリセットフィールドと同じ形式を受け付け、同じルールで検証されます — 未知の `headerRightItems` コンポーネント/トリガー名や不正な `metaTags` サブフィールドの型は、スキャフォールド開始前に例外をスローします。