create-zudo-doc CLI

create-zudo-doc プロジェクトスキャフォルダーの完全な CLI リファレンス。

使い方

create-zudo-doc [destination] [options]

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

セットアッププリセットジェネレーターを使って、対話的に設定を構成し、JSON プリセットまたは CLI コマンドとしてコピーすることもできます。

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

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

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

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

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

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

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

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

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

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

CLI が生成するもの

スキャフォールドは最小限で、ファイル数はおよそ12個です（プロジェクト構成を参照）。レイアウト、クローム、スキーマはすべて @takazudo/zudo-doc から出荷され、node_modules から消費されるため、生成されるプロジェクトが持つのは本当に固有のものだけです。

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

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

• .zudo-doc.json なし — eject のプロベナンスファイルは最初の zudo-doc eject 時に遅延生成されるため、eject していないプロジェクトはこれを持ちません。

• check:html / HTML バリデーションステップと gen:z-index / check:z-index コードジェネレーションなし — どちらも生成プロジェクトから削除されました。デフォルトの z-index ティアはパッケージから出荷され、HTML バリデーションと pre-push スイートはオプトインの追加項目です（カスタマイズの pre-push / HTML バリデーション復元の節を参照）。

• デプロイアダプターや wrangler.toml なし — デフォルトのビルドは純粋な静的エクスポートです。デプロイ（や AI アシスタントのような SSR 機能の有効化）は明示的な拡張ステップです。

カラースキーム

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

カスタマイズはもう一段深いレイヤー、zfb.config.ts の colorSchemes エスケープハッチフィールドで行います。独自の { ramps, map } パレットマップを zudoDoc({ colorSchemes: { … } }) に渡します（Color の「カスタムカラースキームの追加」を参照）。ソースにコミットする前に Design Token Panel の Palette タブで結果をライブプレビューできます（カラースキームプレビューを参照）。

テーマパック

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

オプション

プロジェクト

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

カラースキーム

テーマパック

機能

プリセット

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

一般

サポート言語

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

--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 文字列キー の順に解決されます。

使用例

対話モード

pnpm create zudo-doc

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

pnpm create zudo-doc my-docs --yes

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

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

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

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

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

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

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

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

セットアッププリセットジェネレーターで JSON プリセットを生成し、ファイルに保存してから CLI に渡します:

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

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

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

CI/自動化での使用

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 がそのままディレクトリ名を兼ねます:

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 ガイドを参照）と metaTags（設定を参照）は、同名の JSON プリセットフィールドと同じ形式を受け付け、同じルールで検証されます — 未知の headerRightItems コンポーネント/トリガー名や不正な metaTags サブフィールドの型は、スキャフォールド開始前に例外をスローします。